Installing from source code

Compiling ctools from source is the recommended method to install the package in case that you do not use Anaconda (if you use Anaconda, please follow the instructions at Installing via Anaconda, and better do not try to compile the source code against your Anaconda Python installation). You also need to compile from source if you want to use the development version of ctools.

Before you start

The procedure for building and installing ctools is modeled on GNU software distributions. You will need the following to build the software:

  • About 50 MB of free disk space.

  • An ANSI C++ compiler. ctools builds well using GNU g++ or clang.

  • make, automake, autoconf, libtools

  • gammalib (see next section).

  • Python, including the Python developer package that provides the Python.h header files. Although ctools compiles without Python and/or the Python developer package installed, compiling with Python support is highly recommended to enable dynamic scripting of ctools and developing and using of cscripts.

Installing GammaLib

ctools is built on top of GammaLib, hence GammaLib needs to be built, installed and configured before ctools can be installed. In case that ctools is already installed on your system you may skip reading this section and continue with the Building ctools section.

You will need the following to build the GammaLib:

  • About 300 MB of free disk space.

  • An ANSI C++ compiler. We recommend building GammaLib with the GNU g++ or the clang compilers.

  • make, automake, autoconf, libtools

  • The cfitsio library for FITS file support together with the developer package that provides the cfitsio.h header.

  • Python, including the Python developer package that provides the Python.h header files. Although ctools compiles without Python and/or the Python developer package installed, compiling with Python support is highly recommended to enable dynamic scripting of ctools and developing and using of cscripts.

Furthermore it is recommended to have readline and ncurses installed (including the developer packages).

After downloading the GammaLib tarball (see Download), save it in an appropriate location (for example $HOME/builds), and type

$ tar xvfz gammalib-2.0.0.tar.gz

(the $ symbol indicates the console prompt and is not part of the command that you should type in).

Step in the created directory and build, check and install gammalib by typing

$ cd gammalib-2.0.0
$ ./configure
$ make
$ make check
$ make install

The last step may require system administator privileges. In this case, use

$ sudo make install

If you do not have system administrator privileges, change the install directory by typing for example

$ ./configure --prefix=$HOME/gamma

which then installs GammaLib in the gamma folder of your home directory.

Setting up the GammaLib environment

Before building and installing ctools, you have to configure GammaLib by setting up some environment variables. This will be done automatically by an initialisation script that is found in the bin directory of the GammaLib directory (we call here “GammaLib directory” the directory into which GammaLib has been installed). Assuming that you have installed GammaLib in the default directory /usr/local/gamma you need to add the following to your $HOME/.bashrc or $HOME/.profile script on a Linux machine:

export GAMMALIB=/usr/local/gamma
source $GAMMALIB/bin/gammalib-init.sh

If you use C shell or a variant then add the following to your $HOME/.cshrc or $HOME/.tcshrc script:

setenv GAMMALIB /usr/local/gamma
source $GAMMALIB/bin/gammalib-init.csh

Building ctools

After downloading the ctools tarball (see Download), save it in an appropriate location (for example $HOME/builds), and type

$ tar xvfz ctools-2.0.0.tar.gz

(the $ symbol indicates the console prompt and is not part of the command that you should type in).

Step in the directory and build the ctools by typing

$ cd ctools-2.0.0
$ ./configure
$ make

at the operating system prompt. The ./configure command customizes the Makefiles for the particular system, the make command compiles the source files and builds the executables. Type ./configure and not simply configure to ensure that the configuration script in the current directory is run and not some other system-wide configuration script.

You can get the full list of configuration options by typing

$ ./configure --help

Testing ctools

Before installing the ctools you should execute the unit test suite to make sure that ctools have been built correctly. For this, type

$ make check

If you have automake version 1.13 or newer installed, you should see the following output at the end of the unit testing:

PASS: test_python_ctools.sh
PASS: test_python_cscripts.sh
PASS: test_examples.py
PASS: test_python_comscripts.sh
============================================================================
Testsuite summary for ctools 2.0.0
============================================================================
# TOTAL: 4
# PASS:  4
# SKIP:  0
# XFAIL: 0
# FAIL:  0
# XPASS: 0
# ERROR: 0
============================================================================

For older automake version, you should see

***********************
* ctools unit testing *
***********************
Test ctobssim on command line: ...... ok
Test ctobssim from Python: ................................................... ok
Test ctselect on command line: ........ ok
Test ctselect from Python: .............................................................. ok
...
PASS test_python_ctools.sh

*************************
* cscripts unit testing *
*************************
Test cscript base class: ............................................................................................................................... ok
Test ctobservation base class: ............................................. ok
Test ctlikelihood base class: ... ok
Test csbkgmodel on command line: ..... ok
...
PASS test_python_cscripts.sh

********************
* Examples testing *
********************
Test make_pointings.py: ....... ok
Test show_butterfly.py: ... ok
Test show_irf.py: .. ok
Test show_lightcurve.py: .. ok
...
PASS test_examples.py

***************************
* comscripts unit testing *
***************************
Test comobsselect on command line: .... ok
Test comobsselect from Python: .. ok
Test comobsbin on command line: .............................. ok
Test comobsbin from Python: ........................... ok
...
PASS test_python_comscripts.sh
==================
All 4 tests passed
==================

The same detailed information is also available for the newer automake versions, but there it is written in log files that you can find in the test directory of the ctools:

test_python_ctools.sh.log
test_python_cscripts.sh.log
test_examples.py.log
test_python_comscripts.sh.log

If you do not see the same output, but a failure message, please check first the Known issues section. If you cannot fix the problem, please create an issue on the ctools tracker here.

Installing ctools

Now you are ready to install the ctools by typing

$ make install

If the destination directory is owned by root (which is normally the case when using the default), administrator privileges are needed for installation. In this case, type

$ sudo make install

By default, the install directory is set to /usr/local/gamma. To change the install directory (for example in case that you do not have system administrator privileges), an optional --prefix argument can be given, for example:

$ ./configure --prefix=$HOME/gamma

Setting up the ctools environment

You have to configure ctools by setting up some environment variables. This will be done automatically by an initialisation script that is found in the bin directory of the ctools installation. Assuming that you have installed ctools into /usr/local/gamma you need to add the following to your $HOME/.bashrc or $HOME/.profile script on a Linux machine:

export CTOOLS=/usr/local/gamma
source $CTOOLS/bin/ctools-init.sh

If you use C shell or a variant then add the following to your $HOME/.cshrc or $HOME/.tcshrc script:

setenv CTOOLS /usr/local/gamma
source $CTOOLS/bin/ctools-init.csh

Checking your setup

Now you should be ready to get started using Gammalib and ctools.

As a quick check that your setup is okay you can run csinfo check:

$ csinfo check

Gammalib / ctools setup check:

   GAMMALIB environment variable ... ok
   CTOOLS   environment variable ... ok
   gammalib Python import .......... ok
   ctools   Python import .......... ok
   cscripts Python import .......... ok

   ===> Your Gammalib / ctools setup is OK.

If the setup is not okay, run the csinfo info command to print detailed information about your setup. There’s also a csinfo list command to quickly list the available tools.

Known problems

In case you encounter problem, please check the list of known Installation issues. If you encounter problems during the GammaLib installation, please check the list of known GammaLib issues. If you cannot solve your problems, please create an issue on the ctools tracker here.