=head1 NAME
PDL::DeveloperGuide - How to develop
for
PDL
=head1 Public Git Repository
The PDL source distribution is hosted
with
L</Git> at the GitHub
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<Test::More> 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<make test>.
=item 5) Watch
for
bug reports
Bugs should be reported to the GitHub issue tracker at
detailed description.
=item 6) PDL Developer Recommended Workflow
This is detailed in section 4.11 of L<PDL::FAQ>.
=back
=head1 PDL Developer Notes
=head2 Getting (some) Debug Information
PDL
has
some global variables which control diagnostic output:
=over
=item C<$::PP_VERBOSE>
If set to a true value, L<PDL::PP> will
print
details
while
building
the module processing C<pp_def> declarations.
=item C<
$PDL::Graphics::TriD::verbose
>
If set to a true value, the routines in L<PDL::Graphics::TriD> will
report their progress.
=item C<
$PDL::verbose
>
Several modules produce diagnostic output to STDOUT
if
C<
$PDL::verbose
>
has
a true value.
=item C<
$PDL::debug
>
Several modules produce diagnostic output
if
C<
$PDL::verbose
>
has
a
true value.
=back
=head2 Generating a Stack Trace
To generate a stack-trace to help us debug a problem, please first of
all
do
C<make realclean>, ensure you have the latest released PDL.
Then,
if
it is still happening, please follow this process:
=over
=item Rerun perl Makefile.PL
This will update the timestamps on Makefiles, prompting a full rebuild.
=item Edit your generated top-level Makefile
Add C<-g> to the C<
OPTIMIZE
=> line to generate debug symbols (this gets
propagated to subdirectories)
=item Run: C<make>
This builds PDL into the C<blib> directory.
=item Run: C<gdb perl -ex
'run -Mblib t/tracking.t'
>
In gdb, run: C<bt>
=item Copy-paste the backtrace output
This should show where the segfault originated.
=back
Then please
open
an issue on whichever repo is relevant
with
your
C<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.
=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
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.
=back
=head2 Finding the Source
As of 2.096, the directory layout in the repository is largely the
same as in a PDL installation, especially in L<PDL::Basic>.
Where the .pm files are generated via PDL::PP, changes would need
to go into their .pd sources. Use C<git
grep
Package::Name> to find
them.
=head1 References
=over
=item Official Website
For the audience of PDL users there is a dedicated website in the
=item The current PDL version on MetaCPAN
=item A guide to PDL's module references
for
PDL users
L<PDL::Modules>
=item The comprehensive modules
index
(autogenerated)
L<PDL::Index>
=item Git
Two good online Git references are:
=over
=item the Git User's Manual at
=item and Git Magic at
=back
=back