[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">
<link rel="stylesheet" href="http://www.w3.org/StyleSheets/Core/Swiss" type="text/css">
<STYLE type="text/css">

BODY	{	
	background:	#FFFFFF;
	}	

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

TABLE.wide {
	cellspacing: 100%;
	background: #FF0000
	}

</STYLE>
</HEAD>

<BODY>
<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><A NAME="#Content">Content</A></H2>
<UL>
<LI><A HREF="#Installation">Installation</A>
<LI><A HREF="#Code">Code development and user environment</A>
</UL>

<HR>

<h2><A HREF="#Content" NAME="Installation">Installation</A></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>For users with c-like shells, update your search path:

<p>
<pre>
$ rehash
</pre>

<p>This usually has to be done only once, after having defined the new PATH.

<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><A HREF="#Content" NAME="Code">Code development and user environment</A></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="../development.html">code development</a> section.

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