Editing Advanced Installation (section)

=Environment variables=
Besides the variables defined in env.sh or env.csh (see the [[Installation|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.

For future documentation writers: the environment variables read by Madagascar that have not been documented below can be found by running the script <tt>$RSFSRC/admin/find_env_var.py</tt>. If the script does not exist or does not work, a summary of all environment variable calls can be obtained by going to $RSFSRC, temporarily moving the directory <tt>build/</tt> outside RSFSRC, and typing
<syntaxhighlight lang="bash">
grep environ.get *.py */*.py */*/*.py */*/*/*.py
grep getenv           */*.c  */*/*.c  */*/*/*.c
</syntaxhighlight>

==Used by the Madagascar core==

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="3" style="background:#ffdead;"|Variables introduced by Madagascar's non-graphic programs
|-
| '''Name''' || '''Default''' || Meaning
|-
| RSF_DATASERVER || <nowiki>ftp://egl.beg.utexas.edu/</nowiki> || Data server for benchmark datasets
|-
| RSFDOC || $RSFROOT/doc || Directory for the HTML self-doc
|-
| RSFFIGS || $RSFROOT/figs || Directory with figures for testing examples in $RSFSRC/book
|-
|-
| RSFALTFIGS || $RSFFIGS || Alternate directory with figures for testing examples not in $RSFSRC/book
|-
| 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
|}


{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="3" style="background:#ffdead;"|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 || $RSFROOT/include || 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.
|}


{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="2" style="background:#ffdead;"| 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
|}

==Used by the Madagascar build process and parallelization utilities==
Type <tt>scons -h</tt> 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:
* <tt>RSF_THREADS</tt>: used by <tt>pscons</tt> to determine on how many threads to run on the local node, overriding the number of threads detected by Madagascar
* <tt>RSF_CLUSTER</tt>: used by <tt>pscons</tt> to determine on which cluster nodes to run, and on how many CPUs

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

Old-style API (1.0 and before): The path to the downloaded Mines JTK must be specified in the MINESJTK environment variable in order to install the Java API. For example:
<syntaxhighlight lang="bash">
export MINESJTK=/home/user/edu_mines_jtk.jar
</syntaxhighlight>

==RSFROOT for NFS-shared user home directories==
Heterogeneous networks with user home directories shared through [http://en.wikipedia.org/wiki/Network_File_System_(protocol) 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. [http://en.wikipedia.org/wiki/RHEL 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:
<syntaxhighlight lang="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
</syntaxhighlight>
Of course, the Madagascar administrator will have to download appropriate versions of Madagascar to each $RSFROOT, and compile them on the appropriate system.

If you have many kinds of systems to maintain, with multiple versions of Madagascar, and users have more than one shell, you may find it easy to outsource the complex logic to the easy-to-debug Python, i.e.:

<syntaxhighlight lang="bash">
export RSFROOT=`$M8R_SETUP/get_rsfroot.py`
export PYTHONPATH=`$M8R_SETUP/edit_pythonpath.py`
export PATH=`$M8R_SETUP/edit_path.py`
</syntaxhighlight>

and similarly for (t)csh. The Python scripts determine the operating system and its version, determine the machine name, and simply print to stdout the desired string.

==Eclipse + Pydev==
If you use [http://eclipse.org/ Eclipse] with [http://pydev.org/ Pydev], [http://pydev.org/manual_101_interpreter.html#id2 configure the interpreter] by adding <tt>$RSFROOT/lib</tt> to the <tt>PYTHONPATH</tt> for your chosen interpreter.