=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
site L<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.

=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
L<https://github.com/PDLPorters/pdl/issues>.  See L<PDL::Bugs> for a
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

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::TriD                    | Graphics/TriD/TriD.pm           |
  | PDL::Graphics::TriD::*                 | Graphics/TriD/Objects.pm        |
  | PDL::Graphics::TriD::BoundingBox       | Graphics/TriD/TriD.pm           |
  | PDL::Graphics::TriD::Material          | Graphics/TriD/TriD.pm           |
  | PDL::Graphics::TriD::OneTransformation | Graphics/TriD/TriD.pm           |
  | PDL::Graphics::TriD::QuaterController  | Graphics/TriD/TriD/ArcBall.pm   |
  | PDL::Graphics::TriD::Scale             | Graphics/TriD/TriD.pm           |
  | PDL::Graphics::TriD::Transformation    | Graphics/TriD/TriD.pm           |
  | PDL::Graphics::TriD::Translation       | Graphics/TriD/TriD.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<https://pdl.perl.org/>.

=item The current PDL version on MetaCPAN

L<https://metacpan.org/dist/PDL>

=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

The main Git home page is at L<http://www.git-scm.org/>.
Two good online Git references are:

=over

=item  the Git User's Manual at

L<http://www.kernel.org/pub/software/scm/git/docs/user-manual.html>

=item and Git Magic at

L<http://www-cs-students.stanford.edu/~blynn/gitmagic/>

=back

=back
