PDL::DeveloperGuide - How to develop for PDL
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.
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 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.
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.
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.
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.