Project

General

Profile

Install » History » Version 204

Franchini, Paolo, 26 July 2019 12:15

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