[u/mrichter/AliRoot.git] / html / installation.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
               "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>
<TITLE>Installation</TITLE>
<link rev="made" href="mailto:Federico.Carminati@cern.ch">
<STYLE>
BODY	{	
	background:	#FFFFFF;
	}	

COL, COLGROUP, TABLE, TBODY, TD, TR	{	
	color:	black;
	text-decoration:	none;
	border-color:	black;
	border-style:	none;
	background:	#FFFFFF;
	}			

</STYLE>
<link rel="stylesheet" href="http://www.w3.org/StyleSheets/Core/Swiss" type="text/css">
</HEAD>

<BODY background=#FFFFFF>
<TABLE>
<TR>
<TD><img src="picts/MadHatter.gif" alt="ALICE Off-line Project Logo">
<TD><img src="picts/installation_name.gif" alt="Installation">
<TD><img src="picts/AliceLogo.gif" alt="ALICE Logo">
</TR>
</TABLE>

<h2>Installation</h2>

<ol> 
<p><li> Install <a href="http://root.cern.ch">ROOT</a> and define the
necessary variables correctly.

<p><li> Decide where the code will reside (from here on <i>directory</i>).

<p><li>Define the following global variables in the login script

<p><table align=centre borders=no>
<tr><th align=left>variable</th><th align=left>value</th></tr>
<tr><td width=30%>ALICE	       </td><td> <i>directory</i>
<tr><td>ALICE_LEVEL		</td><td> pro </td></tr>
<tr><td>ALICE_ROOT		</td><td> $ALICE/$ALICE_LEVEL </td></tr>
<tr><td>ALICE_TARGET		</td><td> `uname` 
(i.e. result of the Unix <b>uname</b> command)</td></tr>
<tr><td colspan=2><i><center>on all systems but HP-UX</center></i></td></tr>
<tr><td>LD_LIBRARY_PATH</td>
<td>$ALICE_ROOT/lib/tgt_${ALICE_TARGET}\:$LD_LIBRARY_PATH</td></tr>
<tr><td colspan=2><i><center>on HP-UX</center></i></td></tr>
<tr><td>SHLIB_PATH</td>
<td>$ALICE_ROOT/lib/tgt_${ALICE_TARGET}\:$SHLIB_PATH</td></tr>
<tr><td>PATH</td>
<td> $PATH\:$ALICE_ROOT/bin/tgt_${ALICE_TARGET} </td></tr>
</table>

<p>At this point you should logout, login again and check that the symbols
are set correctly.

<p><li> Retrieve the AliRoot code. There are two ways to do this:

<ul> 
<p><li> <em>From a tar file</em>. This is the preferred way for those who
do not have an internet connection to the <em>cvs</em> server from the
machine where the code has to be installed. The <a
href="ftp://pcepaip01.cern.ch/pub">files</a> containing the latest release
should be brought on the target machine. Three files are offered:

<p><table align=center borders=no>
<tr><th align=left>File<th align=left>Content</tr>
<tr><td align=center colspan=2><em>Either</em></tr>
<tr><td>AliOffline<i>MM.mm-pp</i>.tar.gz
<td>Code and the data files of ALICE Off-line</tr>
<tr><td align=center colspan=2><em>Or</em></tr>
<tr><td>AliLibs<i>MM.mm-pp</i>.tar.gz
<td>Code and the data files of the auxiliary libraries</tr>
<tr><td>AliRoot<i>MM.mm-pp</i>.tar.gz
<td>All the code and the data files of the AliRoot system</tr>
</table>

<p> <i>MM.mm-pp</i> is the number of the latest <i>M</i>ajor and
<i>m</i>inor version and the <i>p</i>atch number. The file(s) have to be
unpacked into the $ALICE directory via the command:

<p><pre>$ gtar xvfz Ali[...].tar.gz</pre>


<p><li> <em>From cvs remote cvs server</em>. This method has the advantage
that new patches can be incrementally retrieved and installed via internet.
At the moment the problem is that the version of cvs currently installed at
CERN (1.09) does not support well binary files. Therefore some data files
will be missing with this download mechanism, and these will have to be
fetched <em>by hand</em>. The setup of the access to the remote cvs server
is described in the Code Development section. The
code is dowloaded via the command:

<p><pre>
$ cd $ALICE
$ cvsa co -d pro AliRoot
</pre>

</ul>

<p><li>install the CERN library part

<p><pre>
$ cd $ALICE_ROOT
$ gmake cernlibs
</pre>

<p><li>Install the ALICE specific software

<p><pre>
$ cd $ALICE_ROOT
$ gmake
</pre>

<p><li>Copy the file $ALICE_ROOT/.rootrc to your home directory

<p><li>Change to your home directory and run the code

<p>
<pre>
$ cd
$ aliroot

<output from aliroot>

root [1] .x menu.C
</pre>
</ol>

<h2>Code development and user environment</h2>

<p>If the ALICE environment is set up correctly, the
<var>$ALICE_ROOT/lib/tgt_$ALICE_TARGET</var> directory is in the shared
libraries load path, and the <var>$ALICE_ROOT/bin/tgt_$ALICE_TARGET</var>
directory is in the PATH variable. This means that the command aliroot will
in fact correspond to the file
<var>$ALICE_ROOT/bin/tgt_$ALICE_TARGET/aliroot</var>.

<p>This is convenient for the normal user, but as soon as the user wants to
modify one or more directories, this arrangement becomes inefficient
because if a local copy of one of the shared libraries is remade, the
linker will always find the official unmodified one that sits in the above
directory before the local one in the load library path. Moreover, and
unless the full path is specified, the local version of the <b>aliroot</b>
executable will be ignored and the official version executed.

<p>Therefore in order to develop one or more packages locally
(let's say the TPC) and make modifications, the following steps should be
performed. We suppose here that the remote cvs server has been setup correctly
as explained in the <a href="management.html">code management</a> section.

<p><table>
 <tr align=left>
  <th width=30%>$ mkdir AliRoot
  <td width=50%>create the working directory
 <tr align=left>
  <th>$ cd AliRoot
  <td>set default to it
 <tr align=left>
  <th>$ mkdir pro
  <td>create pro subdirectory
 <tr align=left>
  <th>$ cd pro
  <td>set default to it
 <tr align=left>
  <th>$ ln -s $ALICE_ROOT/* ./
  <td>link all files here
 <tr align=left>
  <th>$ rm lib
  <td>remove link for library, we need a local file here to containing the new
      TPC library
 <tr align=left>
  <th>$ rm bin
  <td>remove link for bin directory, we need it to rebuild <b>aliroot</b> executable
 <tr align=left>
  <th>$ rm TPC
  <td>remove link for TPC subdirectory, we need the real files here
 <tr align=left>
  <th>$ rm ALIROOT
  <td>remove link to ALIROOT subdirectory, may be this is not really necessary
      on all systems, but we do it just to be on the safe side
 <tr align=left>
  <th>$ cvsa co TPC
  <td>get from the cvs server the TPC files to be modified
 <tr align=left>
  <th>$ cvsa co ALIROOT
  <td>get from the server the ALIROOT files to recreate the executable
 <tr align=left>
  <th>$ mkdir -p lib/tgt_$ALICE_TARGET
  <td>create library directory
 <tr align=left>
  <th>$ cd lib/tgt_$ALICE_TARGET
  <td>set default to the lib directory
 <tr align=left>
  <th>$ ln -s $ALICE_ROOT/lib/* ./
  <td>link all libraries here
 <tr align=left>
  <th>$ rm libTPC.sl
  <td>remove link to TPC library, we need a real one
 <tr align=left>
  <th>$ changeRoot $HOME/AliRoot
  <td>change the AliRoot root to $HOME/AliRoot
 <tr align=left>
  <th>$ rehash
  <td>make sure that the new PATH is taken into account by the shell
 <tr align=left>
  <th>$ cd $ALICE_ROOT/TPC
  <td>(1) set default to TPC directory
 <tr align=left>
  <th>$ make macroclean
  <td>clean up all objects
 <tr align=left>
  <th>$ emacs AliTPCv1.cxx
  <td>(2) edit all the files...
 <tr align=left>
  <th>$ make
  <td>(3) recreate ../lib/libTPC.sl
 <tr align=left>
  <th>$ cd ../ALIROOT
  <td>set default to ALIROOT directory
 <tr align=left>
  <th>$ make macroclean
  <td>clean up object files
 <tr align=left>
  <th>$ make
  <td>make new executable
 <tr align=left>
  <th>$ cd <em>directory</em>
  <td>(4) set default elsewhere
 <tr align=left>
  <th>$ aliroot
  <td>(5) run aliroot
</table>

<p>Steps 1-5 are the normal development cycle after the first pass through the 
procedure.

<hr>
<address>
          <script language="JavaScript">
             document.write("Last modified "+ document.lastModified)
             // end of script -->
          </script>
by <a href="mailto:Federico.Carminati@cern.ch">Federico Carminati</a>
</address>
</BODY>
</HTML>
Commit	Line	Data
14c31136	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	<link rev="made" href="mailto:Federico.Carminati@cern.ch">
	7	<STYLE>
	8	BODY {
	9	background: #FFFFFF;
	10	}
	11
	12	COL, COLGROUP, TABLE, TBODY, TD, TR {
	13	color: black;
	14	text-decoration: none;
	15	border-color: black;
	16	border-style: none;
	17	background: #FFFFFF;
	18	}
	19
	20	</STYLE>
	21	<link rel="stylesheet" href="http://www.w3.org/StyleSheets/Core/Swiss" type="text/css">
	22	</HEAD>
	23
	24	<BODY background=#FFFFFF>
	25	<TABLE>
	26	<TR>
	27	<TD><img src="picts/MadHatter.gif" alt="ALICE Off-line Project Logo">
87ad6e14	28	<TD><img src="picts/installation_name.gif" alt="Installation">
14c31136	29	<TD><img src="picts/AliceLogo.gif" alt="ALICE Logo">
	30	</TR>
	31	</TABLE>
	32
	33	<h2>Installation</h2>
	34
	35	<ol>
	36	<p><li> Install <a href="http://root.cern.ch">ROOT</a> and define the
	37	necessary variables correctly.
	38
	39	<p><li> Decide where the code will reside (from here on <i>directory</i>).
	40
	41	<p><li>Define the following global variables in the login script
	42
	43	<p><table align=centre borders=no>
	44	<tr><th align=left>variable</th><th align=left>value</th></tr>
	45	<tr><td width=30%>ALICE </td><td> <i>directory</i>
	46	<tr><td>ALICE_LEVEL </td><td> pro </td></tr>
	47	<tr><td>ALICE_ROOT </td><td> $ALICE/$ALICE_LEVEL </td></tr>
	48	<tr><td>ALICE_TARGET </td><td> `uname`
	49	(i.e. result of the Unix <b>uname</b> command)</td></tr>
	50	<tr><td colspan=2><i><center>on all systems but HP-UX</center></i></td></tr>
	51	<tr><td>LD_LIBRARY_PATH</td>
	52	<td>$ALICE_ROOT/lib/tgt_${ALICE_TARGET}\:$LD_LIBRARY_PATH</td></tr>
	53	<tr><td colspan=2><i><center>on HP-UX</center></i></td></tr>
	54	<tr><td>SHLIB_PATH</td>
	55	<td>$ALICE_ROOT/lib/tgt_${ALICE_TARGET}\:$SHLIB_PATH</td></tr>
	56	<tr><td>PATH</td>
	57	<td> $PATH\:$ALICE_ROOT/bin/tgt_${ALICE_TARGET} </td></tr>
	58	</table>
	59
	60	<p>At this point you should logout, login again and check that the symbols
	61	are set correctly.
	62
	63	<p><li> Retrieve the AliRoot code. There are two ways to do this:
	64
	65	<ul>
	66	<p><li> <em>From a tar file</em>. This is the preferred way for those who
	67	do not have an internet connection to the <em>cvs</em> server from the
	68	machine where the code has to be installed. The <a
	69	href="ftp://pcepaip01.cern.ch/pub">files</a> containing the latest release
	70	should be brought on the target machine. Three files are offered:
	71
	72	<p><table align=center borders=no>
	73	<tr><th align=left>File<th align=left>Content</tr>
	74	<tr><td align=center colspan=2><em>Either</em></tr>
	75	<tr><td>AliOffline<i>MM.mm-pp</i>.tar.gz
	76	<td>Code and the data files of ALICE Off-line</tr>
	77	<tr><td align=center colspan=2><em>Or</em></tr>
	78	<tr><td>AliLibs<i>MM.mm-pp</i>.tar.gz
	79	<td>Code and the data files of the auxiliary libraries</tr>
	80	<tr><td>AliRoot<i>MM.mm-pp</i>.tar.gz
	81	<td>All the code and the data files of the AliRoot system</tr>
	82	</table>
	83
	84	<p> <i>MM.mm-pp</i> is the number of the latest <i>M</i>ajor and
20b19209	85	<i>m</i>inor version and the <i>p</i>atch number. The file(s) have to be
20b19209	86	unpacked into the $ALICE directory via the command:
14c31136	87
	88	<p><pre>$ gtar xvfz Ali[...].tar.gz</pre>
	89
	90
	91	<p><li> <em>From cvs remote cvs server</em>. This method has the advantage
	92	that new patches can be incrementally retrieved and installed via internet.
	93	At the moment the problem is that the version of cvs currently installed at
	94	CERN (1.09) does not support well binary files. Therefore some data files
	95	will be missing with this download mechanism, and these will have to be
	96	fetched <em>by hand</em>. The setup of the access to the remote cvs server
1f3e54b9	97	is described in the Code Development section. The
14c31136	98	code is dowloaded via the command:
	99
	100	<p><pre>
	101	$ cd $ALICE
	102	$ cvsa co -d pro AliRoot
	103	</pre>
	104
	105	</ul>
	106
	107	<p><li>install the CERN library part
	108
	109	<p><pre>
	110	$ cd $ALICE_ROOT
	111	$ gmake cernlibs
	112	</pre>
	113
	114	<p><li>Install the ALICE specific software
	115
	116	<p><pre>
	117	$ cd $ALICE_ROOT
	118	$ gmake
	119	</pre>
	120
	121	<p><li>Copy the file $ALICE_ROOT/.rootrc to your home directory
	122
	123	<p><li>Change to your home directory and run the code
	124
	125	<p>
	126	<pre>
	127	$ cd
	128	$ aliroot
	129
	130	<output from aliroot>
	131
	132	root [1] .x menu.C
	133	</pre>
	134	</ol>
	135
87ad6e14	136	<h2>Code development and user environment</h2>
	137
	138	<p>If the ALICE environment is set up correctly, the
	139	<var>$ALICE_ROOT/lib/tgt_$ALICE_TARGET</var> directory is in the shared
	140	libraries load path, and the <var>$ALICE_ROOT/bin/tgt_$ALICE_TARGET</var>
	141	directory is in the PATH variable. This means that the command aliroot will
	142	in fact correspond to the file
	143	<var>$ALICE_ROOT/bin/tgt_$ALICE_TARGET/aliroot</var>.
	144
	145	<p>This is convenient for the normal user, but as soon as the user wants to
	146	modify one or more directories, this arrangement becomes inefficient
	147	because if a local copy of one of the shared libraries is remade, the
	148	linker will always find the official unmodified one that sits in the above
	149	directory before the local one in the load library path. Moreover, and
	150	unless the full path is specified, the local version of the <b>aliroot</b>
	151	executable will be ignored and the official version executed.
	152
	153	<p>Therefore in order to develop one or more packages locally
	154	(let's say the TPC) and make modifications, the following steps should be
	155	performed. We suppose here that the remote cvs server has been setup correctly
	156	as explained in the <a href="management.html">code management</a> section.
	157
	158	<p><table>
	159	<tr align=left>
	160	<th width=30%>$ mkdir AliRoot
	161	<td width=50%>create the working directory
	162	<tr align=left>
	163	<th>$ cd AliRoot
	164	<td>set default to it
	165	<tr align=left>
	166	<th>$ mkdir pro
	167	<td>create pro subdirectory
	168	<tr align=left>
	169	<th>$ cd pro
	170	<td>set default to it
	171	<tr align=left>
	172	<th>$ ln -s $ALICE_ROOT/* ./
	173	<td>link all files here
	174	<tr align=left>
	175	<th>$ rm lib
	176	<td>remove link for library, we need a local file here to containing the new
	177	TPC library
	178	<tr align=left>
	179	<th>$ rm bin
	180	<td>remove link for bin directory, we need it to rebuild <b>aliroot</b> executable
	181	<tr align=left>
	182	<th>$ rm TPC
	183	<td>remove link for TPC subdirectory, we need the real files here
	184	<tr align=left>
	185	<th>$ rm ALIROOT
	186	<td>remove link to ALIROOT subdirectory, may be this is not really necessary
	187	on all systems, but we do it just to be on the safe side
	188	<tr align=left>
	189	<th>$ cvsa co TPC
	190	<td>get from the cvs server the TPC files to be modified
	191	<tr align=left>
	192	<th>$ cvsa co ALIROOT
	193	<td>get from the server the ALIROOT files to recreate the executable
	194	<tr align=left>
	195	<th>$ mkdir -p lib/tgt_$ALICE_TARGET
	196	<td>create library directory
	197	<tr align=left>
	198	<th>$ cd lib/tgt_$ALICE_TARGET
	199	<td>set default to the lib directory
200	<tr align=left>
201	<th>$ ln -s $ALICE_ROOT/lib/* ./
202	<td>link all libraries here
203	<tr align=left>
204	<th>$ rm libTPC.sl
205	<td>remove link to TPC library, we need a real one
206	<tr align=left>
207	<th>$ changeRoot $HOME/AliRoot
208	<td>change the AliRoot root to $HOME/AliRoot
209	<tr align=left>
210	<th>$ rehash
211	<td>make sure that the new PATH is taken into account by the shell
212	<tr align=left>
213	<th>$ cd $ALICE_ROOT/TPC
214	<td>(1) set default to TPC directory
215	<tr align=left>
216	<th>$ make macroclean
217	<td>clean up all objects
218	<tr align=left>
219	<th>$ emacs AliTPCv1.cxx
220	<td>(2) edit all the files...
221	<tr align=left>
222	<th>$ make
223	<td>(3) recreate ../lib/libTPC.sl
224	<tr align=left>
225	<th>$ cd ../ALIROOT
226	<td>set default to ALIROOT directory
227	<tr align=left>
228	<th>$ make macroclean
229	<td>clean up object files
230	<tr align=left>
231	<th>$ make
232	<td>make new executable
233	<tr align=left>
234	<th>$ cd <em>directory</em>
235	<td>(4) set default elsewhere
236	<tr align=left>
237	<th>$ aliroot
238	<td>(5) run aliroot
239	</table>
240
241	<p>Steps 1-5 are the normal development cycle after the first pass through the
242	procedure.
243
14c31136	244	<hr>
	245	<address>
	246	<script language="JavaScript">
	247	document.write("Last modified "+ document.lastModified)
	248	// end of script -->
	249	</script>
	250	by <a href="mailto:Federico.Carminati@cern.ch">Federico Carminati</a>
	251	</address>
	252	</BODY>
	253	</HTML>