gstlal Installation Instructions
================================


Overview
========

These instructions have been developed specifically for the gstlal
workshop, and cover the installation on LSC clusters only (tested on Atlas
and CIT).  gstlal is known to work on Debian Testing, and Mac OS/X but the
installation sequence is different than what is described here.

gstlal is a project that links together LAL and its associated libraries
with GStreamer and so requires all of those tools to be installed,
including the normally optional development-related components.  Once the
dependencies are installed, the installation of gstlal itself should be
straight-foward.

In what follows, read each section completely before starting that section
to ensure you understand all that you will be required to do.

These instructions include the installation of lalsuite.  No special
configuration of lalsuite is required, and if you have an installation
already and wish to use it you may do so.  Note, however, that the
instructions here set environment variables and configure command lines
based on the assumption that your lalsuite installation will be configured
as in these instructions.  If you wish to use your own installation you
will need to understand how to adjust these things.  If you attempt to do
so and have difficulties, please attempt to follow the instructions here
before reporting problems.


Preparing the Filesystem
========================

The following is the filesystem layout I (Kipp) use.  Of course other
arrangements are possible, and you are welcome to experiment, but if you
have difficulties please try this arrangement before reporting problems.

  local/
    bin/
    include/
    lib/
    ... and so on ...
    src/
      gst-plugins-bad/
      gst-plugins-base/
      gst-plugins-good/
      gst-python/
      gstlal/
      gstreamer/
      lalsuite/
        glue/
        lal/
        lalapps/
        ... and so on ...

Prepare the filesystem by doing the following.  Choose where you want
local/ to reside (I put it in my home directory, but you might prefer to be
more organized than that), then in that directory type

  $ mkdir local
  $ mkdir local/src

The rest of the tree will be created as software is downloaded and
installed.

Throughout the remainder of the instructions, where you see /path/to/local/
you are to replace that with the full path of your local/ directory.


Preparing the Environment --- Disable LSCSoft
=============================================

Disable the system-wide lscsoft installation by doing

  $ cd ${HOME}
  $ touch .nolscsoft

then, on Debian systems, manually re-enable libframe and libmetaio by
adding

  export PKG_CONFIG_PATH="/opt/lscsoft/libframe/lib/pkgconfig:${PKG_CONFIG_PATH}"
  export PKG_CONFIG_PATH="/opt/lscsoft/libmetaio/lib/pkgconfig:${PKG_CONFIG_PATH}"

to ${HOME}/.bash_profile, or wherever you set variables like this.  On
CentOS systems, replace lib/ with lib64/ as in

  export PKG_CONFIG_PATH="/opt/lscsoft/libframe/lib64/pkgconfig:${PKG_CONFIG_PATH}"
  export PKG_CONFIG_PATH="/opt/lscsoft/libmetaio/lib64/pkgconfig:${PKG_CONFIG_PATH}"

Log out of your account, log in again, and confirm that pkg-config returns
the correct directories for these two libraries with

  $ pkg-config --cflags libframe libmetaio
  -I/opt/lscsoft/libmetaio/include -I/opt/lscsoft/libframe/include


Preparing the Environment --- Setup Script
==========================================

Now create the environment setup script for the software to be installed in
your home directory.  On Debian systems do this with

  $ cd /path/to/local/
  $ cat >environment.sh <<_EOF_
  export PATH="/path/to/local/bin:\${PATH}"
  export PKG_CONFIG_PATH="/path/to/local/lib/pkgconfig:\${PKG_CONFIG_PATH}"
  export PYTHONPATH="/path/to/local/lib/python2.5/site-packages:\${PYTHONPATH}"
  _EOF_

or, on CentOS systems do this with

  $ cd /path/to/local/
  $ cat >environment.sh <<_EOF_
  export PATH="/path/to/local/bin:\${PATH}"
  export PKG_CONFIG_PATH="/path/to/local/lib/pkgconfig:\${PKG_CONFIG_PATH}"
  export PYTHONPATH="/path/to/local/lib64/python2.4/site-packages:/path/to/local/lib/python2.4/site-packages:\${PYTHONPATH}"
  _EOF_

Note that in both cases your system might use an older or newer version of
Python than indicated above.  Check your Python version, and change the
"pythonX.Y" parts of the paths if need.

Once you have constructed environment.sh with those four environment
variables in it

  $ source /path/to/local/environment.sh

You will need to do this every time you wish to use or do development work
with the software.  It might make sense to put this in your login scripts
(but if you choose to do so, remember that you have done this!).


Downloading and Installing GStreamer Dependencies --- CentOS Bonus
==================================================================

GStreamer requires a newer version of flex than is available on CentOS.  If
you are using CentOS, then before proceeding, you will need to install

 * flex >= 2.5.35

The following instructions will download and install this software package
into your /path/to/local prefix

  $ cd /path/to/local/src
  $ wget http://prdownloads.sourceforge.net/flex/flex-2.5.35.tar.gz
  $ tar -xzf flex-2.5.35.tar.gz
  $ pushd flex-2.5.35
  $ ./configure --prefix=/path/to/local && make install
  $ popd


Downloading and Installing GStreamer Dependencies
=================================================

Building gstreamer on Debian Lenny (the OS found on the Atlas cluster) or
on CentOS (the OS found on the CIT cluster) will require you to install

 * glib >= 2.20.5
 * pygobject >= 2.14.2
 * pygtk >= 2.8.6

The following instructions will download and install these three software
packages into your /path/to/local prefix

  $ cd /path/to/local/src
  $ wget http://ftp.gnome.org/pub/GNOME/sources/glib/2.20/glib-2.20.5.tar.gz
  $ wget http://ftp.gnome.org/pub/GNOME/sources/pygobject/2.14/pygobject-2.14.2.tar.gz
  $ wget http://ftp.gnome.org/pub/GNOME/sources/pygtk/2.8/pygtk-2.8.6.tar.gz

  $ tar -xzf glib-2.20.5.tar.gz
  $ pushd glib-2.20.5
  $ ./configure --prefix=/path/to/local && make install
  $ popd

  $ tar -xzf pygobject-2.14.2.tar.gz
  $ pushd pygobject-2.14.2
  $ ./configure --disable-glibtest --prefix=/path/to/local && make install
  $ popd

  $ tar -xzf pygtk-2.8.6.tar.gz
  $ pushd pygtk-2.8.6
  $ ./configure --disable-glibtest --prefix=/path/to/local && make install
  $ popd


Downloading and Installing GStreamer
====================================

GStreamer is the suite of C and Python libraries for multimedia stream
processing on which gstlal is constructed.  gstlal requires

 * gstreamer >= 0.10.30.4
 * gst-plugins-base >= 0.10.30.4
 * gst-plugins-good >= 0.10.25.4
 * gst-plugins-bad >= 0.10.20
 * gst-python >= 0.10.19.4

The following instructions will download and install the gstreamer packages
needed by gstlal into your /path/to/local prefix

  $ cd /path/to/local/src/
  $ wget http://gstreamer.freedesktop.org/src/gstreamer/pre/gstreamer-0.10.30.4.tar.gz
  $ wget http://gstreamer.freedesktop.org/src/gst-plugins-base/pre/gst-plugins-base-0.10.30.4.tar.gz
  $ wget http://gstreamer.freedesktop.org/src/gst-plugins-good/pre/gst-plugins-good-0.10.25.4.tar.gz
  $ wget http://gstreamer.freedesktop.org/src/gst-plugins-bad/gst-plugins-bad-0.10.20.tar.gz
  $ wget http://gstreamer.freedesktop.org/src/gst-python/pre/gst-python-0.10.19.4.tar.gz
  $ wget --no-check-certificate https://www.lsc-group.phys.uwm.edu/daswg/projects/gstlal/audioresample.patch

Read all of the following before starting the installation sequence.
Install the components in the order gstreamer, gst-plugins-base,
gst-plugins-good, gst-plugins-bad, gst-python using

  $ tar -xzf packagename.tar.gz
  $ pushd packagename
  $ ./configure --prefix=/path/to/local && make -j install
  $ popd

with the following exceptions

 * gst-plugins-base requires a patch applied to it;  between pushd and
   configure add the command

  $ patch -p1 <../audioresample.patch

 * on CentOS gst-python requires a modified configure command

  $ ./configure --prefix=/path/to/local --with-libpython-dir=/usr/lib64

NOTE:  the builds produce many warnings indicating that this-or-that plugin
will not be built due to missing dependencies.  Ignore them.


Downloading and Installing LALSuite
===================================

In the directory

  $ cd /path/to/local/src

clone the lalsuite repository by following the instructions on the LAL
project page.  Install lalsuite in the order glue, lal, lalframe,
lalmetaio, lalburst, lalinspiral, lalpulsar, lalstochastic, lalapps, pylal,
using

  Start:

  $ pushd lalsuite

  For C components:

  $ pushd directory
  $ ./00boot && ./configure --prefix=/path/to/local && make -j install
  $ popd

  For Python components:

  $ pushd directory
  $ python setup.py install --prefix=/path/to/local
  $ popd

  Done:

  $ popd

DO NOT set any environment variables except as directed in these
instructions.  DO NOT source any "user-env" scripts except as directed in
these instructions.


Downloading and Installing gstlal
==================================

The following will clone the gstlal source tree giving you read-only access

  $ cd /path/to/local/src/
  $ git clone git://ligo-vcs.phys.uwm.edu/gstlal.git

or, if you have ligo.org credentials you can obtain a read-write clone of
the gstlal source tree with

  $ cd /path/to/local/src/
  $ git clone ssh://albert.einstein@ligo-vcs.phys.uwm.edu/usr/local/git/gstlal.git

Install gstlal with

  $ pushd gstlal
  $ ./00init.sh && ./configure --prefix=/path/to/local && make -j install
  $ popd


Verifying the Installation
==========================

From your home directory, to check that each component is installed
correctly, do the following.

lal/lalapps
-----------

  $ which lalapps_version

should print /path/to/local/bin/lalapps_version, and

  $ ldd $(which lalapps_version)

should indicate that liblalburst.so.0 is being obtained from a directory
under /path/to/local, while libFrame.so.1 is being obtained from
/opt/lscsoft/libframe, and libmetaio.so.1 is being obtained from
/opt/lscsoft/libmetaio.  Finally,

  $ python -c "from lalapps import power ; print power.__file__"

should not produce an error, and should print a filename located in the
/path/to/local directory tree.


glue
----

  $ python -c "from glue import segments ; print segments.__file__"

should not produce an error, and should print a filename located in the
/path/to/local/ directory tree.


pylal
-----

  $ python -c "from pylal import datatypes ; print datatypes.__file__"

should not produce an error, and should print a filename located in the
/path/to/local/ directory tree, and

  $ ldd /path/to/local/lib*/python*/site-packages/pylal/xlal/fft.so

should not produce an error, and should show that liblal.so.0 is provided
by a file located in the /path/to/local directory tree.


gstreamer
---------

  $ which gst-inspect

should print /path/to/local/bin/gst-inspect, and

  $ gst-inspect coreelements

should indicate that the Filename is in /path/to/local/lib/... .  To test
for the audioresampler's gap-aware patch

  $ gst-inspect audioresample

should list gap-aware under Element Properties.


gstlal
------

  $ gst-inspect gstlal

should report information on the gstlal plugin, showing a Filename in the
/path/to/local/lib/... tree, and there should be several elements provided
by the plugin; and

  $ ldd /path/to/local/lib/libgstlal.so

should not produce an error, and should show that libgstbase-0.10.so.0,
libgstreamer-0.10.so.0, libgobject-2.0.so.0, libgmodule-2.0.so.0,
libgthread-2.0.so.0 and libglib-2.0.so.0 are all provided by files located
in the /path/to/local directory tree; and

  $ python -c "from gstlal import pipeparts ; print pipeparts.__file__"

should not produce an error, and should print a filename located in the
/path/to/local/ directory tree.  Finally,

  $ gst-inspect python

should not report an error, should indicate that the Filename is in
/path/to/local/lib/.., and several gstlal-related elements should be
listed.