Small improvements to the installation instructions
[u/mrichter/AliRoot.git] / html / installation.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
2                "http://www.w3.org/TR/REC-html40/loose.dtd">
3 <HTML>
4 <HEAD>
5 <TITLE>Installation</TITLE>
6
7 <link rev="made" href="mailto:Federico.Carminati@cern.ch">
8 <link rel="stylesheet" href="http://www.w3.org/StyleSheets/Core/Swiss" type="text/css">
9 <STYLE type="text/css">
10
11 BODY    {       
12         background:     #FFFFFF;
13         }       
14
15 COL, COLGROUP, TABLE, TBODY, TD, TR     {       
16         color:  black;
17         text-decoration:        none;
18         border-color:   black;
19         border-style:   none;
20         background:     #FFFFFF;
21         }                       
22
23 TABLE.wide {
24         cellspacing: 100%;
25         background: #FF0000
26         }
27
28 </STYLE>
29 </HEAD>
30
31 <BODY>
32 <TABLE>
33 <TR>
34 <TD><img src="picts/MadHatter.gif" alt="ALICE Off-line Project Logo">
35 <TD><img src="picts/installation_name.gif" alt="Installation">
36 <TD><img src="picts/AliceLogo.gif" alt="ALICE Logo">
37 </TR>
38 </TABLE>
39
40 <H2><A NAME="#Content">Content</A></H2>
41 <UL>
42 <LI><A HREF="#Prequisites">Prerequisites</A>
43 <LI><A HREF="#Installation">Installation</A>
44 <LI><A HREF="#Code">Code development and user environment</A>
45 </UL>
46
47 <HR>
48
49 <h2><A HREF="#Content" NAME="Prerequisites">Prerequisites</A></h2>
50
51 <h3>Environment</h3>
52
53 <p> The code is actively maintained on Linux and HP (both CC and aCC
54 compilers). It also runs on Compaq OSF1 and SunOS. We welcome feedback from
55 the installation on other systems and we will be happy to consider 
56 modifications and corrections necessary to make the installation possible.
57
58 <p> The disk space required for a full installation of AliRoot is 200MB for
59 the system itself and 60MB for the ROOT system.
60
61 <h3>gmake</h3>
62
63 <p> The installation is performed via the <kbd>
64 <a href="http://www.gnu.ai.mit.edu/manual/make-3.77/make.html">
65 gmake</a></kbd> program. <kbd>gmake</kbd> is the 
66 <a href="http://www.gnu.ai.mit.edu">GNU</a> version of make, it is free and,
67 if missing on your machine, it can be loaded from the GNU Internet site 
68 <a href="ftp://ftp.gnu.ai.mit.edu/pub/gnu/make">
69 ftp://ftp.gnu.ai.mit.edu/pub/gnu/make</a>. <kbd>gmake</kbd> is compatible
70 with the standard UNIX <kbd>make</kbd> and on the CERN ion WGS
71 <kbd>make</kbd> is aliased to <kbd>gmake</kbd>. The only files you need for 
72 <kbd>gmake</kbd> are the executable <kbd>gmake</kbd>
73 and the script <kbd>autoconf</kbd>, therefore you can copy such files from
74 any site in a directory in your path.
75
76 <h3>ROOT</h3>
77
78 <p> <em>ROOT</em> is available for many platforms, therefore in most cases
79 no <em>ROOT</em> installation is required. To install ROOT on your machine,
80 connect to the <a href="http://root.cern.ch">web site</a> and follow the
81 link <em>downloads</em>. Usually you should get the latest release, unless
82 announced differently by the news of the Off-line Project.
83
84 <p> All you need to do is download the compressed tar file, that usually is
85 called <var>root_v...tar.gz</var>uncompress and untar it (we supposed you
86 downloaded the tar file in your <var>$HOME</var>):
87
88 <p><kbd>
89 $ gunzip root_v...tar.gz
90 <br>$ cd <i>directory</i> # name of the directory where you want ROOT to sit
91 <br>$ tar xvf ~/root_v...tar
92 </kbd>
93
94 <p> When tar ends, you will have the full root directory tree, with already
95 installed libraries for your platform. 
96
97 <p> The following shell variables should be defined in the login scripts:
98
99 <p><table align=centre borders=no>
100 <tr><th align=left>variable</th><th align=left>value</th></tr>
101 <tr><td width=50%>ROOTSYS              </td><td> <i>directory</i>/root
102 <tr><td colspan=2><i><center>on all systems but HP-UX</center></i></td></tr>
103 <tr><td>LD_LIBRARY_PATH</td>
104 <td>$LD_LIBRARY_PATH\:$ROOTSYS/lib</td></tr>
105 <tr><td colspan=2><i><center>on HP-UX</center></i></td></tr>
106 <tr><td>SHLIB_PATH</td>
107 <td>$SHLIB_PATH\:$ROOTSYS/lib</td></tr>
108 <tr><td>PATH</td>
109 <td> $PATH\:$ROOTSYS/bin </td></tr>
110 </table>
111
112
113 <h2><A HREF="#Content" NAME="Installation">Installation</A></h2>
114
115 <ol> 
116 <p><li> Install <a href="http://root.cern.ch">ROOT</a> and define the
117 necessary variables correctly.
118
119 <p><li> Decide where the code will reside (from here on <i>directory</i>).
120
121 <p><li>Define the following global variables in the login script
122
123 <p><table align=centre borders=no>
124 <tr><th align=left>variable</th><th align=left>value</th></tr>
125 <tr><td width=30%>ALICE        </td><td> <i>directory</i>
126 <tr><td>ALICE_LEVEL             </td><td> pro </td></tr>
127 <tr><td>ALICE_ROOT              </td><td> $ALICE/$ALICE_LEVEL </td></tr>
128 <tr><td>ALICE_TARGET            </td><td> `uname` 
129 (i.e. result of the Unix <b>uname</b> command)</td></tr>
130 <tr><td colspan=2><i><center>on all systems but HP-UX</center></i></td></tr>
131 <tr><td>LD_LIBRARY_PATH</td>
132 <td>$ALICE_ROOT/lib/tgt_${ALICE_TARGET}\:$LD_LIBRARY_PATH</td></tr>
133 <tr><td colspan=2><i><center>on HP-UX</center></i></td></tr>
134 <tr><td>SHLIB_PATH</td>
135 <td>$ALICE_ROOT/lib/tgt_${ALICE_TARGET}\:$SHLIB_PATH</td></tr>
136 <tr><td>PATH</td>
137 <td> $PATH\:$ALICE_ROOT/bin/tgt_${ALICE_TARGET} </td></tr>
138 </table>
139
140 <p>At this point you should logout, login again and check that the symbols
141 are set correctly.
142
143 <p><li> Retrieve the AliRoot code. There are two ways to do this:
144
145 <ul> 
146 <p><li> <em>From a tar file</em>. This is the preferred way for those who
147 do not have an internet connection to the <em>cvs</em> server from the
148 machine where the code has to be installed. The <a
149 href="ftp://pcepaip01.cern.ch/pub">files</a> containing the latest release
150 should be brought on the target machine. Three files are offered:
151
152 <p><table align=center borders=no>
153 <tr><th align=left>File<th align=left>Content</tr>
154 <tr><td align=center colspan=2><em>Either</em></tr>
155 <tr><td>AliOffline<i>MM.mm-pp</i>.tar.gz
156 <td>Code and the data files of ALICE Off-line</tr>
157 <tr><td align=center colspan=2><em>Or</em></tr>
158 <tr><td>AliLibs<i>MM.mm-pp</i>.tar.gz
159 <td>Code and the data files of the auxiliary libraries</tr>
160 <tr><td>AliRoot<i>MM.mm-pp</i>.tar.gz
161 <td>All the code and the data files of the AliRoot system</tr>
162 </table>
163
164 <p> <i>MM.mm-pp</i> is the number of the latest <i>M</i>ajor and
165 <i>m</i>inor version and the <i>p</i>atch number. The file(s) have to be
166 unpacked into the $ALICE directory via the command:
167
168 <p><pre>$ gtar xvfz Ali[...].tar.gz</pre>
169
170
171 <p><li> <em>From cvs remote cvs server</em>. This method has the advantage
172 that new patches can be incrementally retrieved and installed via internet.
173 At the moment the problem is that the version of cvs currently installed at
174 CERN (1.09) does not support well binary files. Therefore some data files
175 will be missing with this download mechanism, and these will have to be
176 fetched <em>by hand</em>. The setup of the access to the remote cvs server
177 is described in the Code Development section. The
178 code is dowloaded via the command:
179
180 <p><pre>
181 $ cd $ALICE
182 $ cvsa co -r Release-3-02 -d pro AliRoot
183 </pre>
184
185 <p>Where the meaning of <kbd>cvsa</kbd> is explained in the 
186 <a href="../development.html">code development</a> section.
187
188 </ul>
189
190 <p><li>install the CERN library part
191
192 <p><pre>
193 $ cd $ALICE_ROOT
194 $ gmake cernlibs
195 </pre>
196
197 <p><li>Install the ALICE specific software
198
199 <p><pre>
200 $ cd $ALICE_ROOT
201 $ gmake
202 </pre>
203
204 <p><li>Copy the file $ALICE_ROOT/.rootrc to your home directory
205
206 <p><li>For users with c-like shells, update your search path:
207
208 <p>
209 <pre>
210 $ rehash
211 </pre>
212
213 <p>This usually has to be done only once, after having defined the new PATH.
214
215 <p><li>Change to your home directory and run the code
216
217 <p>
218 <pre>
219 $ cd
220 $ aliroot
221
222 <output from aliroot>
223
224 root [1] .x menu.C
225 </pre>
226 </ol>
227
228 <h2><A HREF="#Content" NAME="Code">Code development and user environment</A></h2>
229
230 <p>If the ALICE environment is set up correctly, the
231 <var>$ALICE_ROOT/lib/tgt_$ALICE_TARGET</var> directory is in the shared
232 libraries load path, and the <var>$ALICE_ROOT/bin/tgt_$ALICE_TARGET</var>
233 directory is in the PATH variable. This means that the command
234 <kbd>aliroot</kbd> will in fact correspond to the file
235 <var>$ALICE_ROOT/bin/tgt_$ALICE_TARGET/aliroot</var>.
236
237 <p>This is convenient for the normal user, but as soon as the user wants to
238 modify one or more directories, this arrangement becomes inefficient
239 because if a local copy of one of the shared libraries is remade, the
240 linker will always find the official unmodified one that sits in the above
241 directory before the local one in the load library path. Moreover, and
242 unless the full path is specified, the local version of the <b>aliroot</b>
243 executable will be ignored and the official version executed.
244
245 <p>Therefore in order to develop one or more packages locally
246 (let's say the TPC) and make modifications, the following steps should be
247 performed. We suppose here that the remote cvs server has been setup correctly
248 as explained in the <a href="../development.html">code development</a> section.
249
250 <p><table id="wide" cellspacing=10%>
251  <tr align=center>
252   <th colspan=2>
253     <hr><br>
254     <font size=+1>Preparation of the environment</font>
255     <br><hr>
256  <tr align=left>
257   <th width=30%>$ mkdir AliRoot
258   <td width=50%>create the working directory
259  <tr align=left>
260   <th>$ cd AliRoot
261   <td>set default to it
262  <tr align=left>
263   <th>$ mkdir pro
264   <td>create pro subdirectory
265  <tr align=left>
266   <th>$ cd pro
267   <td>set default to it
268  <tr align=left>
269   <th>$ ln -s $ALICE_ROOT/* ./
270   <td>link all files here
271  <tr align=left>
272   <th>$ rm lib 
273   <td>remove link for library, we need a local file here to containing the new
274       TPC library
275  <tr align=left>
276   <th>$ rm bin
277   <td>remove bin, we need a local copy of the <var>aliroot</var>
278       executable
279  <tr align=left>
280   <th>$ mkdir bin
281   <td>make a local bin directory 
282  <tr align=left>
283   <th>$ rm CVS
284   <td>remove the link to the CVS directory, we need a local one
285       to check-out files
286  <tr align=left>
287   <th>$ rm TPC
288   <td>remove link for TPC subdirectory, we need the real files here
289  <tr align=left>
290   <th>$ rm ALIROOT
291   <td>remove link to ALIROOT subdirectory, may be this is not really necessary
292       on all systems, but we do it just to be on the safe side
293  <tr align=left>
294   <th>$ cvsa co -r Release-3-02 TPC
295   <td>get from the cvs server the release version of the TPC files to be
296       modified
297  <tr align=left>
298   <th>$ cvsa co -r Release-3-02 ALIROOT
299   <td>get from the server the release version of the ALIROOT files to recreate
300       the executable
301  <tr align=left>
302   <th>$ mkdir -p lib/tgt_$ALICE_TARGET
303   <td>create library directory
304  <tr align=left>
305   <th>$ cd lib/tgt_$ALICE_TARGET
306   <td>set default to the lib directory
307  <tr align=left>
308   <th>$ ln -s $ALICE_ROOT/lib/tgt_$ALICE_TARGET/* ./
309   <td>link all libraries here
310  <tr align=left>
311   <th>$ rm libTPC.sl (on HP)
312   <br>$ rm libTPC.so (on the other systems)
313   <td>remove link to TPC library, we need a real one
314  <tr align=left>
315   <th>$ changeRoot $HOME/AliRoot
316   <td>change the AliRoot root to $HOME/AliRoot via the <em>changeRoot</em> command
317  <tr align=left>
318   <th>$ rehash
319   <td>make sure that the new PATH is taken into account by the shell
320  <tr align=center>
321   <th colspan=2>
322     <hr><br>
323     <font size=+1>Normal development cycle</font>
324     <br><hr>
325  <tr align=left>
326   <th>$ cd $ALICE_ROOT/TPC
327   <td>(1) set default to TPC directory
328  <tr align=left>
329   <th>$ make macroclean
330   <td>clean up all objects
331  <tr align=left>
332   <th>$ emacs AliTPCv1.cxx
333   <td>(2) edit all the files...
334  <tr align=left>
335   <th>$ make
336   <td>(3) recreate ../lib/libTPC.sl
337  <tr align=left>
338   <th>$ cd ../ALIROOT
339   <td>set default to ALIROOT directory
340  <tr align=left>
341   <th>$ make macroclean
342   <td>clean up object files
343  <tr align=left>
344   <th>$ make
345   <td>make new executable
346  <tr align=left>
347   <th>$ cd <em>directory</em>
348   <td>(4) set default elsewhere
349  <tr align=left>
350   <th>$ aliroot
351   <td>(5) run aliroot
352  <tr align=center>
353   <th colspan=2>
354     <hr>
355 </table>
356
357 <p>Steps 1-5 are the normal development cycle after the first pass through the 
358 procedure.
359
360 <hr>
361 <address>
362           <script language="JavaScript">
363              document.write("Last modified "+ document.lastModified)
364              // end of script -->
365           </script>
366 by <a href="mailto:Federico.Carminati@cern.ch">Federico Carminati</a>
367 </address>
368 </BODY>
369 </HTML>