Project

General

Profile

Install » History » Version 191

Dobbs, Adam, 16 May 2017 16:02

1 1 Tunnell, Christopher
h1. Introduction
2 188 Dobbs, Adam
3
{{>toc}}
4 1 Tunnell, Christopher
5 105 Tunnell, Christopher
This page will take you through getting the prerequisites of installing MAUS and ensuring that it's working.  
6 1 Tunnell, Christopher
7 105 Tunnell, Christopher
If you have issue, please file a new support ticket by clicking "new issue" above.  Below are some common known problems:
8
9 144 Rogers, Chris
* Do not have whitespace in your path. Various third_party packages will break.  This is beyond the scope of MAUS.  See issue #306.
10 35 Tunnell, Christopher
11 107 Rogers, Chris
h1. Supported Distributions
12
13 110 Rogers, Chris
We support recent versions of
14 108 Rogers, Chris
* Scientific Linux
15
* CENT OS
16
17
Other Linux distributions are supported on a "best effort" basis.
18 107 Rogers, Chris
19 1 Tunnell, Christopher
h1. Prerequisites
20 21 Tunnell, Christopher
21 105 Tunnell, Christopher
_Most installation problems are a result of people not reading this section_
22 1 Tunnell, Christopher
23 105 Tunnell, Christopher
You will need a few GBs of free space on your harddrive for Geant4 and ROOT (which will be installed along with MAUS).
24
25 145 George, Melissa
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.
26
27 90 Tunnell, Christopher
h2. Scientific Linux/Redhat/Fedora/Centos
28 1 Tunnell, Christopher
29 158 Rogers, Chris
Remove Canopy if you have it installed. It causes conflicts with the default freetype (Ref. #1291).
30
31 23 Tunnell, Christopher
To install the tools required to build software on Scientific Linux, you must run the following commands:
32 1 Tunnell, Christopher
33 23 Tunnell, Christopher
<pre>
34
sudo yum groupinstall "Development Tools"
35
sudo yum groupinstall "Development Libraries"
36 168 Mohayai, Tanaz Angelina
sudo yum install wget libX11-devel libXft-devel libXext-devel libXpm-devel libX11-devel libpng-devel tcl-devel tk-devel sqlite-devel
37 161 Rajaram, Durga
sudo yum install cmake
38 23 Tunnell, Christopher
</pre>
39 1 Tunnell, Christopher
40 62 Tunnell, Christopher
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.
41 51 Tunnell, Christopher
42 161 Rajaram, Durga
> *Geant 4.9.6p02 requires cmake*. Please also run:
43
<pre> sudo yum install cmake</pre>
44
45 1 Tunnell, Christopher
> *Scientific Linux 4.8 only*. Please also run:
46 136 Rogers, Chris
> 
47
> <pre>sudo yum install xorg-x11-devel</pre>
48
49 162 Greis, Jan
When generating the documentation via doxygen, Graphviz is required to create graphs. To install, run
50
<pre> sudo yum install graphviz</pre>
51 136 Rogers, Chris
52 88 Tunnell, Christopher
h2. Debian or Ubuntu
53 23 Tunnell, Christopher
54
To install the tools required to build software on Debian-based systems, you must run the following commands:
55
56
<pre>
57 187 Dobbs, Adam
sudo apt-get install build-essential xorg-dev automake autoconf libtool scons zlibc libssl-dev libblas-dev liblapack-dev libpng-dev libsqlite3-dev bison libXpm-devel libXft-dev
58 1 Tunnell, Christopher
</pre>
59
60
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.
61 137 Rogers, Chris
62 161 Rajaram, Durga
> *Geant 4.9.6p02 requires cmake*. Please also run:
63 137 Rogers, Chris
> 
64 166 Snopok, Pavel
> <pre>sudo apt-get install cmake</pre>
65 47 Tunnell, Christopher
66 162 Greis, Jan
When generating the documentation via doxygen, Graphviz is required to create graphs. To install, run
67
<pre> sudo apt-get install graphviz</pre>
68
69 167 Rajaram, Durga
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
70
("ROOTTalk":http://root.cern.ch/phpBB3/viewtopic.php?f=3&t=17419)
71
To get around this, as superuser, do
72
<pre>
73
ln -s /usr/include/freetype2 /usr/include/freetype
74
</pre>
75
76 88 Tunnell, Christopher
h2. OpenSUSE
77 46 Tunnell, Christopher
78
To install the required tools, you must run the following command:
79 1 Tunnell, Christopher
80 46 Tunnell, Christopher
<pre>
81
sudo zypper install -t pattern devel_C_C++
82
</pre>
83 155 Rajaram, Durga
84
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.
85 1 Tunnell, Christopher
86 162 Greis, Jan
When generating the documentation via doxygen, Graphviz is required to create graphs.
87
88 155 Rajaram, Durga
h2. Other distribution
89 88 Tunnell, Christopher
90 24 Tunnell, Christopher
Please try using "google":http://www.google.com 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).
91 25 Tunnell, Christopher
92 24 Tunnell, Christopher
h1. Getting the code
93 87 Tunnell, Christopher
94 178 Dobbs, Adam
There are a number of options for obtaining MAUS:
95 25 Tunnell, Christopher
96 122 Rogers, Chris
h2. Using a packaged tarball
97 25 Tunnell, Christopher
98 172 Dobbs, Adam
Choose a version from the  "release page":http://heplnv152.pp.rl.ac.uk/maus/ 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
99 25 Tunnell, Christopher
<pre>
100 176 Dobbs, Adam
md5sum -c MAUS-vX.X.X.tar.gz.md5
101 1 Tunnell, Christopher
</pre>
102
103 176 Dobbs, Adam
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
104 128 Rogers, Chris
<pre>
105 176 Dobbs, Adam
tar xvfz MAUS-vX.X.X.tar.gz
106 128 Rogers, Chris
</pre>
107
You should now have a directory called 'maus'.
108 1 Tunnell, Christopher
109 182 Dobbs, Adam
h2. Bazaar and Launchpad (recommended for developers)
110 1 Tunnell, Christopher
111 180 Dobbs, Adam
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 [[Bzr_usage|here]]. The code is hosted on "launchpad":http://launchpad.net (also maintained by Canonical) under the "MAUS project":https://code.launchpad.net/maus.
112 25 Tunnell, Christopher
113 181 Dobbs, Adam
In order to obtain the code, "branch":http://en.wikipedia.org/wiki/Branching_%28software%29 the remote repository from launchpad using the following commands:
114 72 Tunnell, Christopher
115 1 Tunnell, Christopher
<pre>
116 181 Dobbs, Adam
mkdir MAUS
117
bzr init-repo MAUS
118
cd MAUS
119 1 Tunnell, Christopher
bzr branch lp:maus
120
</pre>
121
122 181 Dobbs, Adam
This will branch a copy of the release branch. To get a copy of the development trunk, use the following command:
123 1 Tunnell, Christopher
<pre>
124
bzr branch lp:maus/merge
125
</pre>
126
127
and you should now have a directory called 'maus' (or merge).  If you get a 'command not found', you must [[InstallingBzr|install bazaar]].  If you run into connectivity issues, you can check the bazaar server status "here":http://identi.ca/launchpadstatus.
128
129 185 Dobbs, Adam
*If you want to publish results based on MAUS, please use a release version of the code*.
130
131 182 Dobbs, Adam
h2. Git and GitHub (beta support)
132 181 Dobbs, Adam
133 183 Dobbs, Adam
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":https://github.com/mice-software/maus.
134 181 Dobbs, Adam
135
To obtain the code use the following steps:
136 177 Dobbs, Adam
137
* Optional: set up an account on github and add an ssh key
138
* Clone the MAUS repository using:
139
<pre>
140
git clone git@github.com:mice-software/maus.git
141
</pre>
142
* Move into the @maus@ directory and check the branches present with:
143
<pre>
144
git branch -av
145
</pre>
146
The following branches should be present:
147
** @master@ (the release branch)
148
** @merge@ (the development branch)
149
** @release-candidate@ (used by the release manager)
150 25 Tunnell, Christopher
151 184 Dobbs, Adam
* Checkout the branch you want using e.g. for the release:
152
<pre>
153
git checkout master
154
</pre>
155
156 87 Tunnell, Christopher
*If you want to publish results based on MAUS, please use a release version of the code*.
157 1 Tunnell, Christopher
158 31 Tunnell, Christopher
h1. Dependencies and building MAUS
159
160 1 Tunnell, Christopher
MAUS will try to help you by installing all of its dependencies for you.  
161 31 Tunnell, Christopher
162 146 Rogers, Chris
* 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.
163
* If running remotely, you may need to forward X11 connections (use ssh -X or ssh -Y)
164 97 Dobbs, Adam
165 175 Dobbs, Adam
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!*):
166 31 Tunnell, Christopher
167 1 Tunnell, Christopher
<pre>
168 129 Rogers, Chris
cd maus
169 102 Tunnell, Christopher
./install_build_test.bash
170 31 Tunnell, Christopher
</pre>
171 1 Tunnell, Christopher
172 172 Dobbs, Adam
Various arguments may be appended to modify the build procedure:
173
174 173 Dobbs, Adam
* Build with N threads:
175
<pre> -j N </pre>
176
177
* Use an existing MAUS installation for the third party libraries (drastically cuts the build time):
178
<pre> -t /path/to/other/maus </pre>
179
180
* Make the build verbose:
181
<pre> -v 1 </pre>
182
183
* Use your system gcc compiler (must support C++11, anything at version 4.8 or above should do):
184 174 Dobbs, Adam
<pre> --use-system-gcc true </pre>
185 172 Dobbs, Adam
186 169 Rogers, Chris
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:
187 34 Tunnell, Christopher
188 91 Rogers, Chris
<pre>
189 34 Tunnell, Christopher
Ran 79 tests in 251.375s
190 1 Tunnell, Christopher
191 112 Rogers, Chris
OK (SKIP=20)
192 111 Rogers, Chris
</pre>
193 91 Rogers, Chris
194 112 Rogers, Chris
Sometimes the test script may skip some tests because a certain library was not available. A test failure looks like
195 91 Rogers, Chris
196
<pre>
197
Ran 79 tests in 251.375s
198
199 34 Tunnell, Christopher
FAILED (errors=1, failures=1)
200 86 Tunnell, Christopher
</pre>
201 34 Tunnell, Christopher
202 114 Dobbs, Adam
If you run into issues, please send the output of:
203
204
<pre>
205
bash run_tests.bash
206
</pre>
207
208 120 Blot, Summer
to us through an issue by clicking 'New Issue' above.
209 114 Dobbs, Adam
210 84 Rogers, Chris
You are now ready to run MAUS!
211
212
h3. Troubleshooting
213
214 151 Rogers, Chris
If you aren't sure, a sample @install.log@ can be found "here":http://micewww.pp.rl.ac.uk/maus/MAUS_latest_version/install.log
215 1 Tunnell, Christopher
216 151 Rogers, Chris
* *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.
217 96 Rogers, Chris
* *MAUS does not import* - are you using a symbolic link?  See #770
218 1 Tunnell, Christopher
* *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
219 151 Rogers, Chris
* *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 <pre>bash ${MAUS_ROOT_DIR}/third_party/build_all.bash</pre> Better to just follow the install instructions above.
220 156 Rogers, Chris
* *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.
221 118 Rogers, Chris
222
h1. Other useful libraries/applications
223
224
MAUS doesn't require these libraries to build or run, but they may provide useful functionality for documentation, installation, etc
225
226 148 Rogers, Chris
h2. Rebuilding with Geant4.9.5
227
228
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:
229
230
<pre>
231
bash third_party/install_build_test_geant4.9.5.p01.bash
232
source env.sh
233
source env_geant4.9.5.p01.sh
234
</pre>
235
236
Note this is an experimental feature - however it is regularly tested against a scientific linux build "here":http://test.mice.rl.ac.uk/view/Trunk/job/MAUS_geant4.9.5.p01/
237
238 119 Rogers, Chris
h2. Documentation
239
240
To build the documentation, you will need
241
242 124 Rogers, Chris
* *doxygen* automatic code documentation tool "website":www.doxygen.org/
243
* *latex* typesetting tool "website":www.latex-project.org/
244
* *latex2html* for making html documents "website":http://www.latex2html.org/
245 123 Rogers, Chris
* *graphviz* (dot) for making class layouts, etc "website":http://www.graphviz.org/ "documentation":http://www.graphviz.org/Documentation/dotguide.pdf 
246 119 Rogers, Chris
247 149 Rogers, Chris
h2. Visualisation
248
249
We use @vrml@ as our default visualisation format. There are a number of viewers that may or may not work for viewing VRML files.
250
251
* Scientific Linux: If you have a VRML viewer that works in SL, please email the developers.
252
* Ubuntu: Try "paraview":http://www.paraview.org/
253
<pre>
254
sudo apt-get install paraview
255
/usr/bin/paraview g4_00.wrl
256
click on eye icon in left menu bar
257
</pre>
258 163 Rogers, Chris
or blender
259
<pre>
260
sudo apt-get install blender
261
Click on file > import to import a wrl file
262
</pre>
263 1 Tunnell, Christopher
* Windows: Try "Instant Player":http://www.instantreality.org/downloads/ or "FreeWRL":http://freewrl.sourceforge.net/
264 150 Rogers, Chris
* Other: There are a few options listed in #1250
265 149 Rogers, Chris
266 157 Rogers, Chris
h2. Online use (and testing)
267
268
In order to run the online tests, you will need some extra libraries - please see instructions [[MLCR_Deployment|here]]