How To: Compile and install tempo2

Today we are looking at how to install the pulsar timing package tempo2. If you are having problems with this a detailed troubleshooting guide will follow! This guide is based on tempo2-2011.7

1. Requirements

To build a minimal tempo2 version of tempo2 you simply need a C,C++ and fortran 77 compiler. Here we assume you are using a recent version of the GCC tools gcc, g++ and gfortran. Some plugins have extra requirements:

• To build the graphical plugins such as plk you will need pgplot.
• To build the spectral analysis plugins such as spectrum and spectralModel you will need FFTW (version 3 or later) as well as pgplot.
• To build the fermi plugin, you will need CFITSIO as well as pgplot.

2. Download - Distributable or CVS?

Before installing tempo2 you first must choose between using the distribution tarball or fetching the latest version from the CVS. The distribution tarball has the advantage that it's simpler to compile and will (most likely) compile correctly. On the other hand, using the CVS will give you access to the most cutting edge version and may have additional features not present in the distribution tarball, but requires additional steps in building.

In short, for a recent, "stable", version of the code with minimal build requirements, jump to step 2a to download the distribution tarball.
For a cutting edge version of the code, or if you want to do development work on tempo2, jump to step 2b to download via CVS.

2a. Downloading a distribution version

You can fetch the latest distribution version of tempo2 from the sourceforge website.

http://sourceforge.net/projects/tempo2/files/

At the time of writing this is tempo2-2011.7.tar.gz. Extract the tarball with:

tar -xzvf tempo2-2011.7.tar.gz
cd tempo2-2011.7/

You can now continue with step 3 - copying the tempo2 runtime files

2b. Downloading via the CVS

If you prefer to download the code through the CVS you will require the CVS software and the "GNU autotools".

As described on the tempo2 website, download the code from the anonymous CVS with:

touch $HOME/.cvspass
cvs -d:pserver:anonymous@tempo2.cvs.sourceforge.net:/cvsroot/tempo2 login

When prompted for the password, simply hit return.

cvs -z3 -d:pserver:anonymous@tempo2.cvs.sourceforge.net:/cvsroot/tempo2 co -P tempo2

Now you have to set up the build environment:

cd tempo2/
./bootstrap

This will generate the ./configure script.

3. Copy the Tempo2 runtime files

However you downloaded tempo2, you now need to copy over the "runtime" files. These include things like the solar-system ephemeris and the clock correction files. The location of these files must be pointed to by the $TEMPO2 environment variable. In our example we will put this in $HOME/tempo2runtime, but you can place it anywhere suitable. How you set this variable depends on your shell (you can check this with echo $SHELL).

For tcsh:

setenv TEMPO2 $HOME/tempo2runtime
cp -r T2runtime/ $TEMPO2

For bash:

export TEMPO2=$HOME/tempo2runtime
cp -r T2runtime/ $TEMPO2

Now we can continue to run the configure script.

4. Configure and build

Once this is done, we can procede to configure and make in the same way as most Linux style software packages. For completeness, a step-by-step guide to this process is continued below.

The first step is to run the ./configure script that is now in our build directory. This script checks our environment is set up correctly, checks for required libraries and defines what compliers are going to be used to build the software. Before we run the configure script we must have already set the $TEMPO2 environment variable as in the above section, but other useful variables to set are:

• $CC, $CXX and $F77 - These define the default compilers to use for C, C++ and Fortran 77. You will want to ensure that you are using the same version of each; this is particularlaly common issue with MacOSX where the gfortran version is often different to the system default. You may find that you need to use e.g. CC=gcc-4, CXX=g++-4 and F77=gfortran-4
• $CFLAGS and $CXXFLAGS - these define the default options to pass to the C and C++ compilers. Often this is used to specify optimisation flags or a non-standard location of header files.
• $LDFLAGS - this defines the default options to pass to the linker. Often this is used to specify non-standard location of libraries.

To run configure, we can simply type:

./configure

There are however some useful arguments to this, the most common specified below:

• --help - print all the arguments supported by configure
• --prefix=path - install tempo2 in path/bin, path/lib, etc. Be aware that this defaults to $TEMPO2
• --with-tempo2-plug-dir=path - install plugins into path. By default they are placed in $TEMPO2/plugins. IF you set this, you will want to add path to your $TEMPO2_PLUG_PATH.

After running configure there will be one of three outcomes:

1. Configure fails - there is a missing library, a problem with your environment, or your compilers are incompatible. In this case the build cannot continue until the problems are solved.
2. Configure completes, however there is a notice that some libraries (FFTW, pgplot or cfitsio) were not found. In this case you can continue to build, however some of the plugins will not be compiled unless the libraries are found.
3. Configure completes and all libraries are found. In this case you can build tempo2 and all the standard plugins!

When troubleshooting any failures in configure, it can be useful to look at the "config.log" file, which provides a detailed log of all the steps taken by configure. This file is useful to provide if you contact someone for help. A complete troubleshooting guide will feature on pulsarastronomy.net shortly.

5. Build tempo2

Now you are ready to build and install tempo2. To do this run the usual make commands:

make -j2
make install

This builds the core tempo2 code, libtempo2 and libtempo2pred (the tempo2 libraries used by other code that depends on tempo2) and installs them in your selected prefix (if you did not select a prefix, this defaults to $TEMPO2). The -j2 tells it to run two threads at once, useful for todays dual-core processors (if you have a different number of processor cores you can change this number). If make fails, see the upcoming troubleshooting guide.

6. Build plugins

You can build all the default plugins with

make plugins
make plugins-install

or build plugins individually from the plugin directory with:

cd plugin/
make name
make name-install

Where name is the name of the plugin, for example, to build the default graphical interface plk, type make plk && make plk-install from the plugin/ directory.

Plugins are installed to $TEMPO2/plugins, or a custom directory if configured with --with-tempo2-plug-dir=path.

7. Test and run

With luck, you should now have a operational copy of tempo2.

You can test your build by running:

tempo2 -h

which should list all the plugins you installed.