
In this file:

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


About CPL
---------
This is version 3.1 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 (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.2.6 or newer), and you must have
a Java Development Kit (JDK) available.

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

In order to be able to install the CPL from sources you need an installed
version of the Qfits FITS library (version 5.2.0 or newer). Qfits can be
obtained from

   http://www.eso.org/projects/aot/qfits

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

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

If you installed a Qfits shared object library you might have to add the
directory containing the Qfits 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 Qfits in an exotic place, i.e.
not in one of the standard system directories, you will have to tell configure
where the Qfits library and headers can be found. This could be done by either
setting the environment variable QFITSDIR to the directory where Qfits is
installed, which is convenient if you plan to install CPL more than once, or
you can use the command line options `--with-qfits', `--with-qfits-includes'
or `--with-qfits-libs' of the configure script. Defining the environment
variable QFITSDIR is equivalent with using the option `--with-qfits'. Both
assume that the library and headers are present in the subdirectory `lib' and
`include' respectively. For instance, if the Qfits 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 Qfits 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-qfits=$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 you machine for the necessary
prerequisites in order to build this interface library.

The requirements are an existing Gasgano installation (version 2.2.6 or
newer), and an installation of a Java Development Kit (JDK). The Java runtime
environment (JRE) is not sufficient. 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>
