Project

General

Profile

Actions
History

Introduction

This page will take you through getting the prerequisites of installing MAUS and ensuring that it's working.

If you have issue, please file a new support ticket by clicking "new issue" above. Below are some common known problems:

  • Do not have whitespace in your path. Various third_party packages will break. This is beyond the scope of MAUS. See issue #306.

Supported Distributions

We support recent versions of
  • Scientific Linux
  • CENT OS

Other Linux distributions are supported on a "best effort" basis.

Prerequisites

Most installation problems are a result of people not reading this section

You will need a few GBs of free space on your hard drive for Geant4 and ROOT (which will be installed along with MAUS).

You will also need a number of prerequisite tools for the software to build and run correctly, such as X11. To be sure that your system has the correct setup, follow the instructions that relate to your system in the following sections.

Old version of Bazaar needs to be updated or patched (e.g. 2.1.1). A working one is 2.7.0, so please check this before running the install script.

Scientific Linux/Redhat/Fedora/Centos

Remove Canopy if you have it installed. It causes conflicts with the default freetype (Ref. #1291).

To install the tools required to build software on Scientific Linux, you must run the following commands:

sudo yum groupinstall "Development Tools" 
sudo yum groupinstall "Development Libraries" 
sudo yum install wget libX11-devel libXft-devel libXext-devel libXpm-devel libX11-devel libpng-devel tcl-devel tk-devel sqlite-devel openssl-devel cmake patch bzr bison gcc-c++

where the sudo command means that this is run as the root superuser. If you do not have this access, you must ask your system manager.

NB: If you are using a modern version of Fedora you may need to replace "yum" with "dnf"

Geant 4.9.6p02 requires cmake. Please also run:

 sudo yum install cmake

Scientific Linux 4.8 only. Please also run:

sudo yum install xorg-x11-devel

When generating the documentation via doxygen, Graphviz is required to create graphs. To install, run

 sudo yum install graphviz

Debian or Ubuntu

To install the tools required to build software on Debian-based systems, you must run the following commands:

sudo apt-get install build-essential xorg-dev automake autoconf libtool scons zlibc libssl-dev libblas-dev liblapack-dev libpng-dev libsqlite3-dev bison libbison-dev libxpm-dev libxml2-dev libjsoncpp-dev bzr byacc unzip

where the sudo command means that this is run as the root superuser. If you do not have this access, you must ask your system manager.

Geant 4.9.6p02 requires cmake. Please also run:

sudo apt-get install cmake

When generating the documentation via doxygen, Graphviz is required to create graphs. To install, run

 sudo apt-get install graphviz

On Ubuntu, the ROOT build could fail because ROOT looks for freetype in /usr/include/freetype, whereas the system has them in /usr/include/freetype2
(ROOTTalk)
To get around this, as superuser, do

ln -s /usr/include/freetype2 /usr/include/freetype

OpenSUSE

To install the required tools, you must run the following command:

sudo zypper install -t pattern devel_C_C++

where the sudo command means that this is run as the root superuser. If you do not have this access, you must ask your system manager.

When generating the documentation via doxygen, Graphviz is required to create graphs.

Other distribution

Please try using google to find out how to do it for your specific architecture. If you succeed, then please post those instruction here and continue with these instructions. If you fail, please email the user mailing list ().

Getting the code

There are a number of options for obtaining MAUS:

Using a packaged tarball

Choose a version from the release page and click on the Source Code tarball link (latest version at the top of the page). You may wish to check that the download was okay, for instance by doing

md5sum -c MAUS-vX.X.X.tar.gz.md5

where MAUS-vX.X.X.tar.gz.md5 can be found either by following the md5 link from the download page and X.X.X is the MAUS version number. Then extract the code by doing

tar xvfz MAUS-vX.X.X.tar.gz

You should now have a directory called 'maus'.

Grid repository

Release tarballs will also be made available on the Grid: http://gfe02.grid.hep.ph.ic.ac.uk:8301/Construction/Software/MAUS/

Bazaar and Launchpad (recommended for developers)

Bazaar is a distributed version control system (DVCS) maintained by Canonical. It is used for version control and distribution of MAUS for developers. There is a MAUS-specific tutorial for bzr here. The code is hosted on launchpad (also maintained by Canonical) under the MAUS project.

In order to obtain the code, branch the remote repository from launchpad using the following commands:

mkdir MAUS
bzr init-repo MAUS
cd MAUS
bzr branch lp:maus

This will branch a copy of the release branch. To get a copy of the development trunk, use the following command:

bzr branch lp:maus/merge

and you should now have a directory called 'maus' (or merge). If you get a 'command not found', you must install bazaar. If you run into connectivity issues, you can check the bazaar server status here.

If you want to publish results based on MAUS, please use a release version of the code.

Git and GitHub (beta support)

Git is another, very popular, DCVS. MAUS provides beta level support for git. In particular at the moment code updates for the trunk cannot be accepted from git, only via launchpad and bazaar (if you would rather use git, please email the head of MAUS to show your support). The remote MAUS git repository is hosted on github.

To obtain the code use the following steps:

  • Optional: set up an account on github and add an ssh key
  • Clone the MAUS repository using:
    git clone git@github.com:mice-software/maus.git
  • Move into the maus directory and check the branches present with:
    git branch -av

    The following branches should be present:
    • master (the release branch)
    • merge (the development branch)
    • release-candidate (used by the release manager)
  • Checkout the branch you want using e.g. for the release:
    git checkout master

If you want to publish results based on MAUS, please use a release version of the code.

Dependencies and building MAUS

MAUS will try to help you by installing all of its dependencies for you.

  • Be careful about using symbolic links to move to this directory prior to installation, as this may confuse the build system. Always try to follow an absolute path instead.
  • If running remotely, you may need to forward X11 connections (use ssh -X or ssh -Y)

You can now run the following command to build all your dependencies, build MAUS, and run the unit and style tests for you (this takes about 2 hours for most machines, and 4 hours for VMs!):

cd maus
./install_build_test.bash

Various arguments may be appended to modify the build procedure:

  • Build with N threads:
     -j N
  • Use an existing MAUS installation for the third party libraries (drastically cuts the build time):
     -t /path/to/other/maus
  • Make the build verbose:
     -v 1
  • Use your system gcc compiler (must support C++11, anything at version 4.8 or above should do):
     --use-system-gcc true

The build output is automatically stored in a log file like ./install.log. Some of the tests check that errors are handled correctly, so we expect some error messages. The tests should end with a line like:

Ran 79 tests in 251.375s

OK (SKIP=20)

Sometimes the test script may skip some tests because a certain library was not available. A test failure looks like

Ran 79 tests in 251.375s

FAILED (errors=1, failures=1)

If you run into issues, please send the output of:

bash run_tests.bash

to us through an issue by clicking 'New Issue' above.

You are now ready to run MAUS!

Troubleshooting

If you aren't sure, a sample install.log can be found here

  • I get errors in the test output: this is normal - if the tests finish with a line like OK, then the tests passed. If the tests finish with a line like FAILED (errors=1, failures=1) (or worse a segmentation fault), then the tests failed. Some of the tests are actually checking that errors are produced on bad input. Sample output for the installer are available.
  • MAUS does not import - are you using a symbolic link? See #770
  • I get a message like FATAL: Failed to install python module matplotlib and then some more error messages - you may need to forward X11 connections to install matplotlib. See #1246
  • I get an error about Python versions when I run ./configure: this is normal - you need to install third party libraries (including python 2.7) by doing 
    bash ${MAUS_ROOT_DIR}/third_party/build_all.bash
    Better to just follow the install instructions above.
  • I get a failure in the ROOT build - ROOT fails to find freetype.h - if you have canopy installed, this makes an incompatible version of freetype. Uninstall canopy.

Other useful libraries/applications

MAUS doesn't require these libraries to build or run, but they may provide useful functionality for documentation, installation, etc

Rebuilding with Geant4.9.5

MAUS comes prepacked with a script to build against geant4.9.5.p01. In order to build against geant4.9.5, please use the following script:

bash third_party/install_build_test_geant4.9.5.p01.bash
source env.sh
source env_geant4.9.5.p01.sh

Note this is an experimental feature - however it is regularly tested against a scientific linux build here

Documentation

To build the documentation, you will need

Visualisation

We use vrml as our default visualisation format. There are a number of viewers that may or may not work for viewing VRML files.

  • Scientific Linux: If you have a VRML viewer that works in SL, please email the developers.
  • Ubuntu: Try paraview
    sudo apt-get install paraview
/usr/bin/paraview g4_00.wrl
click on eye icon in left menu bar

    or blender
    sudo apt-get install blender
Click on file > import to import a wrl file
  • Windows: Try Instant Player or FreeWRL
  • Other: There are a few options listed in #1250

Online use (and testing)

In order to run the online tests, you will need some extra libraries - please see instructions here

Updated by Franchini, Paolo about 4 years ago ยท 204 revisions