Project

General

Profile

Install » History » Version 180

Dobbs, Adam, 22 December 2016 17:30

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