Advanced Installation

Before reading this document, please familiarize yourself with the short Installation guide.

What the installation process does

The term "installation" in the title is used for brevity, and it actually covers all three steps: configuration, build and install.

1. Configure: determine what tools are available on the system and how they should be used to built the software. Creates a layer of abstraction so that the build is platform-independent. Should ideally either solve or flag all problems, so that the build either works, or does not proceed at all.
2. Build: compiles the software and documentation using RSFSRC/build as a "workplace"
3. Install: moves the compiled executables and the documentation to the final locations in $RSFROOT, sometimes changing filenames. Kept separate from build so that it can be done by root, and to avoid build failures leaving junk files all over the system.

A successful installation will have created in $RSFROOT the following directories:

• bin/: executable programs
• doc/: auto-generated HTML documentation
• include/: header files with info on library procedures; fonts
• lib/: libraries and Python modules

Prerequisites

Basic prerequisites are described in the short Installation guide. Here are some additional details.

Python and SCons

As described below in under Platform-specific installation advice, Madagascar supports the oldest non-deprecated Python version currently supported by the latest stable version of SCons. If your version of Python is older and you experience problems you should probably upgrade.

Madagascar includes the latest stable version of SCons and the configure scripts will try to install it for you in RSFROOT if you don't have it already. However, if you have an older version of SCons the configure scripts will not try to install the newer version. Your older version might work fine, but Madagascar attempts to support only the latest stable version of SCons, so if you have problems you should upgrade.

To install the SCons bundled with Madagascar go to RSFSRC/scons, unpack the tar file, and type

<bash> python setup.py install </bash>

This will install SCons in the standard location. You might need root privileges. If you don't have root privileges, or you don't want to interfere with the system SCons you can install it somewhere else with a --prefix option. A logical choice is to put it in RSFROOT like this:

<bash> python setup.py install --prefix=$RSFROOT </bash>

Location

As long as you set the environment variables and directory permissions correctly, it does not matter in what part of your filesystem you place the install. If you have the luxury of installing anywhere, it is good practice to follow the Filesystem Hierarchy Standard and either:

1. Install everything (including figs if you do testing) under /usr/local/rsf, with the source tree in /usr/local/rsf/src, OR
2. Put the source tree in /usr/local/src/rsf, and specify RSFROOT=/usr/local, so that header files and binaries go in /usr/local/bin and /usr/local/include. To follow the standard, before installing set RSFDOC=/usr/local/share/rsf/doc and create the appropriate directories. The auto-generated HTML documentation will get put there. Also, if installed, the figs directory for testing should be /usr/local/share/rsf/figs/.
3. Package Madagascar (i.e. build a RPM, etc) and install it in the default locations. For RPMs, those are as like the ones from the previous option, just directly in the /usr/ hierarchy, instead of in the /usr/local/ one.

Disk space

At present (Feb 2007, r2530), the source directory containing the build tree from the development version was approx. 200Mb, the full installation (bin/, doc/, include/ and lib) is 31Mb, and figs/ (the optional directory if you want to do testing) is about 10 Gb. The stable version is significantly smaller.

The only Madagascar-related directory where disk space can be an issue is $DATAPATH. Real 3-D seismic datasets can be measured in Terabytes. Buggy programs/processing flows can fill up $DATAPATH. A real problem are "disk memory leaks" -- removing header files with anything else than sfrm will leave the binaries intact. Crashed jobs which start to write to binary but never get to write the header also produce "leaks". Experience has shown that over time $DATAPATH inexorably fills up. You may need to

1. keep irreplaceable data and expensive results in a separate place;
2. remove the oldest files in $DATAPATH whenever the amount of free space declines under a preset threshold.

Dependencies

Some platforms feature complete lists of dependencies. See Platform-specific installation advice for details.

C++ API

A C++ compiler. SCons is smart and will try to find it for you. If it does not work specify the path to your compiler in the CXX environment variable (can be passed as an option to the configuration script, like the API one).

F77 API

A Fortran 77 compiler. If SCons does not find one, then you can either specify its path through the F77 variable, or if the executable is in your path, add its name to the list of F77 compilers in RSFSRC/configure.py .

F90 API

Same as for Fortran 77 – just substitute F90. If using the gfortran compiler, make sure to get the latest version.

Matlab API

Besides Matlab itself, you need Mex, which compiles C code into regular Matlab functions. Use the MATLAB and MEX environment variables to specify their paths if they are installed, but not found.

Octave API

The Octave function compiler (mkoctfile) is sometimes bundled in a separate package, so it may be missing from the Octave installation. If you cannot get mkoctfile installed, but still want some limited functionality of this API, specifying APIFORCE=y during the configuration.

Python API

This API requires SWIG and numpy. Numpy requires Python 2.4 or newer (i.e. RHEL 5 or newer). However, these dependencies are unnecessary for the common case when Python is just used as glue to create chains of programs, and it only needs to read the RSF header, and not the binary. To allow Python metaprograms in madagascar to function, and programming in this style to be done, a fallback development kit implementing only the header-related functionality will be installed in the lack of these dependencies.

Python modules in user space

Python is an evolving language. Many large systems have old versions for stability reasons, and administrators of such large systems tend to not install all software users may wish, and to not allow access to rpm either. To install a module in your user space, download the tarball, unzip it, cd into the directory and run:

python setup.py install --prefix=/path/to/your/place

The installer will create a subdirectory named lib, or lib64 under the directory above. These lib* dirs will have a directory named python, or python2.3 for example, and those will have a subdirectory named site-packages. Add all paths to these site-packages subdirectories in your PYTHONPATH environment variable. Some (numpy) may create a bin directory that needs to be added to PATH.

Environment variables

Used by the Madagascar core

Besides RSFROOT, DATAPATH and PYTHONPATH (described in the short Installation guide), Madagascar programs may read the variables below. They usually have reasonable defaults and were introduced just to provide more power to the advanced user.

Variables introduced by Madagascar's non-graphic programs
Name	Default	Meaning
RSF_DATASERVER	ftp://egl.beg.utexas.edu/	Data server for benchmark datasets
RSFDOC	$RSFROOT/doc	Directory for the HTML self-doc
RSFFIGS	$RSFROOT/figs	Directory with figures for testing
RSFMEMSIZE	100	Maximum RAM (Mb) to be used by some programs
RSFSRC	undefined	Root of the Madagascar source tree
TMPDATAPATH	$DATAPATH	Datapath for temporary files on local disk.
LATEX2HTML	undefined	LateX2HTML customization directory

Variables introduced by Madagascar graphics programs
Name	Default	Meaning
DEFAULT_PAPER_SIZE	"letter"	For pspen. Other options: legal, a3, a4, a5.
FATMULT	?	Fatness multiplication factor.
GIFBORDER	0.25	For vplot2gif (spacing)
GIFDELAY	100	For vplot2gif (for animations)
IMAGE_TYPE	'png'	Icon type for LateX2HTML
PATTERNMULT	None	Pattern multiplication factor
PLOTSTYLE	None	Used in vplot
PPI	75	For vplot2gif (screen resolution)
PPMSCALE	1	For vplot2gif
PSBORDER	0.05	For vplot2eps (border around the plot)
PSPRINTER	postscript or colorps	For pspen
PSTEXPENOPTS	color=n fat=1 fatmult=1.5 invras=y	Other vplot2eps options
VPLOTFONTDIR	?	Dir with backup fonts in case the runtime-loaded vplot fonts are not found
VPLOTSPOOLDIR	/tmp	Where to put vplot tmp files
WSTYPE	"default"	Workstation type.

Variables set by OS/other apps, read-only to Madagascar
Name	Primarily used/set by
CWPROOT	Seismic Unix
DISPLAY	Operating System (OS)
HOME	OS
LD_LIBRARY_PATH	linker
MATLABPATH	Matlab
XAUTHORITY	X-Windows

For future documentation writers: the environment variables read by Madagascar can be found by going to $RSFSRC, temporarily moving the directory build/ outside RSFSRC, and typing <bash> grep environ.get *.py */*.py */*/*.py */*/*/*.py grep getenv */*.c */*/*.c */*/*/*.c </bash>

Used by the Madagascar build process

Type scons -h in RSFSRC to get a list of environment variables that affect the build process, with explanations, defaults and actual values. Below are more detailed explanations for some of them:

• APIFORCE: If APIFORCE=y, those API components that do not have dependencies will be nevertheless installed. This is the case of scripts in interpreted languages which call standalone Madagascar programs. This option is provided for allowing a limited functionality to those who cannot install dependencies, while not annoying those who may want specifically to NOT have an API installed because of namespace conflicts or other reasons.

Used by the Matlab API

To use the Matlab API, you need to add $RSFROOT/lib to MATLABPATH

Used by the Octave API

To use the Octave API, you need to add $RSFROOT/lib to Octave's path. Determine Octave's version with <bash> octave -v | head -1 </bash> If your version is lower than 2.9.6, type at a Unix command line: <bash> echo 'LOADPATH = "::$RSFROOT/lib/octave"' >> ~/.octaverc </bash> For later versions, use: <bash> echo 'addpath([getenv("RSFROOT") "/lib/octave"])' >> ~/.octaverc </bash>

RSFROOT for NFS-shared user home directories

Heterogeneous networks with user home directories shared through NFS are quite common in many institutions. In addition, even when the architecture is the same (i.e. 64-bit) and the operating system is the same (i.e. RHEL), the difference between operating system versions may be very significant because clusters may run legacy versions, while desktop workstations may run the latest-and-greatest (even beta), and entirely different Madagascar versions may be needed to support both.

One possible solution of detecting the distribution version and architecture and setting RSFROOT appropriately is shown below. In the example network, all RHEL4 machines have the same architecture, but there are RHEL 3 machines with several architectures: <bash> REDHAT_RELEASE=`awk -F'release' '{ print $2 }' /etc/redhat-release | awk -F' ' '{ print $1 }'`

RSFROOT=/usr/local/rsf/rhel$REDHAT_RELEASE

if [ $REDHAT_RELEASE == '4' ] ; then

   export RSFROOT

elif [ $REDHAT_RELEASE == '3' ] ; then

   export RSFROOT=$RSFROOT/$ARCH

fi </bash> Of course, the Madagascar administrator will have to download appropriate versions of Madagascar to each $RSFROOT, and compile them on the appropriate system.

Platform-specific installation advice

Supported platforms

Madagascar attempts to support any POSIX-compliant operating system demanded by users. For systems that bundle Python (i.e. Linux distributions, BSDs), backwards compatibility will attempt to cover those systems that were bundled with the oldest non-deprecated Python version currently supported by the latest stable version of SCons. For example, in early 2009 the stable SCons release (1.2) supported Python 2.2 or newer. Python 2.2 was bundled by RHEL3, so RHEL 3 and newer are supported.

Attempts for backward compatibility with a given operating system are also stopped if the operating system itself becomes unsupported. For example, Python 2.2 was bundled by Fedora 1 and newer, but currently only Fedora 9 and 10 are actively maintained. Thus, Madagascar does not attempt to support Fedora 1, even though it included Python 2.2.

Please keep in mind that the above statements constitute only general guidelines for what will be attempted, and do not constitute in any way a warranty of support.

Ubuntu 6.06-8.10

Under the platform support guidelines above, and considering the Ubuntu Life Cycle, Madagascar will attempt to support:

• Ubuntu 6.06 LTS Desktop until end of June 2009
• Ubuntu 6.06 LTS Server until end of June 2011 or until SCons stops supporting Python 2.4, whichever comes sooner
• Ubuntu 7.10 until end of April 2009
• Ubuntu 8.04 LTS Desktop until end of April 2011 or until SCons stops supporting Python 2.5, whichever comes sooner
• Ubuntu 8.04 LTS Server until end of April 2013 or until SCons stops supporting Python 2.5, whichever comes sooner
• Ubuntu 8.10 until end of April 2010 or until SCons stops supporting Python 2.5, whichever comes sooner
• Ubuntu 9.04 until end of October 2010 or until SCons stops supporting Python 2.5, whichever comes sooner
• Ubuntu 9.10 until end of April 2011 or until SCons stops supporting its Python version, whichever comes sooner

You can install all of Madagascar's dependencies by running

sudo apt-get install g++ g77 libc6-dev libjpeg62-dev libx11-dev libxaw7-dev libnetpbm10-dev swig python-dev python-scipy python-numpy units

Fedora 9, 10

Under the platform support guidelines above, Madagascar will attempt to support the last two versions of Fedora (currently 9 and 10). Considering the Fedora Life Cycle (release X maintained until one month after the release of X+2) and the Fedora 11 schedule, Fedora 9 should be dropped and Fedora 11 should be supported starting with 2009-06-26.

You can install the common dependencies for both the stable version and the development one, by typing as root:

yum -y install atlas atlas-devel binutils blas blas-devel freeglut freeglut-devel gcc \
gcc-c++ gcc-gfortran glibc-headers libjpeg-devel libXaw-devel netpbm-devel numpy octave \
octave-devel scipy scons swig units 

Packages that are already installed will be ignored.

If you are using the development version, you also need the subversion package. If you are installing on a multicore machine, you will get a speedup if you install libgomp.

CentOS 3, 4, 5

Given that CentOS is a clone of RHEL, it is expected it will have the same lifecycle (7 years of support after release), CentOS 5 should be supported by Madagascar until 2014-03-14, or until SCons stable version ceases to support Python 2.4 – whichever comes first. CentOS 4 should be supported until 2012-02-15 or until SCons stable drops support for 2.3. CentOS 3 should be supported until 2010-10-22 or until SCons stable drops support for Python 2.2, whichever comes first.

To install and maintain the crucial SCons dependency using package management, you first need to add RPMforge's RHEL5 repository to your local list .

Dependencies can be installed from the repositories with:

yum -y install binutils freeglut freeglut-devel gcc gcc-c++ gcc-gfortran \
glibc-headers libjpeg-devel libXaw-devel netpbm-devel scons units 

A few dependencies ( octave, octave-devel, numpy, scipy and units) are not in the repositories, so they must be searched for and installed manually if you need them. Fortunately, none of the missing packages is crucial enough to stop the core Madagascar installation; they are needed only by optional components.

Debian 4, 5

Under the platform support guidelines above, Madagascar will attempt to support Debian 4 until it stops being supported by its developers (end 2009-beg. 2010), and Debian 5 until it stops being supported by the Debian project or SCons stops supporting Python 2.5, whatever comes sooner.

Specific dependencies:

• Debian 4.0 ("Etch"): In order to build xtpen (for displaying .vpl images) you will need the libXaw7-dev package.
• Debian 5.0 ("Lenny"): Please make sure you have the libc6-dev package before trying to compile from source.

openSUSE 11.0, 11.1

Under the platform support guidelines above, and given that openSUSE releases have a lifetime of 2 years, Madagascar should theoretically attempt to support openSUSE 10.3 until 2009-10-31, openSUSE 11.0 until 2010-06-30, and openSUSE 11.1 until 2010-12-31. In practice, due to limited resources, installation has only been verified on openSUSE 11.0 and 11.1.

The development version of m8r has dependencies beyond the packages installed by the default openSUSE 11.0 DVD install:

• To download the development version, you need subversion
• To compile the package, you need scons and gcc
• To install the C++ API, you need gcc-c++
• To install the Octave API, you need octave
• To install sfbyte2jpg and sfjpg2byte you need libjpeg-devel
• To install the vplot graphics, you need xorg-x11-devel
• To install LaTeX for building papers and books, you need texlive-latex

Packages can be installed by running as root zypper install <package name>. The graphical front-end to Zypper integrated with YaST2 can of course be used as well (Geeko button... Applications... System... Configuration... Install Software)

Mac OS X

First of all, a Mac OS X precompiled binary package of the latest Madagascar stable release is available for download from SourceForge. If you want to install a development version of Madagascar, the following might help.

1. C compiler for Mac OS X. One can download the precompiled binary package of Xcode tools, including the gcc compiler, from Apple. Another way is to use Fink, a tool that brings the full world of Unix Open Source software to Mac OS X.
2. Subversion client for Mac OS X. There are two methods to install Subversion in Mac OS X: you can use Fink to update Subversion client package or the precompiled binary. Some useful information can be found on the Wikihow website and Collab. You can use Subversion to download the development version of the Madagascar source code. Next, follow Installation instructions to install.
3. SEGTeX, a LaTeX package for geophysical publications. To use SEGTeX, you may need TeX Live. Fink provides a easy way to install it with the command fink install texlive.

MS Windows

Due to its size, this topic has been assigned its own Wiki page.

Multi-user installs

Some organizations may find it desirable to deny write access of some users to all RSFSRC/RSFROOT except their own user directory. Fortunately, this can be easily done by placing the restricted user dirs outside RSFSRC/RSFROOT, i.e. in their home dirs, say /home/joe/rsfsrc. In order to move a user's directory out of RSFSRC, you must:

• "tell" the SConstruct in the user's dir where to find RSFSRC so that when the user builds in his directory, it can import configure.py and config.py You do that by setting the environment variable RSFSRC to the absolute path of the Madagascar source root, and by making sure that lines 2 and 3 in the users' SConstruct files are

<python> srcroot = os.environ.get('RSFSRC', '../..') sys.path.append(srcroot) </python> and then replace ../.. throughout the SConstruct using os.path.join and the srcroot variable.

• "tell" the build scripts about the user's dir, so that it is included in the builds launched from RSFSRC. You do that with a symbolic link:

<bash> ln -s /home/joe/rsfsrc $RSFSRC/user/joe </bash> When the link exists, those of Joe's programs that are mentioned in the "prog" string in SConstruct get included in the distribution, complete with self-doc. If Joe is just learning how to code and his stuff breaks the build, just remove the symbolic link. Even if build+installs are done after the link is removed, his stable programs and self-doc will continue to remain installed system-wide as long as the admin does not type scons -c install (not likely).

• point the user's RSFDOC environment variable to a location where the user has write access
• edit the users' SConstruct so that it uses the RSF library and headers already installed in $RSFROOT/lib and $RSFROOT/include , instead of building again the whole librsf with user-specific flags in RSFSRC/filt/lib/. To do that, replace in the user's SConstruct the env.Prepend statement with

<python> rsfroot = os.environ.get('RSFROOT','/usr/local/rsf')

env.Prepend(CPPPATH=[os.path.join(rsfroot,'include')],

           LIBPATH=[os.path.join(rsfroot,'lib')],
           LIBS=['rsf'])

</python>

• If the link from RSFSRC to Joe's directory was not made, add Joe's directory to his own path so that he can execute his own binaries.

To understand how $DATAPATH disk space issues may become an issue in a multi-user environment, refer to the Disk Space subsection at the beginning of this document.

Capturing error and warning messages

The messages during configuration are few and their importance quite high, so they should be watched "in person". A complete log of the configuration process is recorded in RSFSRC/configure.log

Console messages generated during the build step can be captured to a log file as follows: <bash> nice +10 nohup /usr/bin/time -p scons >& log_build.asc & </bash> The log file can be of course named otherwise than log_build.asc. The file can be later grepped for error and warnings with commands such as: <bash> grep -c error log_build.asc grep error log_build.asc | awk '/error.c/ {next}; /error.h/ {next}; /error.o/ {next}; {print}' grep -c warning log_build.asc grep warning log_build.asc | awk '/imaginary constants are a GCC extension/ {next}; {print}' </bash>

Advanced troubleshooting

• If you removed one of your programs or changed its name, and scons install fails with "Source oldprogname not found, needed by target install", and you cleaned everything there was to clean but still get this message, remove RSFSRC/.sconsign*
• If during scons install you get a DBAccessError : (13, 'Permission denied') in some reproducible papers, check permissions in your $DATAPATH directory. This is where SCons places database ".sconsign" files for its dependencies (according to the rules in rsfproj and rsftex).

Further support

Subscribe to the rsf-user mailing list.