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 at sourceforge.net
--------------------------------------------

From version PDL-2.4.4 onwards the source distribution is in a
publicly accessible Git repository. The project is hosted at the
sourceforge site at

  http://sourceforge.net/projects/pdl/

Starting from that URL you will find directions on how to check out
the current sources, browse the Git repository online, etc.

If you would like to actively contribute to PDL development don't
hesitate to contact one of the project admins (listed at the above
URL) to apply for write access to the repository. We strongly believe
in the power of open source development!

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 to the repository you should update:
    - CHANGES file with a description of the change made. 
    - MANIFEST (using 'make manifest'), MANIFEST.SKIP, TODO files if
      applicable.

2) Remember to 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.

2) Make sure you add a test case in the 't' directory for any
   significant additional capability you add to the PDL package.
   Please use one the of the Test modules available within Perl
   rather than doing-it-yourself as many of our tests do!  The
   recommended testing module is Test::More which now distributed
   with the perl distribution.
   
3) Don't commit before you successfully built and passed 'make
   test'. But then again, don't keep your changes private for too
   long to avoid conflicts with other developers.
 
4) 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 Notes:
--------------------

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

*) Need help?

See the pdl-porters email list; details for subscription and access to
the archives can be found on the PDL web page at:

  http://pdl.sourceforge.net/maillists/
 
*) 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).

- 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},...
