Permalink
Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
279 lines (202 sloc) 9.86 KB

INSTALLING GYOTO

0- Installing precompiled packages

Gyoto comes prepackaged for some systems. Although the development version may be much more advanced at a given time, using pre-compiled binaries is the recommended way of using Gyoto for most users.

Debian GNU/Linux

Gyoto is part of Debian since Wheezy (Debian 7.0). Updated packages are made available through the official [backports infrastructure] (https://backports.debian.org/). Occasionally, even more advanced packages may be available at https://people.debian.org/~thibaut/.

You can get a list of available packages with

apt-cache search gyoto

The most recent packages will install about everything in Gyoto with

sudo apt-get install gyoto

Ubuntu

Gyoto is also part of Ubuntu at least since Raring (13.04). Updated versions are provided on our [personal package archive (PPA)] (https://launchpad.net/~paumard/+archive/ubuntu/gyoto/). Follow instructions on that page to add this PPA to your system.

You can get a list of available packages with

apt-cache search gyoto

The most recent packages will install about everything in Gyoto with

sudo apt-get install gyoto

Mac OS X

Precompiled binaries (or at least automatic compilation) is provided through [MacPorts] (http://www.macports.org/). With MacPorts installed, run:

sudo port sync
sudo port install Gyoto

To get MPI parallelization, you must first install Boost with one of its MPI variant, then Gyoto with the same variant:

sudo port install Boost +openmpi
sudo port install Gyoto +openmpi

1- Downloading the source code

If Gyoto is not packaged for your system or if you prefer to build from source, read on.

The source code is available from Github:

git clone git://github.com/gyoto/Gyoto.git

Then the build process is, in a nutshell, after having installed the dependencies:

./git-post-merge
./configure
make
sudo make install
sudo ldconfig

The rest of this file details each step.

2- Installing the dependencies

Please refer to BUGS.md for known bugs in some versions of the following dependencies.

Gyoto requires:

  • a C++ compiler. GCC 4.9 and above work very well. Several features require the C++11 standard. Clang/LLVM is discouraged, see BUGS.md.
  • xercesc-3 (recommended, required for the executable): http://xerces.apache.org/xerces-c/
  • cfitsio (required for the executable and some of the Astrobj): http://heasarc.gsfc.nasa.gov/fitsio/
  • libudunits2 (recommended, support for unit conversions): http://www.unidata.ucar.edu/software/udunits/
  • boost >= 1.53 (required, contains the integrators). See BUGS.md. http://www.boost.org/
  • an implementation of the Gauss hypergeometric function 2F1 (optional, required for Astrobj::Jet), one of:
  • an MPI implementation (tested with openmpi, optional). MPI uses boost features from boost.mpi, you must use the same version as boost.mpi is linked to.
  • Yorick (optional, provides an interface to the Yorick interpreted language, allowing to write Gyoto scripts): http://yorick.sourceforge.net/ Yorick users will also need the yorick-yutils add-on (https://github.com/frigaut/yorick-yutils) and may need to install the yorick-dev package (in particulat Debian/Ubuntu users).
  • Python (optional, provides an interface to the Python interpreted language, allowing to write Gyoto scripts). Python 2.7 and 3.4 have been tested. For building the Python bindings, the Python development files are naturally required (sometimes found in the python-dev or python3-dev package), as well as NumPy and Swig-2.0: https://www.python.org/ http://www.numpy.org/ http://www.swig.org/ Note that although fairly complete, the Python interface is likely to change in future releases. Be ready to adapt your scripts, or contact us is stability of the API is important for you.
  • LORENE (optional, the libgyoto-lorene plug-in can be built later): http://www.lorene.obspm.fr/ On some systems, LORENE must be built with -fPIC (GYOTO as well, but this is the default).
  • developers may need the GNU autotools: autoconf, automake, libtool.

3- Fixing the timestamps

Unfortunately git does not preserve the timestamps of files, which confuses the the build system. The easiest way to do that is running a provided script each time you pull from our repository:

./git-post-merge

This script contains instructions to automate this step if you plan of pulling again from github in the future.

Alternatively, you could recreate the autotools-generated files using autoreconf. This requires the development tools autoconf, automake, libtool, and is really necessary only for developpers who modfied the the build system (configure.ac, */Makefile.am...)

4- Configuring Gyoto

If all the dependencies are installed in standard places (/usr or /usr/local) and if the default prefix (/usr/local) is OK for you, this should do:

./configure

You may need to pass some options or configuration variables. To list the available options:

./configure --help

ARBLIB is known to be installed under various names depending on the Linux distribution. If using ARBLIB (see "Installing the dependencies" above), you may need to set the --with-arblib-ldflags variable to the correct name, e.g.

./configure --with-arblib-ldflags=-larb

The standard GNU INSTALL file is provided next to this file and documents the most standard and obscure features.

The --enable-release option is reserved for pre-compiled package maintainers. In short, don't use it, it is for us alone. Without this option, the library name will contain "-unreleased". This is to allow users to compile new versions without overriding the system-provided library by default. Binaries distributed e.g. by package managers should be compiled with --enable-release, but only when compiling code in the stable branch. Also, the configure script will append flags to the SONAME when features are not available, e.g. libgyoto-nompi.*. This limits the probability of linking with the wrong version of the library at run time. Note that there is no guarantee that two -unreleased builds are ABI compatible, even if they share the same SONAME, because the version information is incremented only immediately before making and official release.

To select a different compiler than the default on your system, set the CC and CXX environment variables accordingly during the configure step:

CC=gcc-4.8 CXX=g++-4.8 ./configure

Example: assume you want to install in ${HOME}/mysoft, that LORENE is in ${HOME}/mysoft/Lorene (but HOME_LORENE is not set), and Xerces and CFITIO are in /opt/local:

./configure --prefix=${HOME}/mysoft \
            --with-lorene=${HOME}/mysoft/Lorene \
            CPPFLAGS=-I/opt/local/include \
            LDFLAGS=-L/opt/local/lib

5- Building Gyoto

make

6- Testing

Gyoto includes a detailed check suite, including atomic tests writen in Yorick and Python as well as full ray-tracing tests. MPI tests and LORENE tests are run using separate Makefile targets. To run all the tests (which assumes that both Gyoto was configures with both MPI and LORENE):

make check check-lorene check-mpi check-lorene-mpi

Don't worry too much for the "severe" warnings.

You can now open the resulting FITS files with ds9 (http://hea-www.harvard.edu/RD/ds9/) or spydr (http://www.maumae.net/yorick/doc/spydr_intro.php) or any other FITS-aware image viewer:

spydr example-*.fits

7- Installing

If installing to a system location (i.e. if you don't have right access to PREFIX), you need to gain root privileges using, for instance, su or sudo:

Using su:

su - # (type root password)
make install
make -C python install

Using sudo:

sudo make install
(type your password)

Under Linux, if installing to a system location, you may need to also run

ldconfig -v

as root (so most likely sudo ldconfig -v).

8- Setting your environment

If installing in a non-standard place (e.g. under your home directory), you do not need to run ldconfig, but you need to adapt your environment for instance by adding the following lines to ${HOME}/.profile (replace <gyoto-prefix> by the actual Gyoto prefix!). One Gyoto file installed in each directory is listed as a comment:

export PREFIX=<gyoto-prefix>
export PATH=${PREFIX}/bin:${PATH}                       # gyoto
export LD_LIBRARY_PATH=${PREFIX}/lib:${LD_LIBRARY_PATH} # libgyoto*.so.*
export MANPATH=${PREFIX}/share/man:${MANPATH}           # gyoto.1
export PKG_CONFIG_PATH=${PREFIX}/lib/pkgconfig          # gyoto.pc

Under Mac OS X, LD_LIBRARY_PATH is replaced by DYLD_LIBRARY_PATH.

It goes beyond the scope of this manual to teach you how to set environment variables; if in doubt ask the local guru or google...

By default, the Yorick plug-in is also installed under ${prefix}. If Yorick itself is in ${prefix}, then the plug-in will be installed directly with the rest of Yorick and hence will be found by Yorick. On the other hand, if Yorick is not under ${prefix}, the plug-in may not be found immediately by Yorick. Assuming you used the default prefix (/usr/local), it should be sufficient to create a file named ${HOME}/Yorick/custom.i containing the three following lines:

require, "pathfun.i";
add_y_home,"/usr/local/lib/yorick/";
command_line= process_argv();

Under Debian and Ubuntu GNU/Linux, /usr/local/lib/yorick/ is by default in Yorick search paths.