Installation of VM-MAD

Author:Riccardo Murri <riccardo.murri@gmail.com> Date:2010-10-06 Revision:$Revision$

Installation

These instructions show how to install VM-MAD from the source repository into a separate python environment (called virtualenv). Installation into a virtualenv has two distinct advantages:

• All code is confined in a single directory, and can thus be easily replaced/removed.
• Better dependency handling: additional Python packages that VM-MAD depends upon can be installed even if they conflict with system-level packages.

0. Install software prerequisites:

   • On Debian/Ubuntu, install packages: subversion, python-dev, python-profiler and the C/C++ compiler:

     apt-get install subversion python-dev python-profiler gcc g++

   • On CentOS5, install packages subversion and python-devel and the C/C++ compiler:

     yum install subversion python-devel gcc gcc-c++

   • On other Linux distributions, you will need to install:

     • the svn command (from the SubVersion VCS)
     • Python development headers and libraries (for installing extension libraries written in C/C++)
     • the Python package pstats (it’s part of the Python standard library, but sometimes it needs separate installation)
     • a C/C++ compiler (this is usually installed by default).

1. Choose a directory where the VM-MAD software will be installed; any directory that’s writable by your Linux account will be ok.

   If you are installing system-wide as root, we suggest you install VM-MAD into /opt/vm-mad.

   If you are installing as a normal user, we suggest you install VM-MAD into $HOME/vm-mad.

2. If it’s not already installed, get the virtualenv Python package and install it:

     wget http://pypi.python.org/packages/source/v/virtualenv/virtualenv-1.5.1.tar.gz
     tar -xzf virtualenv-1.5.1.tar.gz && rm virtualenv-1.5.1.tar.gz
     cd virtualenv-1.5.1/
   
   If you are installing as `root`, the following command is all you
   need:
   
     python setup.py install
   
   If instead you are installing as a normal, unprivileged user,
   things get more complicated::
   
     export PYTHONPATH=$HOME/lib64/python:$HOME/lib/python:$PYTHONPATH
     export PATH=$PATH:$HOME/bin
     mkdir -p $HOME/lib/python
     python setup.py install --home $HOME
   
   (You will also need to add the two `export` lines above to the
   `$HOME/.bashrc` file -if using the `bash` shell- or to the
   `$HOME/.cshrc` file -if using the `tcsh` shell.)
   
   In any case, once `virtualenv`_ has been installed, you can exit
   its directory and remove it::
   
     cd ..
     rm -rf virtualenv-1.5.1

3. Create a virtualenv to host the vm-mad installation at the directory you chose in Step 1.:

   virtualenv $HOME/vm-mad # use '/opt/vm-mad' if installing as root
   cd $HOME/vm-mad/
   source bin/activate

4. Check-out the vm-mad files in a src/ directory:

   svn co http://vm-mad.googlecode.com/svn/trunk src

5. Install the vm-mad in “develop” mode, so any modification pulled from subversion is immediately reflected in the running environment:

   cd src/
   env CC=gcc ./setup.py develop
   cd .. # back into the `vm-mad` directory

   This will place all the VM-MAD command into the vm-mad/bin/ directory.

Upgrade

These instructions show how to upgrade the VM-MAD scripts to the latest version found in the GC3 svn repository.

1. cd to the directory containing the VM-MAD virtualenv; assuming it’s named vm-mad as in the above installation instructions, you can issue the commands:

   cd $HOME/vm-mad # use '/opt/vm-mad' if root

2. Activate the virtualenv

   source bin/activate

3. Upgrade the vm-mad source and run the setup.py script again:

   cd src
   svn up
   env CC=gcc ./setup.py develop

HTML Documentation

HTML documentation for the VMlib programming interface can be read online at:

http://vm-mad.googlecode.com/svn/trunk/doc/html/index.html

You can also generate a local copy from the sources:

cd $HOME/vm-mad # use '/opt/vm-mad' if root
cd src/docs
make html

Note that you need the Python package Sphinx <http://sphinx.pocoo.org> (at least versdion 1.0) in order to build the documentation locally.