
INSTALLING THE PERL5 VERSION OF PGPERL
--------------------------------------

There are two approaches to this. Firstly you might have obtained
the pre-compiled object files for Solaris/SunOS/Linux/OSF1. For
these it is a matter of installing them in the correct locations.
Secondly you might be trying to recompile from scratch.


PRECOMPILED INSTALLATION
------------------------

Precompiled pgperl object files, which can be dynamically loaded into
perl5, are available for Solaris 2.4, SunOS 4.1.3, Linux (using and 
tested with Gnu Dynamic Loading package dld 3.2.6) and Alpha/OSF1.   
These are designed to be inserted into a pre-existing perl5 
installation. (See below for where to obtain perl5.)

1) Unpack the pgperl distribution for your architecture. There are four
   important files which must be installed in the perl5 library
   directory tree.  Normally this will be /usr/local/lib/perl5 but your
   system may vary. If you are installing in a private location you
   will have to set the environment variables PERL5LIB or PERLLIB to
   include this location (these are ":" seperated directory paths in
   the UNIX style).

 File:            Install in:                             Purpose:

pgplot.pl   /usr/local/lib/perl5/pgplot.pl               Module alias file
PGPLOT.pm   /usr/local/lib/perl5/PGPLOT.pm               Module definitions
PGPLOT.so   /usr/local/lib/perl5/auto/PGPLOT/PGPLOT.so   Compiled object*
PGPLOT.bs   /usr/local/lib/perl5/auto/PGPLOT/PGPLOT.bs   DynaLoader Bootstrap

   *Important Notes:
    ----------------
   
  (a) It is quite common to have TWO auto directories - with one for the
      architecture-dependent object files. e.g. on a Sun this might
      be: /usr/local/lib/perl5/sun4-solaris/auto. In this case the
      two last files must be placed here - e.g. something like:
      cp PGPLOT.so /usr/local/lib/perl5/sun4-solaris/auto/PGPLOT/
   
  (b) Note: on Linux this is called PGPLOT.o, and Linux users may
      have to edit PGPLOT.bs to reflect the location of libm and libc on
      their system. In fact Linux dynamic loading is tricky and this may
      not work at all due to differing versions of libc and libm (you may
      get a 'bad magic number' error message), so you may have to resort to
      compiling pgperl as described below.
   
  (c) Object file is alled PGPLOT.sl for HP-UX systems.


2) There are some auxiliary files required by pgplot, copies of
   which are provided in the pgperl binary distribution to save
   the user from having to obtain and build pgplot.

   If you do not already have them already then install them
   in a suitable directory, e.g.:

   mv pgxwin_server pgdisp rgb.txt grfont.dat /usr/local/pgplot/

   [It is most convenient to place these files in /usr/local/pgplot/ 
   as this is where PGPLOT expects to find them. This can be
   overridden if necessary by setting the environment variable
   PGPLOT_DIR]

   Ensure the following executable programs, used by the various
   X-windows display drivers, are somewhere in the $PATH.  e.g.
   by making links or copying to /usr/local/bin:

   ln -s /usr/local/pgplot/pgxwin_server /usr/local/bin/pgxwin_server
   ln -s /usr/local/pgplot/pgdisp        /usr/local/bin/pgdisp



COMPILING PGPERL FOR PERL5
---------------------------

pgperl follows the standard approach for perl5 modules. A PGPLOT.xs
XSUB file is provided to specify how to call the routines in the PGPLOT
library and a PGPLOT.pm file is provided to load the module into perl.

Here is the recipe for compilation:


1) BUILD PERL5

   ftp the perl5 distribution for your architecture. The official
   anonymous ftp site at the time of writing is:

   ftp.netlabs.com:/pub/outgoing/perl5.0/perl5.001.tar.gz

   These files are seperate shell archives all of which must be
   unpacked. Of course you should try and find it first at a more
   local ftp site using the archie program. A European site is:

   src.doc.ic.ac.uk:/packages/perl/perl.5.0/perl5.001.tar.gz 

   Once you have followed the accompanying instructions to configure
   and build perl5. 


2) BUILD AND INSTALL THE PGPLOT LIBRARY

   If you don't already have it ftp and build the PGPLOT distribution
   for your architecture.  At the time of writing the current pgplot
   version is 5.0.  This can be obtained by anonymous ftp from:

   astro.caltech.edu:/pub/pgplot/pgplot5.0.tar.Z

   a local copy may be found in:

   ftp.ast.cam.ac.uk:/pub/pgperl/pgplot5.0.tar.Z

   Compiling PGPLOT requires FORTRAN or f2c.

   If you require the X-windows drivers don't forget to install
   the pgdisp and pgxwin_server programs somewhere in $PATH.

   Note: PGPLOT is written in FORTRAN77 but compiles fine using
   f2c (as in the Linux version).


3) Unpack the pgperl distribution in some directory.

   You will need to edit the file Makefile.PL to reflect your system, in
   particular the LIBS line which must specify how to link with PGPLOT and
   the F77 runtime libraries required by it on your system. Also you may
   need to specify the location of libX11 if you have built PGPLOT with any
   of the X-windows drivers. For hints see the files for particular
   architectures, Makefile.PL.sol2, Makefile.PL.linux etc. included with the
   pgperl distribution. There are also Makefile.PL files in the
   pgperl/perl5/contrib anon ftp directory which have been contributed by
   users.

   Also if you think your system supports standard C/F77 function
   passing you should use the compilation flag -DHAS_UNIX_FUNCTIONS
   with the DEFINE line. (These use callback from PGPLOT into perl.)
   Don't worry if you don't know - it should build fine without it and
   only a few rarely used PGPLOT functions - pgfunx, pgfuny, pgfunt,
   pgconx - are disabled. You can test this later with testpgperl4.pg
   and testpgperl5.pg. If you think your version of UNIX, unlike most,
   doesn't append trailing underscores to F77 subroutine names (e.g.
   HP-UX) then try compiling again with the additional flag
   -DNO_TRAILING_USCORE in Makefile.PL


3) Then:

   perl Makefile.PL
   
   (IMPORTANT: Make sure "perl" points to perl5 NOT perl4 - if
   necessary make a local symbolic link! If you get a "syntax error"
   message this is a sure sign you are using perl4 no matter what you
   might think!  You can check by typing "perl -v".)

   If you have not installed perl5 in an official location you will
   want to do something like:

   setenv PERL5LIB /data/user/perl5/lib
   perl Makefile.PL PERL_SRC=/data/user/perl5 INST_LIB=/data/user/perl5/lib

   (roll your own directories as necessary.)
   
   This will generate a Makefile which reflects your architecture and the
   answers you supplied to the configure program when building perl5.
   
4) Then:

   make dynamic

   This will:
   
   (a) Process PGPLOT.xs (the interface XSUB file) into PGPLOT.c
   (b) compile PGPLOT.c
   (c) Make the bootstrap file PGPLOT.bs which tells the perl5 dynamic loader
       about the new subroutines and where to find them.
   (d) installs all the files in the correct location.
   

   If your system does not support dynamic loading you will have to
   link it statically to perl5 when you build perl5. To do this place
   the files in the directory perl5.001/ext/PGPLOT/ in the perl5
   distribution and include "PGPLOT" in the list of modules to be
   linked statically when running the Configure program.


5) COMMON PROBLEMS

       The most common problem is undefined symbols due to the
       list of FORTRAN runtime libraries (required by PGPLOT) being
       incomplete or having an unknown location. This usually generates
       a tremendous error list of unresolved symbols when doing 'make
       dynamic'.

       You may well have f77 on your system but have no idea where or
       what the runtime libraries are!  Solaris is particularly
       wonderful in this respect as it does not use the sensible
       /usr/lib - rather on my box it they are in
       /opt/SUNWspro/SC3.0.1/lib - and the version number in that name
       can vary from system to system too!

       The Makefile.PL's for the various architectures are known to
       work on at least one machine, looking at them should assist you
       in tracking them down if the directory names vary slightly - the
       actual list of libs should be the same on a particular
       architecture.

       IF your f77 compiler is in fact f2c (e.g. on Linux) then the
       runtime library is easy - /usr/lib/libf2c.a

6) TESTING

   (a) setenv PGPLOT_DIR /dir/where/you/built/pgplot/
       (This makes sure auxiliary files such as fonts and X
       drivers are picked up)

   (b) Try the scripts testpgperl*.pg (the C-shell script
       testpgperlall.csh can be used to run the all consecutively)
       In particular testpgperl4.pg and testpgperl5.pg test 
       function passing.


I have tested and built this code with perl v5.001 (patch 1e) and
PGPLOT 5.0.1.


Karl Glazebrook, 
---
kgb@ast.cam.ac.uk  Institute of Astronomy, Cambridge, U.K.
pgperl software:   http://www.ast.cam.ac.uk/~kgb/pgperl.html

-----------------------------------------------------------------------------
                                               Last Modified. 9/August/1995.
