In this file:

* About the VIMOS pipeline
* Availability
* Installing the VIMOS pipeline
*   Supported Platforms
*   Prerequisites
*   Compiling the Common Pipeline Library 
*   Compiling the VIMOS pipeline
* Running the recipes
* Related Information
* Reporting Bugs


About the VIMOS pipeline:
-------------------------

This is version 1.3.1 of the VIMOS instrument pipeline.

This package contains the VIMOS pipeline recipes for processing the 
imaging and spectroscopy data generated by VIMOS in direct imaging,
the multi-objetc spectroscopy mode, and the IFU spectroscopy mode.

The VIMOS pipeline is free software, you can redistribute it and/or
modify it under the terms of the GNU General Public License.


Availability:
-------------

The latest stable release of the VIMOS pipeline libraries and recipes
is always available from `ftp://ftp.eso.org/pub/cpl/vimos'.


Installing the VIMOS pipeline:
------------------------------

Supported platforms:
--------------------

The VIMOS Pipeline has been verified on the VLT target platforms:

  - HP-UX 11.00 or later,
  - Linux (glibc 2.1 or later),
  - Sun Solaris 2.8 or later,

using the GNU C compiler (version 3.2 or newer). It should be possible
to build the VIMOS pipeline on other UN*X variants too, but support is
only provided for the platforms listed above.

Note: It is known that the current version of the VIMOS pipeline does
      not compile on Mac OS X.


Availability:
-------------


Prerequisites:
--------------

To compile and install the VIMOS Pipeline one needs:

  - the GNU C compiler (version 3.2 or later),
  - the GNU gzip data compression program,
  - a version of the tar file-archiving program, and,
  - the GNU make utility.

Furthermore, an installation of the Common Pipeline library (CPL) must be
available on the system. Currently CPL version 1.0.1 or newer is required.
The CPL destribution can be obtained from `http://www.eso.org/cpl'.

CPL itself depends on an installation of the qfits FITS I/O
library. The qfits sources are available from the CPL download page or
directly from the qfits homepage at `http://www.eso.org/projects/aot/qfits'.
For CPL 1.0.1 one must use qfits 4.3.5. Later versions of CPL support
also newer versions of qfits.

In order run the VIMOS pipeline recipes a front-end application is also
required. Currently there are two such applications available, a
command-line tool called `EsoRex' and the Java based data file organizer,
`Gasgano', which provides an intuitive graphical user interface. At least
one of them must be installed to be able to use the recipes. The `EsoRex'
and `Gasgano' packages are available at `http://www.eso.org/cpl/esorex.html'
and `http://www.eso.org/gasgano' respectively.

For installation instructions of any of the additional packages please
refer to the documentation of these packages. 


Compiling the Common Pipeline library:
--------------------------------------

In the following the installation of the qfits and CPL distributions
is outlined. For detailed instructions and further configuration
options please refer to the documentation of the individual packages.

Since CPL requires the qfits library it must be installed first:

  1. Unpack the qfits package.

  2. Go to the top-level directory of the unpacked qfits source tree

  3. Setup the sources by executing

       $ ./configure --enable-shared --prefix=<installation path>

     at the shell's prompt. This sets up the package and prepares for
     an installation into the directory passed as argument of the 
     `--prefix' option.

     Important: Qfits contains a fixed sized pointer buffer which
                needs to be enlarged for the VIMOS recipes. For qfits
                4.3.5 the only way to adjust the buffer size is to
                edit the file `config.make' which will be created when
                the qfits `configure' program is executed.

                Edit this file and remove all xmemory related entries
                (entries starting with `-DXMEMORY') from the line
                starting with `CFLAGS'.

                Then add `-DXMEMORY_MAXPTRS=32768' to the end of this
                line and continue with the qfits installation.

  4. Build and install the library by executing
     
       $ make static dynamic
       $ make install

     at the system prompt.

This completes the qfits installation. Now the Common Pipeline Library
can be installed:

  1. Unpack the CPL package.

  2. Go to the top-level directory of the unpacked CPL source tree.

  3. Set up the source tree. CPL follows the standard GNU installation
     procedure. To customize the installation the command line options
     of the `configure' script can be used. A typical command line 
     will look like:

       $ ./configure --enable-debug --with-qfits=<qfits directory> \
       > --prefix=<installation path> 
  
     This compiles CPL with debugging support and the libraries will
     be installed into the directory indicated by the argument of the
     `--prefix' option. The location of the qfits installation (the
     root directory of the installation, i.e. it contains the
     directories `include' and `lib' containing the qfits headers and
     libraries respectively) which will be used is also given on the
     command line. As an alternative the environment variable QFITSDIR
     may be used.

     By default both, the static and the shared libraries are built. 

  4. Build and install the CPL typing

       $ make
       $ make install

     at the system prompt. To install the on-line HTML documentation
     execute

       $ make install-html


Compiling the VIMOS pipeline:
-----------------------------

The VIMOS pipeline follows the standard GNU installation procedure,
please refer to the file INSTALL for details.

To prepare the VIMOS pipeline source tree the location of the
libraries the VIMOS pipeline depends on (qfits, CPL) must be
given. The location of the qfits and the CPL libraries may be 
given on the command line, using the options `--with-qfits',
`--with-cpl', and `--with-cext', when runnig the `configure' script,
or by defining the environment variables QFITSDIR and CPLDIR.

The path which has to be used as argument of the options or as the
value of the variables is always the root directory of the
installed package.

Assuming that the environment variables are used and are defined
properly the VIMOS pipeline is built and installed by the steps:

  1. Unpack the VIMOS pipeline distribution.

  2. Go to the top-level directory of the unpacked source tree.

  3. Run the `configure' script with suitable options. A typical
     command line will look like:

       $ ./configure --prefix=<installation path>

     If no `prefix' is given, the `configure' script will use the
     environment variable PIPE_HOME if it is defined, and the default
     path `/usr/local' otherwise.

  4. Execute 

       $ make
       $ make install

     from the shell's prompt.


  5. Make sure that the directories which contain the qfits, CPL and
     VIMOS libraries (usually <installation path>/lib) are added to
     the LD_LIBRARY_PATH environment variable.

This completes the VIMOS pipeline installation. The VIMOS recipes are
ready to run.


Running the recipes:
--------------------

The VIMOS pipeline recipes are not executables, but dynamically
loadable modules, or simply plugins. Therefore one needs a front-end
application to execute these plugins. The advantage of this
architecure is that the same VIMOS pipeline installation can be used
by different front-ends, and can be easily embedded into different
run-time environments.

Currently two front-ends are available. A command line tool called
`EsoRex' and a graphical data file organizer called `Gasgano'. They
are available from `http://www.eso.org/cpl/esorex.html' and 
`http://www.eso.org/gasgano' respectively.

For instructions how to use the VIMOS recipes with any of these
front-ends please refer to the documentation coming with both
packages.

An outline of the configuration of both tools can also be found in the
VIMOS pipeline User's Guide, which can be obtained from 
`http://www.eso.org/projects/dfs/dfs-shared/web/vlt/vlt-instrument-pipelines.html'.


Related Information:
--------------------

For more information about the various packages mentioned here, please
have a look at the following links.

  http://www.eso.org/projects/aot/qfits
  http://www.eso.org/cpl
  http://www.eso.org/cpl/esorex.html
  http://www.eso.org/gasgano
  http://www.eso.org/projects/dfs/dfs-shared/web/vlt/vlt-instrument-pipelines.html


     
Reporting Bugs:
---------------

Please send bug reports and feedback to <usg-help@eso.org>.