diff --git a/Basic/Pod/DeveloperGuide.pod b/Basic/Pod/DeveloperGuide.pod new file mode 100644 index 000000000..36f0e96df --- /dev/null +++ b/Basic/Pod/DeveloperGuide.pod @@ -0,0 +1,248 @@ +=head1 NAME + +PDL::DeveloperGuide - How to develop for PDL + +=head1 Public Git Repository + +The PDL source distribution is hosted with L at the GitHub +site L, alongside with other PDL +related software. + +This is the preferred place to submit bug reports or, even better, +pull requests. + +=head1 PDL Developer Guidelines + +The following guidelines are for any developer that has +access to the PDL Git repository. + +=over + +=item 1) Add new files to the inventory + +Before committing a change with new files to the repository +you should update: + + - MANIFEST (if files were added, using 'make manifest') + - MANIFEST.SKIP (if applicable) + +=item 2) Add tests + +Make sure you add a test case in the 't' directory for any +significant additional capability you add to PDL. Please +use L or one the of the Test modules available via +perl modules rather than doing-it-yourself! + +=item 3) Add documentation + +Please include POD documentation for any functions you add to +the distribution. + +=item 4) Run the tests + +Don't commit before you successfully built and passed +C. + +=item 5) Watch for bug reports + +Bugs should be reported to the GitHub issue tracker at +L. See L for a +detailed description. + +=item 6) PDL Developer Recommended Workflow + +This is detailed in section 4.11 of L. + +=back + +=head1 PDL Developer Notes + +=head2 Random Musings + +A (small) collection of random musings to note if you feel +the need to improve or add to PDL (please do): + +=over + +=item Organizing Commits + +git supports file-by-file commits so it is helpful +to commit your changes to git a little at a time where +each commit corresponds to a single change. This makes +it easy in the log to determine what was done and to +locate any desired commit in case of issues that need +to be resolved. + +=item Access to PDL's configuration + +If you need to access the configuration for PDL then use the +C<%PDL::Config> variable. Prior to 2.4.1 this was a mess since +you had to use %PDL_CONFIG within Makefile.PL and PDL::Config +from *.pm/tests. The build process has been changed (I hesitate +to say "cleaned up" ;) to just use %PDL::Config consistently +throughout. + +=back + +=head2 Ingesting an external PDL module + +Notes on transferring an external PDL module to the PDL +source tree for distribution with PDL: + +Suppose you have developed a PDL module that resides in a +standalone source tree. You typically will need to have PDL +installed on your system before you can build this module. + +If you wish to migrate the module into the PDL distribution +you will need to make certain changes to the module source +in order to built in the PDL distribution. You will need to +removed dependecies on a pre-existing PDL installation for +configuration and build of your module. This is because as +part of the PDL distribution, it is possible that PDL has +never been installed. Build processes based on PDL will then +fail. + +Following is some specific advice that can help you do this. + +Changes that must be made to files in your module source tree +if you are building the module from a .pd file : + +B + +=over + +=item * + +You must remove the line 'use PDL::Core::Dev;'. + +=item * + +The line 'PDL::Core::Dev->import();' must be present + +=item * + +You must change the call from C to a call to +C (with the same arguments.) + +=item * + +It seems that most modules in the PDL source use + + VERSION_FROM => '../../Basic/PDL.pm', + +but not all of them in order that their version tracks +the PDL release version. It is possible to maintain +separate versioning even within the PDL source tree but +it may make things confusing. + +=back + +Make certain that you make these changes to each 'Makefile.PL' in +your source tree. + + +B + +=over + +=item * + +Edit the 'Makefile.PL' in the directory above your module source +to add your module directory name to +C [ qw/Module1 AnotherModule / ]>. + +=item * + +Add your test files (.t files) to the PDL/t directory renaming if +required to avoid namespace conflicts. + +=item * + +Does your module depend on any libraries or external +programs ? If so, doocument the required programs with version +numbers in PDL/DEPENDENCIES and add the PREREQ_* option to the +main Makefile.PL if required. + +=item * + +If your module requires external libraries or header files, +add a section to perldl.conf. The hash values with be available +in your module's 'Makefile.PL' as $PDL::Config{WITH_MYMODULE},... + +=back + +=head2 Finding the Source + +The directory layout in the repository is different from the layout of +a PDL installation. For some modules the .pm files are generated +via PDL::PP, so changes would need to go into their .pd sources. +Here's a table mapping PDL package names to their origin: + + | Package | Source file | + |------------------------+---------------------------------| + | PDL | Basic/PDL.pm | + | PDL::Bad | Basic/Bad/bad.pd | + | PDL::Basic | Basic/Core/Basic.pm | + | PDL::Core | Basic/Core/Core.pm | + | PDL::Demos | Demos/Demos.pm | + | PDL::Graphics::Gnuplot | *not* in this repository | + | PDL::Graphics::PGPLOT | *not* in this repository | + | PDL::Graphics::PLplot | *not* in this repository | + | PDL::Graphics::Prima | *not* in this repository | + | PDL::Graphics::Simple | *not* in this repository | + | PDL::Graphics::TriD | Graphics/TriD/TriD.pm | + | PDL::Graphics::TriD::* | Graphics/TriD/Objects.pm | + | PDL::IO::FITS | IO/FITS/FITS.pm | + | PDL::IO::Misc | IO/Misc/misc.pd | + | PDL::IO::Pic | IO/Pnm/pnm.pd | + | PDL::IO::Storable | IO/Storable/storable.pd | + | PDL::Lvalue | Basic/Lvalue.pm | + | PDL::Math | Basic/Math/math.pd | + | PDL::MatrixOps | Basic/MatrixOps/matrixops.pd | + | PDL::NiceSlice | Basic/SourceFilter/NiceSlice.pm | + | PDL::Ops | Basic/Ops/ops.pd | + | PDL::Primitive | Basic/Primitive/primitive.pd | + | PDL::Slices | Basic/Slices/slices.pd | + | PDL::Ufunc | Basic/Ufunc/ufunc.pd | + + + +=head1 References + +=over + +=item Official Website + +For the audience of PDL users there is a dedicated website in the +perl.org domain: L. + +=item The current PDL version on MetaCPAN + +L + +=item A guide to PDL's module references for PDL users + +L + +=item The comprehensive modules index (autogenerated) + +L + +=item Git + +The main Git home page is at L. +Two good online Git references are: + +=over + +=item the Git User's Manual at + +L + +=item and Git Magic at + +L + +=back + +=back \ No newline at end of file diff --git a/DEVELOPMENT b/DEVELOPMENT deleted file mode 100644 index 88996c10a..000000000 --- a/DEVELOPMENT +++ /dev/null @@ -1,217 +0,0 @@ -This file has some information on how to get access to the latest -PDL sources (mainly of interest for potential developers). This -should not be confused with the latest public release which will -always be available from CPAN (if you don't know what that is -check the FAQ). - -Public Git repository --------------------------------------------- - -From version PDL-2.4.4 onwards the source distribution is in -a publicly accessible Git repository. From version PDL-2.019 -onwards the project is hosted at the GitHub site at - - https://github.com/PDLPorters/pdl - -See Basic/Pod/FAQ.pod section 4.9 for instructions on this. - -If you do not know how to use Git try 'man git' or have a look at -some of the online tutorials available on the web. - -The main Git home page is at - - http://www.git-scm.org/ - -and two good online Git references are the Git User's Manual at - - http://www.kernel.org/pub/software/scm/git/docs/user-manual.html - -and Git Magic at - - http://www-cs-students.stanford.edu/~blynn/gitmagic/ - - -PDL Developer Guidelines: -------------------------- - -The following guidelines are for any developer that has -access to the PDL Git repository. - -1) Before committing a change with new files to the repository - you should update: - - - MANIFEST (if files were added, using 'make manifest') - - MANIFEST.SKIP (if applicable) - -2) Make sure you add a test case in the 't' directory for any - significant additional capability you add to PDL. Please - use Test::More or one the of the Test modules available via - perl modules rather than doing-it-yourself! - -3) Please include POD documentation for any functions you add to - the distribution. - - - See Basic/Core/Core.pm for an example of including POD - documentation in .pm files. - - See Basic/Core/Primitive/Primitive.pd for an example of - including POD documentation in PDL .pd files. - - read the documentation in PDL::Doc for a detailed - description of the PDL documentation conventions. - -4) Don't commit before you successfully built and passed - 'make test'. - -5) Bugs reported on the list should be entered into the bug - database and bugs closed when a patch has been committed - as a fix. (Primary responsibility for this task is the - pumpking, but other devels should be able to help.) - - -PDL Developer Recommended Workflow: ------------------------------------ - -See Basic/Pod/FAQ.pod section 4.11 for instructions on this. - -PDL Developer Notes: --------------------- - -A (small) collection of random musings to note if you feel -the need to improve or add to PDL (please do): - -*) git supports file-by-file commits so it is helpful - to commit your changes to git a little at a time where - each commit corresponds to a single change. This makes - it easy in the log to determine what was done and to - locate any desired commit in case of issues that need - to be resolved. - -*) Need help? - -See the pdl-devel email list; details for subscription -and access to the archives can be found on the PDL web -page at: - - http://pdl.perl.org/?page=mailing-lists - -*) Access to PDL's configuration - -If you need to access the configuration for PDL then use the -%PDL::Config variable. Prior to 2.4.1 this was a mess since -you had to use %PDL_CONFIG within Makefile.PL and PDL::Config -from *.pm/tests. The build process has been changed (I hesitate -to say "cleaned up" ;) to just use %PDL::Config consistently -throughout. - -- %PDL::Config is automatically available to you when you - are in a Makefile.PL within the PDL distribution. You can - change the hash and these changes will be stored in the - PDL::Config module. You should only change values when it - makes sense (e.g. if the user has specified that a module - should be built but you find out this is not possible). - -- use PDL; now loads PDL::Config by default - -- Otherwise you can say 'use PDL::Config;' or - perhaps - something like - eval 'require "' . whereami_any() . '/Core/Config.pm";'; - where whereami_any() is from PDL::Core::Dev; - - -------------------------------------------------------------- -Notes on transferring an external PDL module to the PDL - source tree for distribution with PDL. -------------------------------------------------------------- - -Suppose you have developed a PDL module that resides in a -standalone source tree. You typically will need to have PDL -installed on your system before you can build this module. - -If you wish to migrate the module into the PDL distribution -you will need to make certain changes to the module source -in order to built in the PDL distribution. You will need to -removed dependecies on a pre-existing PDL installation for -configuration and build of your module. This is because as -part of the PDL distribution, it is possible that PDL has -never been installed. Build processes based on PDL will then -fail. - -Following is some specific advice that can help you do this. - -[ These notes are very preliminary and are expected to be ] -[ revised and/or replaced by improved documentation. ] - -Changes that must be made to files in your module source tree -if you are building the module from a .pd file : - -Makefile.PL: --- You must remove the line 'use PDL::Core::Dev;'. - --- The line 'PDL::Core::Dev->import();' must be present - --- You must change the call from 'pdlpp_postamble' to a call to - 'pdlpp_postamble_int' (with the same arguments.) - --- It seems that most modules in the PDL source use - VERSION_FROM => '../../Basic/PDL.pm', - but not all of them in order that their version tracks - the PDL release version. It is possible to maintain - separate versioning even within the PDL source tree but - it may make things confusing. - -Make certain that you make these changes to each 'Makefile.PL' in -your source tree. - - -Changes to the existing PDL source tree: - --- Edit the 'Makefile.PL' in the directory above your module source - to add your module directory name to - 'DIR => [ qw/Module1 AnotherModule / ]'. - --- Add your test files (.t files) to the PDL/t directory renaming if - required to avoid namespace conflicts. - --- Does your module depend on any libraries or external - programs ? If so, doocument the required programs with version - numbers in PDL/DEPENDENCIES and add the PREREQ_* option to the - main Makefile.PL if required. - --- If your module requires external libraries or header files, - add a section to perldl.conf. The hash values with be available - in your module's 'Makefile.PL' as $PDL::Config{WITH_MYMODULE},... - - -Finding the Source ------------------- - -The directory layout in the repository is different from the layout of -a PDL installation. For some modules the .pm files are generated -via PDL::PP, so changes would need to go into their .pd sources. -Here's a table mapping PDL package names to their origin: - -| Package | Source file | -|------------------------+---------------------------------| -| PDL | Basic/PDL.pm | -| PDL::Bad | Basic/Bad/bad.pd | -| PDL::Basic | Basic/Core/Basic.pm | -| PDL::Core | Basic/Core/Core.pm | -| PDL::Demos | Demos/Demos.pm | -| PDL::Graphics::Gnuplot | *not* in this repository | -| PDL::Graphics::PGPLOT | *not* in this repository | -| PDL::Graphics::PLplot | *not* in this repository | -| PDL::Graphics::Prima | *not* in this repository | -| PDL::Graphics::Simple | *not* in this repository | -| PDL::Graphics::TriD | Graphics/TriD/TriD.pm | -| PDL::Graphics::TriD::* | Graphics/TriD/Objects.pm | -| PDL::IO::FITS | IO/FITS/FITS.pm | -| PDL::IO::Misc | IO/Misc/misc.pd | -| PDL::IO::Pic | IO/Pnm/pnm.pd | -| PDL::IO::Storable | IO/Storable/storable.pd | -| PDL::Lvalue | Basic/Lvalue.pm | -| PDL::Math | Basic/Math/math.pd | -| PDL::MatrixOps | Basic/MatrixOps/matrixops.pd | -| PDL::NiceSlice | Basic/SourceFilter/NiceSlice.pm | -| PDL::Ops | Basic/Ops/ops.pd | -| PDL::Primitive | Basic/Primitive/primitive.pd | -| PDL::Slices | Basic/Slices/slices.pd | -| PDL::Ufunc | Basic/Ufunc/ufunc.pd | diff --git a/MANIFEST b/MANIFEST index 4932eb2fa..b2073af4a 100644 --- a/MANIFEST +++ b/MANIFEST @@ -90,6 +90,7 @@ Basic/Pod/BadValues.pod Basic/Pod/Broadcasting.pod Basic/Pod/Course.pod Basic/Pod/Dataflow.pod +Basic/Pod/DeveloperGuide.pod Basic/Pod/FAQ.pod Basic/Pod/Graphics.pod Basic/Pod/Index.pod @@ -142,7 +143,6 @@ Demos/Sound.pm Demos/t/demos.t Demos/Transform_demo.pm DEPENDENCIES -DEVELOPMENT Doc/Doc.pm Doc/Doc/Config.pm.PL Doc/Doc/Perldl.pm diff --git a/README.md b/README.md index 81b0c96f1..d5e5c875b 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ Before sending us your questions, please see the following files for further inf - `Basic/Pod/FAQ.pod`: The FAQ in pod format. Try `perldoc PDL::FAQ` after installation. - `Basic/Pod/QuickStart.pod`: A quick overview of PDL. Try `perldoc PDL::QuickStart` after installation. - `Basic/Pod/BadValues.pod`: A discussion of the bad value support in PDL -- `DEVELOPMENT`: How to participate in the development of PDL +- `Basic/Pod/DeveloperGuide.pod`: How to participate in the development of PDL **Note:** Most PDL documentation is available online within the PDL shell, `pdl2` (or `perldl`). Try the `help` command within either shell.