NAME

       PDL::DeveloperGuide - How to develop for PDL

Public Git Repository

       The PDL source distribution is hosted with "Git" at the GitHub site <https://github.com/PDLPorters/pdl>,
       alongside with other PDL related software.

       This is the preferred place to submit bug reports or, even better, pull requests.

PDL Developer Guidelines

       The following guidelines are for any developer that has access to the PDL Git repository.

       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)

       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 Test::More or one the of the Test modules available via perl modules rather  than
           doing-it-yourself!

       3) Add documentation
           Please include POD documentation for any functions you add to the distribution.

       4) Run the tests
           Don't commit before you successfully built and passed "make test".

       5) Watch for bug reports
           Bugs  should  be  reported to the GitHub issue tracker at <https://github.com/PDLPorters/pdl/issues>.
           See PDL::Bugs for a detailed description.

       6) PDL Developer Recommended Workflow
           This is detailed in section 4.11 of PDL::FAQ.

PDL Developer Notes

   Getting (some) Debug Information
       PDL has some global variables which control diagnostic output:

       $::PP_VERBOSE
           If set to a true value, PDL::PP will print details while  building  the  module  processing  "pp_def"
           declarations.

       $PDL::Graphics::TriD::verbose
           If set to a true value, the routines in PDL::Graphics::TriD will report their progress.

       $PDL::verbose
           Several modules produce diagnostic output to STDOUT if $PDL::verbose has a true value.

       $PDL::debug
           Several modules produce diagnostic output if $PDL::verbose has a true value.

   Generating a Stack Trace
       To generate a stack-trace to help us debug a problem, please first of all do "make realclean", ensure you
       have the latest released PDL.  Then, if it is still happening, please follow this process:

       Rerun perl Makefile.PL
           This will update the timestamps on Makefiles, prompting a full rebuild.

       Edit your generated top-level Makefile
           Add "-g" to the "OPTIMIZE =" line to generate debug symbols (this gets propagated to subdirectories)

       Run: "make"
           This builds PDL into the "blib" directory.

       Run: "gdb perl -ex 'run -Mblib t/tracking.t'"
           In gdb, run: "bt"

       Copy-paste the backtrace output
           This should show where the segfault originated.

       Then  please  open  an  issue  on  whichever repo is relevant with your "perl -V" output and PDL version,
       together with the stack-trace created above. When you do paste such output into a  GitHub  issue,  please
       surround such blocks with ``` on their own lines. You can check out how it will render with the "Preview"
       button above the issue-editing box.

   Random Musings
       A (small) collection of random musings to note if you feel the need to improve or add to PDL (please do):

       Organizing Commits
           The  preferred  way to organize commits is one commit per small, meaningful change (ideally each with
           an update to the corresponding tests).  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.

   Finding the Source
       As  of  2.096,  the  directory  layout  in  the  repository is largely the same as in a PDL installation,
       especially in PDL::Basic.

       Where the .pm files are generated via PDL::PP, changes would need to go into their .pd sources. Use  "git
       grep Package::Name" to find them.

References

       Official Website
           For   the   audience   of   PDL   users  there  is  a  dedicated  website  in  the  perl.org  domain:
           <https://pdl.perl.org/>.

       The current PDL version on MetaCPAN
           <https://metacpan.org/dist/PDL>

       A guide to PDL's module references for PDL users
           PDL::Modules

       The comprehensive modules index (autogenerated)
           PDL::Index

       Git The main Git home page is at <http://www.git-scm.org/>.  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/>

perl v5.40.1                                       2025-03-27                           PDL::DeveloperGuide(3pm)