In this file: * About CPL * Prerequisites * Required dependencies * Optional dependencies * Links * Installation * Installing CFITSIO * Gasgano Support * Third party libraries * Installing CPL * Installing CPL on the macOS platform * Reporting Bugs About CPL --------- This is version 7.2.3 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 a C99 compliant compiler (gcc version 4.4 or newer). In addition, a few third party libraries are used, which are listed below. If the target system provides these dependencies they may be used, however the system provided libraries must meet certain requirements which are given in the Installation section. The recommended way of installing the third party libraries for CPL is to re-compile them from source. The references for obtaining the third party (source) packages are given in the Links section. Required dependencies: ---------------------- - CFITSIO v3.350 or newer - wcslib 4.24 or newer - fftw 3.3.3 or newer The dependencies fftw and wcslib are required by default. However, if needed, their use can be disabled using an option when running 'configure'. Optional dependencies: ---------------------- - Gasgano 2.4.8 - Oracle Java JDK 7 or newer Note that in order to build and install the CPL Gasgano interface both dependencies, the Gasgano package and the Java Development Kit must be installed. Links: ------ CFITSIO: http://heasarc.gsfc.nasa.gov/fitsio Gasgano: http://www.eso.org/sci/software/gasgano Java JDK: http://www.oracle.com/technetwork/java/javase/downloads/index.html wcslib: http://www.atnf.csiro.au/people/mcalabre/WCS Installation ------------ This section gives an overview of the CPL installation process. Before the CPL package itself can be installed, all required dependencies must be installed, as well as all selected optional packages. Note that for the Gasgano support, both the Gasgano package and the Java JDK must be installed. All dependencies are independent of each other and may be installed in any order. With the exception of the Gasgano package, and the Java JDK, it is recommended that all dependencies are installed into a single, separate directory tree, i.e a single, common directory should be given as '--prefix' option when running the configure script of the different packages. If the target directory of the installation is not a system directory like '/usr' or '/usr/local' (which would require superuser privileges!) it is recommended to setup the search path environment variable of the runtime linker so that it includes the the directory where the third party libraries will be located. The environment variable to be used is LD_LIBRARY_PATH on Linux based systems. For other systems one may have to consult the system documentation to find the equivalent environment variable. The environment variable should then be set such that the library search path contains the location of the libraries in the target directory structure, i.e the directory '/lib' or '/lib64' depending on what is the default name for library locations on the target system. The latter may be used on 64 bit Linux systems, while the first one may be used on both, 32 bit and 64 bit systems. Actually on 64 bit systems it is recommended to put both in the library search path, however care should be taken that '/lib64' comes first. As an example, for a 64 bit Linux system the LD_LIBRARY_PATH may be set as follows, assuming that is '$HOME/cpl', and a Bourne type shell is used: $ export LD_LIBRARY_PATH=$HOME/cpl/lib64:$HOME/cpl/lib:$LD_LIBRARY_PATH Installing CFITSIO: ------------------- By default CPL is built as a thread safe library, and unless the thread support is explicitly disabled, CPL relies on the presence of a thread safe CFITSIO library. In order to build a thread safe version of the CFITSIO library it has to be configured as outlined below (for detailed installation instructions please refer to the CFITSIO documentation). 1. Unpack the CFITSIO tar-archive in a temporary place, where a directory 'cfitsio' will be created, and enter it. 2. Configure the package. For being used with CPL it should be configured with the options shown here (build a shared object library, thread support compiled in): $ ./configure --prefix= --enable-shared --enable-reentrant 3. Build and install the package by running $ make $ make shared $ make install 4. If the search path of the runtime loader does not yet include the location of the CFITSIO libraries, it should be added, for instance by prepending it to the environment variable LD_LIBRARY_PATH or the appropriate equivalent (see above). Note that step 4 is essential if the system provides already a CFITSIO library which is not properly configured for CPL. After the installation is successfully completed, the CFITSIO sources are no longer needed, and may be removed. Gasgano support: ---------------- If the support library for ESO's Java based data organizing tool should be built, both, the Gasgano tool itself, and the Java Development Kit (JDK) must be present on the system. Please note that the Java Runtime Environment (JRE), which whould be sufficient to run Gasgano, is not enough to build CPL's Gasgano support library! Both packages are installed by unpacking the respective tar-archives in a suitable place, and adding the location of the executables to the PATH environment variable. In addition to that the JAVA_HOME environment variable should point to the root directory of the JDK installation. Third party libraries: ---------------------- Please follow the installation instructions shipped with the respective source packages. Installing CPL -------------- Package configuration: After all dependencies were successfully installed, the system is ready to install the CPL itself. To do so, unpack the CPL tar-archive in a directory of your choice (if you are reading this file you probably managed to do so already) and change directory into the top-level directory of the CPL source tree. The CPL source tree is setup for the target system by running the configure script found in the top-level directory of the source tree. In general, i.e. if the third party libraries were installed into non-standard directories, the configure script must be told where these libraries can be found. This can be done by either setting environment variables, which may be convenient if it is planned to install CPL more than once, or one can use command line options (if both, environment variables and command line options are used, the command line options take precedence). The following table shows for each of the third party libraries the command line option, and the equivalent environment variable which can be used to specify their location. library option environment ------- ------ ----------- CFITSIO --with-cfitsio CFITSIODIR libwcs --with-wcslib WCSDIR fftw --with-fftw FFTWDIR Both, the command line option and the environment variable expect as an argument or value respectively the path to the root directory of the library installation, i.e. if, for instance, '$HOME/cpl' is given as location of one of the third party libraries, it is expected that the header files are found in '$HOME/cpl/include' and the libraries in '$HOME/cpl/lib', or '$HOME/cpl/lib64'. In case a more fine grained control is needed when specifying third party library locations, there are also command line options which allow to give the location of headers and libraries directly. Run 'configure --h' for details. These (expert) command line options have no environment variable counterpart. If the Gasgano support library should be built and installed, the configure script has to find the JDK and the Gasgano installation. The configure script tries to find both in a few default places, but in case this does not succeed, the location of both packages can be given similar to the third party library packages. The root directory of the Gasgano installation my be given on the command line of the configure script using the option '--with-gasgano', or setting the environment variable 'GASGANODIR'. An expert option '--with-gasgano-classpath' allows to directly specify the location of the Gasgano jar files, if using the standard option '--with-gasgano' does not succeed. Usually they can be found in the subdirectory 'share' of the Gasgano installation. By default, the JDK installation is searched at the location given by the JAVA_HOME environment variable. However the root directory of the JDK installation may also be passed to 'configure' using the command line option '--with-java'. Using this option 'configure' assumes that the required C header files are found in the subdirectories 'includes' and 'includes/' of the JDK installation. Here, 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 expert 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. The target directory of the CPL installation is specified by either setting the environment variable CPLDIR to the desired path, or by using the configure command line option `--prefix'. If the target directory does not yet exist it will be created. If nothing is specified the CPL will be installed into `/usr/local' by default. Note that in this case you must have superuser privileges to install CPL! Building and Installing CPL: The following shows the necessary steps to build and install CPL. For that, it is assumed that CPL should be installed in $HOME/cpl, CFITSIO was installed in $HOME/cpl/lib and $HOME/cpl/include and fftw and wcslib are provided by the system. To configure, build and install CPL one needs to execute the following commands in the top-level directory of the source tree: $ ./configure --prefix=$HOME/cpl --with-cfitsio=$HOME/cpl --with-fftw=/usr \ > --with-wcslib=/usr $ make $ make install Optionally, the HTML reference manual can be installed executing also the command: $ make install-doxygen 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, the location of the CPL libraries has to be added to the runtime loader's search path by properly setting the LD_LIBRARY_PATH variable (or the target system's equivalent). Installing CPL on the macOS platform: ------------------------------------- CPL can be built, installed and used on this platform. To build CPL on the macOS platform, the following has to be taken into account: - On OS X 10.8 or newer a gcc installation is recommended to build CPL. The OS X 10.8 default compiler (clang) is not supported by CPL versions prior to and including CPL 6.1.1! - The symbol for the runtime loader search path is DYLD_LIBRARY_PATH and it has to replace LD_LIBRARY_PATH in the installation instructions. Reporting Bugs -------------- Please report any bugs to