HINT
----
For the latest install and per-platform guidance on
how to get and install PDL, see the Install PDL page at:
http://pdl.perl.org/?page=install



INSTALLATION
------------
To install PDL on your machine, first check that you
have a recent enough version of Perl.  5.10.x and above
is required.

See win32/INSTALL for details on installing PDL on
windows platforms.

See cygwin/INSTALL for details on installing PDL on
cygwin platforms.

The file DEPENDENCIES summarizes the dependencies of
various PDL modules on libraries/other packages.  The
location of some of these files needs to be specified
in the file perldl.conf.

PDL depends on a number of other Perl modules for
feature complete operation.  These modules are generally
available at the CPAN. The easiest way to resolve these
dependencies is to use the CPAN module to install PDL.
Installation should be as simple as

  cpan install PDL   # if the cpan script is in your path

or if you don't have the cpan script try

  perl -MCPAN -e shell
  cpan> install PDL

NOTE: if this is your first time running the cpan shell,
you'll be prompted to configure the running environment.

IMPORTANT: Be sure your cpan build_dir location does not have
white space in the name.  To check or change the setting, start
the cpan shell as above, then to check:

  cpan> o conf build_dir
      build_dir          [/your/build dir/.cpan]
  Type 'o conf' to view all configuration items

And to change to something better:

  cpan> o conf build_dir '/your/build_dir/.cpan'
      build_dir          [/your/build_dir/.cpan]
  Please use 'o conf commit' to make the config permanent!



perldl.conf
-----------
Edit the file perldl.conf in the PDL source directory
to specify configuration options for building PDL.  The
comments in this file specify what the options are and
give examples.

NOTE: If you are happy with your perldl.conf you can
keep the file handy for future reference.  Place it in
~/.perldl.conf where it will be picked up automatically
or use this command

    perl Makefile.PL PDLCONF=your_conf_file

the next time you configure PDL.  (You should check if
new config flags were introduced when installing a new
version of PDL by consulting its perldl.conf.)

After editing the configuration options just say

	perl Makefile.PL

in the directory this file is in. (See 'perldoc ExtUtils::MakeMaker'
for info on how to configure the installation location, etc.)
and if that seems ok, try:

	make

If there are any strange error messages, please contact
the developers with a full bug report; response is
often rapid (We would like to have PDL work right out
of the box on as many platforms as possible).

If the make command completed successfully, try:

	make test

to run the regression tests.  If you have issues,
please read Known_problems to see if they have been
seen before.  Again, if there are
errors, please contact the developers (via the
pdl-devel mailing list, see Basic/Pod/FAQ.pod).

If everything works and you wish to install PDL, type

   make install

There is also another make item:

   make doctest

which creates the documentation database for use
in the PDL shell (pdl2 or perldl).  It will be run
automatically on PDL install, but you may wish to
run it by hand to have access to PDL on-line docs
when running from the build directory before/without
install.



F77 Configuration
-----------------
F77 configuration information is normally picked up
from ExtUtils::F77 to build modules like PDL::Slatec
that rely on a working fortran compiler.

In cases where you don't want to rely on ExtUtils::F77
for one reason or another (e.g., a win32 build or other
platform without ExtUtils::F77 support) there is now
the config variable F77CONF.  It is supposed to point
to a perl file that implements a minimal F77Conf class
(see debian/f77conf.pl for an example).  The use of
F77CONF is similar to the PDLCONF variable, e.g.

   perl Makefile.PL F77CONF=debian/f77conf.pl

Note that almost always it is better to use ExtUtils::F77.
Only use the F77CONF mechanism if you have a good reason to.
Win32 is special. See win32/INSTALL.



COMMON PROBLEMS
---------------
If you have problems building or installing PDL, we
suggest contacting the PDL users and developers via
the PDL mailing lists.  See

   http://pdl.perl.org/?page=mailing-lists

to get started.  Links to searchable archives of the lists
are available on the same page.

The build process has been significantly cleaned up
since PDL-2.4.3.  If you are unable to install PDL,
even after consulting the list archives or other users
and developers on the PDL lists, please do submit
a bug report (see the BUGS file for directions).

* Test failures in t/gis_proj.t, t/proj_transform.t, or
  t/proj_transform2.t with error messages that look like
  this (in the body of the test output, not the summary):

     ...
     not found
     _fwd_trans_inplace[BADCODE](): Projection initialization
     failed: major axis or radius = 0 or not given
     ...

  This indicates that the PROJ4 library on the system is
  either missing or cannot find the transformation parameter
  files.  They are typically in a directory like
  /usr/share/proj and contain files with names like:
  epsg, nad27, nad83, conus,...
  
  If you find such a directory, try setting the PROJ_LIB
  environment variable to that location.

  If you do not have that directory, you may need to use
  your platform's package manager to install the missing
  component.  E.g.:

    - Ubuntu:  These are included in the libproj-dev.
    - Fedora:  You have to install the proj-nad package.

* make failures for PDL with error messages like:

      make: Warning: File `Makefile.PL' has modification
      time 3.1e+05 s in the future
      Makefile out-of-date with respect to Makefile.PL

  This problem has been seen on some Linux Virtual Machines
  where there was a problem with the synchronization of the
  VM time with the host OS system time.  A quick work-
  around for the problem is to 'touch Makefile.PL' which
  updates the file time for Makefile.PL to "now" so make
  runs correctly.

* If you wish to avoid interactive prompts during the PDL
  configure process (e.g., the perl Makefile.PL stage),
  you can set the environment variable PERL_MM_USE_DEFAULT
  to 1 so the default values are taken automatically.
