In this file:

* About CPL
* Prerequisites
* Installation
* Gasgano Support
* Reporting Bugs


About CPL
---------
This is version 5.0.0 of the ESO Common Pipeline libraries (CPL).

This package includes libraries that are central to the development and
execution of pipeline recipes as they are operated by ESO for all VLT
instruments, miscellaneous HTML documentation and regression tests.


Prerequisites
--------------

For installing the CPL or to use it for your own software project you, at
least, need an ANSI-C compiler (gcc version 3.2 or newer).

In order to build and install the Gasgano support library you need in addition
an existing Gasgano installation (version 2.3 or newer), and you must have
a Java Development Kit (JDK) version 6 available.
You can download the JDK from the following link:
http://java.sun.com/javase/downloads/index.jsp


Installation
------------

In order to be able to install the CPL from sources you need an installed
version of the CFITSIO FITS library (version 3). CFITSIO can be
obtained from

        http://heasarc.gsfc.nasa.gov/fitsio
        ftp://legacy.gsfc.nasa.gov/software/fitsio/c

To install CFITSIO unpack the tar-archive in a directory of your choice,
enter the CFITSIO directory and run the commands outlined below (for
detailed installation instructions please refer to the CFITSIO documentation):

 $ ./configure --prefix=<where-CFITSIO-will-be-installed> --enable-shared
 $ make 
 $ make install

If you installed a CFITSIO shared object library you might have to add the
directory containing the CFITSIO libraries to the LD_LIBRARY_PATH environment
variable or any equivalent.

Now unpack the CPL tar-archive in a directory of your choice (if you are
reading this file you probably managed to do so) and change directory into
the top-level directory of the CPL source tree.

To configure the CPL source tree you have to run the GNU configure script
in the top level directory. If you installed CFITSIO in an exotic place, i.e.
not in one of the standard system directories, you will have to tell configure
where the CFITSIO library and headers can be found. This could be done by either
setting the environment variable CFITSIODIR to the directory where CFITSIO is
installed, which is convenient if you plan to install CPL more than once, or
you can use the command line options `--with-cfitsio', `--with-cfitsio-includes'
or `--with-cfitsio-libs' of the configure script. Defining the environment
variable CFITSIODIR is equivalent with using the option `--with-cfitsio'. Both
assume that the library and headers are present in the subdirectory `lib' and
`include' respectively. For instance, if the CFITSIO library is located in
$HOME/lib and the headers in $HOME/include the environment variable or the
option argument should be $HOME.

The installation directory is specified by either setting the environment
variable CPLDIR to the target directory (if it does not exist it is created)
or using the configure command line option `--prefix'. If nothing is
specified the CPL will be installed into `/usr/local'. Note that in this
case you must be root to install CPL!

Assuming that CFITSIO was installed in $HOME/lib and $HOME/include and CPL
should be installed in $HOME you need to execute the following commands
in the top-level directory of the source tree in order to build and
install CPL:

$ ./configure --prefix=$HOME --with-cfitsio=$HOME
$ make
$ make install

Optionally, if the HTML reference manual should be installed execute also

$ make install-html

By default this installs the HTML reference manual into the subdirectory
'share/doc/cpl/html' of the installation tree.
  
Finally, if the CPL was not installed in one of the standard system
directories do not forget to add the location of the CPL libraries to
your LD_LIBRARY_PATH variable or the equivalent for your system.


Gasgano Support
---------------

Since version 3.1 of CPL the support for ESO's Gasgano data organizing tool is
included in the CPL distribution. When running the configure script, as
described in the previous section, it checks your machine for the necessary
prerequisites in order to build this interface library.

The requirements are an existing Gasgano installation (version 2.3 or
newer), and an installation of a Java Development Kit (JDK), version 6. 
The Java runtime environment (JRE) is not sufficient, 
you can download the JDK from the following link:
http://java.sun.com/javase/downloads/index_jdk5.jsp
In addition the environment variable JAVA_HOME should point to the root directory
of the JDK installation.

If the Gasgano, or the JDK installation is not found by the configure script,
but are nevertheless present on the target machine, you may use the command
line options '--with-gasgano-classpath', '--with-java' or
'--with-java-includes' and/or '--with-java-includes-md' to pass the Gasgano
and Java installation directories to configure.

The option '--with-gasgano-classpath' takes the path to the Gasgano jar files
as an argument, which can usually be found in the subdirectory 'share' of the
Gasgano installation.

The option '--with-java' takes the root directory of the JDK installation as
an argument. Using this option configure assumes that the required C header
files are found in the subdirectories 'includes' and 'includes/<platform>' of
the JDK installation. <platform> is usually the name of your operating system,
for instance 'linux' on a Linux system, but this may not be true in all cases.

If running configure using '--with-java' does not succeed, you may want to try
the options '--with-java-includes' and '--with-java-includes-md' to set the
include directories explicitly to the subdirectories of the JDK containing the
files 'jni.h' and 'jni_md.h' respectively.


Reporting Bugs
--------------

Please report any bugs to <cpl-help@eso.org>