PDL 2.4.3b1 "COMPLETE DISTRIBUTION"

This is version 2.4.3b1 of the Perl Data Language, the free, efficient,
powerful, vectorized, interactive, object oriented data analysis
language that is based on Perl.  In addition to PDL 2.4.3b1 itself, this
disk image contains many freely distributable auxiliary modules that
are used by PDL, including Perl itself, all in source-code form.

Because 2.4.3b1 is a "beta-test" (pre-release) version, we also
include PDL 2.4.2 as released.  2.4.3b1 passes "make test" on most
supported platforms and includes several bug fixes and enhancements
not present in earlier versions.


COMPATIBILITY:

PDL 2.4.2 is known to run well on most flavors of Linux, Solaris,
IRIX, BSD, and MacOS X.  It is believed to install cleanly on
Microsoft Windows XP, and also installs under the Windows Cygwin POSIX
compatibility layer.  It will probably work with Perl 5.6.1, but 5.8
or higher is recommended.  Perl 5.8.5 is included on this disk.


FREE SOFTWARE:

You have explicit permission to make copies of this disk and the
software on it, and distribute them for free to anyone.  If you want
to sell copies of this software, please see the file "COPYING" in this
directory.


INSTALLATION:

	- BINARIES OVER THE NET: If you prefer direct installation and
          are using either Macintosh or Linux, you can probably install
	  a precompiled binary.  Search your usual software repository.
	  Here are some starting points:

		Macintosh:  use the FINK PDL package

		Linux:  Debian -   'apt-get PDL'
			Fedora -   'rpmfind PDL'

	- FROM THIS SOURCE CODE DISTRIBUTION PACKAGE:
	  Skip down 42 lines to the "INSTALLATION NOTES" section, below.


MORE INFORMATION ON PDL:  

Visit the PDL web site at "http://pdl.perl.org".


WHERE TO GET HELP: 

Send an email to the users' list: "pdl@jach.hawaii.edu".
For information on internals or deep technical questions, send email to
the development list at "pdl-porters@jach.hawaii.edu".  


APPLICATION SOFTWARE: 

Several CPAN modules (http://www.cpan.org) exist for specific applications.  
There is a development area for solar physics specific code in the SolarSoft 
development environment (http://www.lmsal.com/solarsoft).


DOCUMENTATION: 

There is a large body of documentation included with PDL; it gets formatted 
as web pages, man pages, and online docs during installation.  To get 
started, say "man PDL::Impatient" once PDL has been installed, or visit
"http://pdl.sourceforge.net/PDLdocs/".  There is a "help" command in perldl.

A brief "Switcher's manual", geared toward helping IDL users switch to
PDL, is being developed and is available in draft form; if interested,
contact Craig DeForest, deforest@boulder.swri.edu.  


CONTRIBUTING: 

Contribution of language components, bugfixes, and documentation is 
welcomed.  Send a note to "pdl-porters@jach.hawaii.edu", or check out 
the SourceForge website at "http://sourceforge.net/projects/pdl/".  

=============================================================================

INSTALLATION NOTES (FOR UNIX-LIKE SYSTEMS)

These installation notes will allow you to install PDL from "scratch"
(source code) on any quasi-POSIX (UNIX-like) system.  You may not need
to perform all (or even any) of the steps to install PDL on your
system, as many operating systems already include PDL.

PDL uses several external modules to add functionality. Even if your
OS already includes PDL, it may not contain some external modules that
are not compatible with the GPL.  PGPLOT is one example.

The "PDL-2.4.3b1" subdirectory contains the actual PDL distribution,
while the "aux" subdirectory contains auxiliary modules you'll need if
you're starting from more-or-less scratch.

We have tested these installation directions with several research
groups.  Plan on taking between 20 minutes and 1 hour depending on
your skill level, the amount of compiling you actually need, and the
speed of your installation machine.

We assume that you already have C and FORTRAN compilers, and the
X-windows system.

You very likely have Perl already, but it's included here for
completeness and to ensure that you have a complete Perl distribution
handy.  If your existing perl is under 5.6.1 you will definitely 
need to upgrade; but 5.8.1 or higher is recommended.

There are two sections below: a longish one detailing all the
auxiliary modules that you will need for full functionality, and a
short one explaining how to install PDL once they're all in place.
You can skip individual modules if you want to; you just won't get
that piece of functionality in your final PDL build.

BEFORE YOU BEGIN: Copy the complete CD directory tree to somewhere
writable, so that you can unpack and build in place.  We suggest
/usr/local/build/PDL-2.4.3b1-complete, but anywhere will do.

------------------------------

INSTALLING THE AUXILIARY MODULES (steps 0-9)

Note that you may not have to install most of these things.  PGPLOT 
(step 4) is the only element that is not part of (for example) the
Red Hat Linux distribution.  

There are 9 external packages to check and install.  For each one,
there's a little blurb saying what the package is, what you need it
for, and how to install it.  You probably don't need to install most
of these, but you probably want to check each one.  

Finally, you will need to install the "glue" Perl packages that tie the
external modules into the Perl millieu (step 8).


0. *** Perl ***       (The basic language engine)
   Perl is included "just in case", and also so that you have a complete 
   copy of the Perl-5.8.5 distribution handy: many pre-existing installations 
   (notably Red Hat) don't have everything that comes with the source distro.

   CHECK:   say "perl -v" at your command prompt.  Check to make sure
            you get back a message saying Perl's version is >= 5.6.1
	    5.6.x will probably work, but you should consider upgrading
	    if you have anything less than 5.8.1.
   HOW TO INSTALL:
	Unpack the "aux/external/perl-5.8.5.tar.gz" tarball into somewhere 
        writable, and follow the directions in INSTALL.  Make sure NOT to use
	Perl's built-in malloc (you want the system malloc, which is what
	all the PDL code uses too).



1. *** pbmplus ***    (Image translation, required for file I/O)
   CHECK:  say "ls /usr/lib/libpbm*"; make sure you have some libpbm libraries.
           If you see anything like "libpbm.so", you're probably OK.  If not,
	   you should install.
   INSTALL:  Unpack the "aux/external/pbmplus_10dec1991.tar.gz" tarball,
   	and follow the directions in it.



2. *** zlib ***       (Required for JPEG and PNG image I/O.)
   CHECK:  say "ls /usr/lib/libz*"; make sure you have a "libz.so" in there.
	   If you have it, you're probably OK.  If not, you should install.
   INSTALL:  Unpack the "aux/external/zlib-1.1.4.tar.gz" tarball, and 
        follow the directions in it.



3. *** libjpeg ***    (Required for JPEG image I/O.  Also used by PGPLOT.)
   CHECK:  say "ls /usr/lib/libjp*"; make sure you have some libjpeg libraries.
           If you see anything like "libjpeg.so", you are probably OK.  If not,
	   you should install.
   INSTALL:  Unpack the "aux/external/jpegsrc.v6b.tar.gz" tarball, and 
	follow the directions in it.



4. *** libpng ***     (Required for PNG image I/O. Also used by PGPLOT.)
   CHECK:  say "ls /usr/lib/libpng*"; make sure you have some libpng libraries.
           If you see anything like "libpng.so", you're probably OK.  If not,
           you should install.
   INSTALL:  Unpack the "aux/external/libpng-1.2.5.tar.gz" tarball, and 
        follow the directions in it



5. *** GSL ***       (The Gnu Scientific Library; useful but optional tools)
   CHECK:  Say "ls /usr/lib/libgsl*"; make sure you have some libgsl libraries.
           If not, you should install.  You can skip this step if you don't
	   want the GSL, but, trust me, you probably do.  There are loads
	   of cool curve-fitters, random-number generators, special functions,
	   and other goodies in there.  If you install a binary copy of the
	   GSL from a package manager such as Red Hat's RPM, you will
	   need the "GSL-devel" package too -- or just re-install from this
	   package.
   INSTALL:  Unpack the "aux/external/gsl-1.3.tar.gz" tarball, and follow
	the directions in it.



6. *** pgplot ***     (Device-independent graphics I/O; 2-D plotting package)
   CHECK:  Say "ls /usr/local/pgplot".  If it exists, you're probably OK --
           but you probably want to install this version of pgplot anyway.  
 	   This version ("5.2.2-cd4") is a branch off the main pgplot 
	   distribution.  It includes experimental (but robust) RGB graphics
	   capability, which you will probably want, and also a better 
	   pixel-primitive-device rendering engine than the mainstream 
	   pgplot.  The rest of the API is unchanged, so you can use this 
	   version with your previous PGPLOT code.
   INSTALL:  If you're running a Red Hat-like system, you can just cd to the
	"aux/external" directory and execute the script "BUILD-PGPLOT".
	You must be root for it to work right.  Otherwise, unpack the 
	"aux/external/pgplot-5.2.2-cd4.tgz" tarball, and follow the
	installation instructions there -- in particular, edit the file
	"drivers.list" to get the device drivers you want.

	In order for PGPLOT to compile, you must have the X11 static 
	library "libX11.a" in your library path -- it's usually in either
	/usr/lib or /usr/X11/lib or /usr/X11R6/lib.  The easiest way to 
	tell if it's there is to try compiling pgplot and look for complaints.
	If you get messages complaining that there's no "libX11.a", you must
	install that library (not included with this CD).  If you're running 
        Red Hat, you can install the package "X11-devel" from the distribution 
 	CD.  X11 is not	included here because there are so many variants,
	and because it's so commonly available.

	In order for PGPLOT to work right, you must set the environment 
        variable "PGPLOT_DIR" to "/usr/local/pgplot" (or wherever you 
	actually install pgplot, if that is somewhere else).  You can do that
	system-wide (how to do that varies according to your flavor of 
	UNIX) or in your own account, by adding
		setenv PGPLOT_DIR /usr/local/pgplot
	or
		PGPLOT_DIR=/usr/local/pgplot; export PGPLOT_DIR
 	to your .login (for csh-like shells) or .profile (for sh-like shells)
	respectively.  You should also set the environment variable now, in 
	your current shell, so you don't have to log in again to get 
	pgplot to work.



7. *** PLPLOT ***    (Device-independent graphics I/O; newer plotting package)
   CHECK: Say "ls /usr/local/lib/plplot.so"; if something is present, you
          probably have PLplot installed.  PLplot is optional; it is a 
          newer plotting package than PGPLOT, and some folks prefer it to
          PGPLOT.
   INSTALL:  Unpack the "aux/external/plplot-5.5.3.tar.gz" 
        tarball, and follow the directions in it.  At a minimum, you can
	just type "./configure; make install" as root in that directory.
        If you do that, then the PLplot libraries get installed in 
	"/usr/local/lib/".



8. *** OpenGL ***    (3-D graphics support -- useful but optional)
   CHECK: Say "ls /usr/lib/libGL*" and you should see some libGL and libGLU 
	files.  If you don't, either download your favorite OpenGL package or
	use the enclosed Mesa library.  Mesa is an open-source software 
	implementation of the OpenGL graphics standard (although they're
	not certified by SGI and hence can't call themselves an OpenGL 
	implementation, that's in fact what they are).  

	OpenGL is a pretty universal standard rendering language, with 
	several dozen implementations.  Mesa works well but is very slow
	compared to the accelerated implementations that exist for most
	modern graphics cards.  
	
	You can skip this step if you don't want 3-D graphics support.
   INSTALL:  Unpack the "aux/external/MesaGL/MesaLib-5.0.1.tar.gz" tarball,
	and follow the directions in it -- then unpack the other one,
	"/aux/external/MesaGL/libGLw.tar.gz", and follow the directions in it.



9.  Install the auxiliary Perl modules in the perl subdirectory.

  The Perl modules are all in "aux/perl".  They are all from CPAN, so
  you can install them using the CPAN client if you are familiar with that.  

  There are two ways to install them:  automatically, or by hand.

  AUTOMATICALLY:
	Just run (as root) the "00-BUILD_EVERYTHING" script in "aux/perl".
	It will sequentially unpack each archive and execute the 
	command "perl Makefile.PL; make install" in each directory.

  MANUALLY:
  	You can unpack the perl modules, and compile and install
	them individually.  For each one, unpack it, then cd to the 
	directory and say "perl Makefile.PL; make; make test"
  	to your shell.  If all tests get passed, say "make install" as root.

	Some of the modules depend on others, so you will want to install them
	in a particular order.  

	One choice you have to make: If you are running the included,
	RGB-enabled pgplot distribution from step 5 above, you will want
	PGPLOT-2.19 -- that is the Perl glue module that understands the 
	RGB extensions.  If you are running a standard pgplot
	distribution up to version 5.3, then you will want PGPLOT-2.18.

	Here are the modules, in an order that avoids dependency problems 
	between them:
  
	Parse-RecDescent-1.94.tar.gz   # Required for Inline
	Text-Balanced-1.95.tar.gz      # Required for NiceSlice and perldl
	Inline-0.44.tar.gz             # Required for ExtUtils
	ExtUtils-F77-1.14.tar.gz       # Required for glue functionality
	Astro-FITS-Header-2.8.1.tar.gz # Helps out with rfits/wfits
	Convert-UU-0.52.tar.gz         # Enables PDL::IO::Dumper
	PGPLOT-2.18.tar.gz             # PGPLOT Graphics (vanilla pgplot)
	PGPLOT-2.19.tgz	               # PGPLOT Graphics (RGB-enabled pgplot)
	TermReadKey-2.21.tar.gz	       # Needed for ReadLine
	Term-ReadLine-Gnu-1.13.tar.gz  # Gnu terminal handler (cmd hist. etc.)
	Time-modules-2003.0211.tar.gz  # Needed for FITS header time handling

------------------------------

INSTALLING PDL ITSELF

This is the easy part.  Just cd into the PDL-2.4.2 directory, edit
"perldl.conf" if you want to (the default settings are probably just
fine), and say "perl Makefile.PL; make".  Afterward, say "make test"
if you like, and then become root and say "make install".

You're good to go!

The install process will install the perl modules and man pages, and
also put the script "perldl" into /usr/bin.  

It will also compile the documentation into web pages, which are
accessible from the perldl shell by saying "help www" or "help url".

The documentation also gets turned into man pages which you can access
with the ordinary "man" command at the shell, and into browsable
documentation which you can access with the "?" command within perldl.

You also may want to copy the "sample-perldlrc" file to your home directory:
  cp sample-perldlrc ~/.perldlrc
That will make perldl automatically load a bunch of modules that are useful 
but not part of the PDL core.

To try out PDL, say "perldl" and type "demo".

