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;
*) Location of temporary files
Please use $PDL::Config{TEMPDIR} for the directory in which to
place temporary files (e.g. when IO::File::new_tmpfile() is
not appropriate). This will make it easier for distributions
to package PDL since there will only be one place they need to
change if the default value causes problems.
This *includes* test cases as well as for Makefile.PL's!
-------------------------------------------------------------
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/Core/Version.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},...