Introduction¶
- Table of contents
- Introduction
- Supported Distributions
- Prerequisites
- Getting the code
- Dependencies and building MAUS
- Other useful libraries/applications
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 (maus-user@jiscmail.ac.uk).
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
- doxygen automatic code documentation tool website
- latex typesetting tool website
- latex2html for making html documents website
- graphviz (dot) for making class layouts, etc website documentation
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 blendersudo 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