minor changes to the "download code" part.
[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: the
144     preferred way is retrieving a tar file on the ftp server and the
145     slow and network consuming way is checking out the whole cvs tree using
146     cvs. cvsup will be available soon.
147     
148 <ul> 
149 <p><li> <em>From a tar file</em>. This is the preferred way. Tar files
150     for the different releases including an up-to-date file remade
151     every night are available on the ftp server
152     <a href="ftp://alisoft.cern.ch/pub/offline">
153     ftp://alisoft.cern.ch/pub/offline</a>. The tar files include the
154     "CVS" subdirectories for the anonymous cvs user (login "cvs"). So after
155     getting the full tar file, it is possible to incrementally update
156     the code using cvs.
157
158     <p> The tar file(s) can to be unpacked into the ALICE directory
159     via the command: 
160     
161     <p><pre>$ gtar xvfz V3.XX.tar.gz</pre>
162     
163     <p> A script <a href="ftp://alisoft.cern.ch/pub/misc/">changeCVSRoot</a>
164     is available to convert a CVS tree under user "cvs" to another
165     user. For example, <pre> ChangeCVSRoot asmith </pre>
166     
167 <p><li> <em>From cvs remote cvs server</em>.  The setup for the access
168     to the remote cvs server is described in the
169     <A HREF="/offline/development.html#Code">Code Development section</A>.
170     The code can be downloaded via the command:
171
172 <p><pre>
173 $ cd $ALICE
174 $ cvsa co -r Release-3-02 -d pro AliRoot
175 </pre>
176
177 </ul>
178
179 <p><li>install the CERN library part
180
181 <p><pre>
182 $ cd $ALICE_ROOT
183 $ gmake cernlibs
184 </pre>
185
186 <p><li>Install the ALICE specific software
187
188 <p><pre>
189 $ cd $ALICE_ROOT
190 $ gmake
191 </pre>
192
193 <p><li>Copy the file $ALICE_ROOT/.rootrc to your home directory
194
195 <p><li>For users with c-like shells, update your search path:
196
197 <p>
198 <pre>
199 $ rehash
200 </pre>
201
202 <p>This usually has to be done only once, after having defined the new PATH.
203
204 <p><li>Change to your home directory and run the code
205
206 <p>
207 <pre>
208 $ cd
209 $ aliroot
210
211 <output from aliroot>
212
213 root [1] .x menu.C
214 </pre>
215 </ol>
216
217 <h2><A HREF="#Content" NAME="Code">Code development and user environment</A></h2>
218
219 <p>If the ALICE environment is set up correctly, the
220 <var>$ALICE_ROOT/lib/tgt_$ALICE_TARGET</var> directory is in the shared
221 libraries load path, and the <var>$ALICE_ROOT/bin/tgt_$ALICE_TARGET</var>
222 directory is in the PATH variable. This means that the command
223 <kbd>aliroot</kbd> will in fact correspond to the file
224 <var>$ALICE_ROOT/bin/tgt_$ALICE_TARGET/aliroot</var>.
225
226 <p>This is convenient for the normal user, but as soon as the user wants to
227 modify one or more directories, this arrangement becomes inefficient
228 because if a local copy of one of the shared libraries is remade, the
229 linker will always find the official unmodified one that sits in the above
230 directory before the local one in the load library path. Moreover, and
231 unless the full path is specified, the local version of the <b>aliroot</b>
232 executable will be ignored and the official version executed.
233
234 <p>Therefore in order to develop one or more packages locally
235 (let's say the TPC) and make modifications, the following steps should be
236 performed. We suppose here that the remote cvs server has been setup correctly
237 as explained in the <a href="../development.html">code development</a> section.
238
239 <p><table id="wide" cellspacing=10%>
240  <tr align=center>
241   <th colspan=2>
242     <hr><br>
243     <font size=+1>Preparation of the environment</font>
244     <br><hr>
245  <tr align=left>
246   <th width=30%>$ mkdir AliRoot
247   <td width=50%>create the working directory
248  <tr align=left>
249   <th>$ cd AliRoot
250   <td>set default to it
251  <tr align=left>
252   <th>$ mkdir pro
253   <td>create pro subdirectory
254  <tr align=left>
255   <th>$ cd pro
256   <td>set default to it
257  <tr align=left>
258   <th>$ ln -s $ALICE_ROOT/* ./
259   <td>link all files here
260  <tr align=left>
261   <th>$ rm lib 
262   <td>remove link for library, we need a local file here to containing the new
263       TPC library
264  <tr align=left>
265   <th>$ rm bin
266   <td>remove bin, we need a local copy of the <var>aliroot</var>
267       executable
268  <tr align=left>
269   <th>$ mkdir bin
270   <td>make a local bin directory 
271  <tr align=left>
272   <th>$ rm CVS
273   <td>remove the link to the CVS directory, we need a local one
274       to check-out files
275  <tr align=left>
276   <th>$ rm TPC
277   <td>remove link for TPC subdirectory, we need the real files here
278  <tr align=left>
279   <th>$ rm ALIROOT
280   <td>remove link to ALIROOT subdirectory, may be this is not really necessary
281       on all systems, but we do it just to be on the safe side
282  <tr align=left>
283   <th>$ cvsa co -r Release-3-02 TPC
284   <td>get from the cvs server the release version of the TPC files to be
285       modified
286  <tr align=left>
287   <th>$ cvsa co -r Release-3-02 ALIROOT
288   <td>get from the server the release version of the ALIROOT files to recreate
289       the executable
290  <tr align=left>
291   <th>$ mkdir -p lib/tgt_$ALICE_TARGET
292   <td>create library directory
293  <tr align=left>
294   <th>$ cd lib/tgt_$ALICE_TARGET
295   <td>set default to the lib directory
296  <tr align=left>
297   <th>$ ln -s $ALICE_ROOT/lib/tgt_$ALICE_TARGET/* ./
298   <td>link all libraries here
299  <tr align=left>
300   <th>$ rm libTPC.sl (on HP)
301   <br>$ rm libTPC.so (on the other systems)
302   <td>remove link to TPC library, we need a real one
303  <tr align=left>
304   <th>$ changeRoot $HOME/AliRoot
305   <td>change the AliRoot root to $HOME/AliRoot via the <em>changeRoot</em> command
306  <tr align=left>
307   <th>$ rehash
308   <td>make sure that the new PATH is taken into account by the shell
309  <tr align=center>
310   <th colspan=2>
311     <hr><br>
312     <font size=+1>Normal development cycle</font>
313     <br><hr>
314  <tr align=left>
315   <th>$ cd $ALICE_ROOT/TPC
316   <td>(1) set default to TPC directory
317  <tr align=left>
318   <th>$ make macroclean
319   <td>clean up all objects
320  <tr align=left>
321   <th>$ emacs AliTPCv1.cxx
322   <td>(2) edit all the files...
323  <tr align=left>
324   <th>$ make
325   <td>(3) recreate ../lib/libTPC.sl
326  <tr align=left>
327   <th>$ cd ../ALIROOT
328   <td>set default to ALIROOT directory
329  <tr align=left>
330   <th>$ make macroclean
331   <td>clean up object files
332  <tr align=left>
333   <th>$ make
334   <td>make new executable
335  <tr align=left>
336   <th>$ cd <em>directory</em>
337   <td>(4) set default elsewhere
338  <tr align=left>
339   <th>$ aliroot
340   <td>(5) run aliroot
341  <tr align=center>
342   <th colspan=2>
343     <hr>
344 </table>
345
346 <p>Steps 1-5 are the normal development cycle after the first pass through the 
347 procedure.
348
349 <hr>
350 <address>
351           <script language="JavaScript">
352              document.write("Last modified "+ document.lastModified)
353              // end of script -->
354           </script>
355 by <a href="mailto:Federico.Carminati@cern.ch">Federico Carminati</a>
356 </address>
357 </BODY>
358 </HTML>