Madagascar has been installed and is periodically tested on
- Different Linux distributions (Fedora, RedHat, Ubuntu, etc.)
- MacOS X
- Windows under the Cygwin environment.
It was previously tested on
- SGI Irix
- Windows under Microsoft's Services for UNIX environment.
Precompiled binary packages
See the Madagascar download page for availability of binary packages.
Installation from source
Specific instructions are provided for Windows users.
For other platform-specific instructions, please consult the Advanced Installation guide.
- C compiler. Any ANSI-compliant compiler such as GCC should work. GCC usually comes pre-installed on Linux machines.
- Python interpreter. Python is an interpretable programming language. It is used in Madagascar installation scripts and project management scripts. Python comes pre-installed on some platforms. Madagascar currently attempts to support Python versions 2.2 through 2.6. Versions before 2.2 are not common, but if you experience problems and you have an earlier version you should probably upgrade.
SCons is also required, but it is included with Madagascar and the configure scripts will attempt to install it for you if you don't have it already. Alternatively you can get it through yum with "yum install scons" in a terminal window. For more information see the Advanced Installation guide.
Each API option has its own prerequisites.
Prerequisites for optional add-on functionality are platform-specific.
Building under cygwin on Windows requires several preparatory steps.
- Configuration: Open a terminal window and change to the top source directory (sometimes called "RSFSRC"). Next, you'll have to make some changes to your .bashrc file, so open it in you're favorite editor, e.g. <bash> vim ~/.bashrc </bash> or <bash> gedit ~/.bashrc </bash> Now simply append these lines to the bottom of the .bashrc file:
<bash> export DATAPATH=$HOME/scratch/ export EDITOR=nedit export OMP_NUM_THREADS=2 export LATEX2HTML=$HOME/texmf/latex2html export RSFROOT=~/madagascar
- source $HOME/Desktop/RSFSRC/env.sh
</bash>Notice that the "source" line of this file is commented out for now. After this directory is created during the install, we'll come back here to fix this. Another tweak you make elect to implement is changing the OMP_NUM_THREADS line to a number greater than 2 but less than or equal to the number of cores on your machine (2 is the max for a dual-core processor). Incrementing this environment variable will have benefits when running parallelized code. I also assume that you want Madagascar installed to a directory called "madagascar". Feel free to adjust the second to last line accordingly. To have the changes you just made to the file take effect, type
into your terminal window. Now you're ready to run <bash>./configure --prefix=/directory/where/you/want/madagascar/installed</bash> You can examine the config.py file that this command generates. Additional options are available. You can obtain a full list of customizable variables by running scons -h. For example, to install C++ and Fortran-90 API bindings in addition to the basic package, run <bash>./configure API=c++,f90 --prefix=/directory/where/you/want/madagascar/installed</bash> Oftentimes after running "./configure ..." you'll see a list of things that your system may not have installed (the items that have "no" next to them). Usually they are optional, but for the best experience with Madagascar, it is strongly recommended that you install these packages using a package manager such as yum. Example syntax is used here. Just change the name from "python-devel" to whatever you might be missing.<bash>yum install python-devel</bash>After installing this dependency, rerun the .configure command above and repeat this step until you have all of the desired packages installed.
- Building and installing the package: Run <bash>make install</bash> If you need "root" privileges for installing under $RSFROOT, you may need to run <bash>make; su; make install</bash> or <bash>make; sudo make install</bash> If make does not exist on your system, an alternative procedure can be found in the Troubleshooting section.
- User setup: If your shell is sh or bash, add to your $HOME/.bashrc and $HOME/.bash_profile files the line <bash>source $RSFROOT/share/madagascar/etc/env.sh</bash> where RSFROOT is the install directory you specified in the --prefix option to ./configure. If your shell is (t)csh, add to your $HOME/.cshrc file the line <bash>source $RSFROOT/share/madagascar/etc/env.csh</bash> Please be aware that, on some systems, the default value for DATAPATH set in the script above may get automatically cleaned at some intervals, so if you want to keep your data binaries for a long time, set DATAPATH in your resource file to another location where you have write access and that allows large files. Remember that the value of DATAPATH should have a slash at the end.
To clean all intermediate files and all installed files, run
scons -c install
in the source code directory.
Alternative build/install procedure
- Set the environment variables: If your shell is sh or bash, type (or uncomment) <bash>source env.sh</bash> Else, if your shell is csh or tcsh, type <bash>source env.csh</bash>
- Build: Type scons
- Install: Run scons install . If you need "root" privileges for installing under $RSFROOT, you may need to run <bash>su; scons install </bash> or <bash>sudo scons install</bash>
Note that scons does not inherit your environmental variables including PATH. If the configuration part ends with the message like
checking if cc works ... failed
the problem may be that your compiler is in unusual place. Try
./configure CC=`which cc`
On Windows under SFU, use the gcc compiler
For more information, please consult the Advanced Installation guide.
Testing and quick start
Here are a few simple tests and and a brief introduction to Madagascar:
Typing any Madagascar command in a terminal window without parameters should generate a brief documentation on that command. Try one of the following:
sfin sfattr sfspike sfbandpass sfwiggle
If you get an error like "Command not found", you may not have your $PATH environment variable set correctly, or you may need to issue the rehash command.
Now try making a simple Madagascar data file:
sfspike n1=1000 k1=300 > spike.rsf
This command generates a one dimensional list of 1000 numbers, all zero except for a spike equal to one at position 300. If this generates an error like
Cannot write to data file /path/spike.rsf@: Bad file descriptor
you may need to create the directory pointed to by your $DATAPATH environment variable.
The file spike.rsf is a text header. The actual data are stored in the binary file pointed to by the in= parameter in the header. You can look at the header file directly with more, or better, examine the file properties with
You can learn more about the contents of spike.rsf with
sfattr < spike.rsf
The following command applies a bandpass filter to spike.rsf and puts the result in filter.rsf:
sfbandpass fhi=2 phase=y < spike.rsf > filter.rsf
The following command makes a graphics file from filter.rsf:
sfwiggle clip=0.02 title="Welcome to Madagascar" < filter.rsf > filter.vpl
If you have an X11 display program running, and your $DISPLAY environment variable is set correctly, you can display the graphics file with:
sfpen < filter.vpl
You can pipe Madagascar commands together and do the whole thing at once like this:
sfspike n1=1000 k1=300 | sfbandpass fhi=2 phase=y | \ sfwiggle clip=0.02 title="Welcome to Madagascar" | sfpen
If you have SCons installed, you can use it to automate Madagascar processing. Here is a simple SConstruct file to make filter.rsf and filter.vpl:
- Setting up
from rsf.proj import *
- Make filter.rsf
Flow('filter',None,'spike n1=1000 k1=300 | bandpass fhi=2 phase=y')
- Make filter.vpl
Result('filter','wiggle clip=0.02 title="Welcome to Madagascar"')
Put the file in an empty directory, give it the name SConstruct, cd to that directory, and issue the command:
The graphics file is now stored in the Fig subdirectory. You can view it manually with:
... or you can use:
When an SConstruct file makes more than one graphics file, the scons view command will display all of them in sequence.
Now edit the SConstruct file: change the title string on the Result line to "Hello World!", save the file, and rerun the scons command. You will see that scons has figured out that the file filter.rsf does not need to be rebuilt because nothing that affects it has changed. Only the file filter.vpl is rebuilt.