6356059ebd68306df12461da77f439bb7e508bef
[u/mrichter/AliRoot.git] / HLT / README
1 Package: ALICE HLT
2
3 This package implements the ALICE High Level Trigger analysis framework
4 and analysis component libraries. All files are property of and copyright
5 by the ALICE HLT Project unless stated differently.
6
7 All contributions are under the terms of the 
8 GNU General Public License as published by the Free Software 
9 Foundation. Also see files AUTHORS and THANKS.
10
11 This packages is maintained by Matthias.Richter@ift.uib.no
12 Comments, bug reports, suggestions welcome! 
13
14 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
15 + TOC
16 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
17 + 1. Overview
18 + 2. Requirements
19 + 3. Setting up a version retrieved from CVS
20 + 4. Modifying a distributed package
21 + 5. Installation
22 + 6. Documentation
23 + 7. Further information
24 + 8. Reporting bugs/Asking for support
25 + 9. Committing to the AliRoot CVS
26 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
27
28 1. Overview
29 ===========
30 This package provides a compilation of shared libraries of the ALICE
31 HLT project and is intended for stand-alone compilation, i.e. not as part 
32 of the AliRoot compilation. 
33
34  - \b BASE: The base library (libHLTbase.so) provides the common interface for
35    HLT processing components, the binding into the ALICE offline project
36    AliRoot and a pure C interface to the HLT on-line framework 
37    (Publisher/Subscriber framework)
38
39  - \b SampleLib: The sample library contains examples for component 
40    implementation and a tutorial.
41
42  - \b TPCLib: The HLT code for the TPC
43  - \b TPCLib/OnlineDisplay: HLT visualization code for the TPC
44
45  - \b PHOS: The HLT code for PHOS
46
47  - \b TRD: The HLT code for TRD
48
49  - \b MUON: The HLT code for MUON
50
51 2. Requirements
52 ===============
53 The package needs both ROOT and AliRoot. Both must be set up in the
54 usual way (ROOTSYS, ALICE_ROOT, library locations evtl. specified in
55 LD_LIBRARY_PATH, ...). Actually, the BASE and SampleLib modules are
56 not dependend on AliRoot. The TPCLib does.
57
58 To set up a version retrieved from CVS, autoconf 2.57, automake 1.6
59 ,and libtool 1.4 or higher versions are required. Thats the versions
60 which come with the Scientific Linux CERN 3. The same applies if
61 you want to change the Makefiles.
62
63 If your GNU build tools are too old, ask the maintainers for a distributed
64 package.  
65
66 3. Setting up a version retrieved from CVS
67 ==========================================
68 Skip this section if you have started from the tar ball.
69
70 A version checked out from CVS requires a few steps to set up the Makefiles.
71 Go to the directory and run
72
73   autoreconf -i -f
74
75 Then continue with the package configuration described in the 'Installation'
76 section.
77
78 4. Modifying a distributed package
79 ==================================
80 If you are going the modify a distributed package you might need to re-make 
81 the GNU build system by running
82
83   autoreconf -f -i
84
85 Please notify the authors about bug fixes/corrections/extensions you made if
86 you consider them worth to be merged into the project.
87
88 Then continue with the package configuration described in the 'Installation'
89 section.
90
91 5. Installation
92 ===============
93 Package build relies on the GNU triplet configure, make and make install.
94 In order to keep the development directory clean, it is recommended to
95 use a separate build directory. 
96
97 \b NOTE: Autotools creates the Makefiles from templates. All \b changes have to
98 be done to the \b Makefile.am templates.
99
100 It is recommended to read the complete section before the build process.
101
102 5.1 For the impatiant user
103 --------------------------
104
105   mkdir build
106   cd build
107   ../configure
108   make
109   make install
110
111 5.2 Installation directory
112 --------------------------
113 The default install directory is set to the current directory ($PWD). To
114 override the default directory use the option 
115   --prefix=<dir>. 
116 More information can be obtained from the configure script by running it with
117 option --help. All binary libraries will be installed under
118   <prefix>/lib.
119
120 If the directory is equal to $ALICE_ROOT, the libraries will be installed under
121   <prefix>/lib/tgt_<arch>
122 as used for AliRoot. This is a custom extension in
123 order to adapt to the specific AliRoot installation directories.
124
125 5.3 For the AliRoot user
126 ------------------------
127 To install all libraries in the AliRoot lib dir:
128
129   mkdir build
130   cd build
131   ../configure --prefix=$ALICE_ROOT
132   make
133   make install
134
135 5.4 Package options
136 -------------------
137 Some important options (all options are on by default):
138
139   --disable-sample           # disable compilation the sample library
140   --disable-tpc              # disable compilation the TPC library
141   --disable-phos             # disable compilation the PHOS library
142   --disable-trd              # disable compilation the TRD library
143   --disable-aliroot-logging  # disable logging
144
145 Debugging (default disabled)
146
147   --enable-debug             # enable debugging: symbols & messages
148
149 Optimization (default -O2)
150
151   --disable-optimization     # disable compiler optimization
152   --enable-optimization<=l>  # enable compiler optimization level l
153
154 5.5 External packages
155 ---------------------
156 PubSub framework: the TPC online display needs the HOMER interface, which
157 is currently part of the PubSub framework. It is planned to integrate it
158 into AliRoot.<br>
159 If the TPC online display is not necessary one can skip this option.
160
161   --with-pubsub=<dir>        # the top dir of the HLT PubSub framework
162
163 5.6 Final remarks/further information 
164 -------------------------------------
165 \b Note: You can have several build directories with different configure
166 options, but using the same source code. 
167
168 If you need further information on the GNU build system, execute from the 
169 top directory:
170
171   ./configure --help | less
172
173
174 6. Documentation
175 ================
176 Documentation is build as part of the build process if \b doxygen is installed.
177 The documentation can be opended from the
178   doc/html/
179 sub-folder of your build directory. E.g with a web browser like firefox
180 (assuming you are in the build directory):<br>
181   firefox file://`pwd`/doc/html/index.html
182
183 A special target can be used to make a tar ball out of the documentation (again
184 provided you are in the build directory):<br>
185   (cd doc && make tar-ball)
186
187 On-line documentation is available at
188   http://web.ift.uib.no/~kjeks/doc/alice-hlt/
189
190 7. Further information
191 ======================
192 A wiki with detailed information is set up at
193   http://www.kip.uni-heidelberg.de/wiki/HLT
194
195 8. Reporting bugs/Asking for support
196 ====================================
197 Please include the following information into your request:
198  - config.log from your build directory
199  - output of the make process. Note: Redirect BOTH the stdout and stderr
200    channel to a log file. Redirection depends on the shell you are using:     <br>
201     bash: make 2>&1 | tee make.log                                            <br>
202     csh: make |& tee make.log                                                 <br>
203    The 'tee' command just duplicates the output.
204  - history of the commands you are using for compilation
205    history > history.log
206
207 9. Committing to the AliRoot CVS
208 ================================
209 For development of HLT analysis code check out a HEAD version from the 
210 repository and implement your code. 
211
212 For committing do:
213  - 1. make sure that the code changes are correct                    <br><tt>
214       cvs diff | less                                                </tt><br>
215       \b Remember to restore all temporary changes you made (e.g. log level)
216  - 2. cvs update
217  - 3. correct merging conflicts
218  - 4. compile and test your code again
219  - 5. send the whole HLT module except the build sub-directories to
220       Matthias.Richter@ift.uib.no
221  - 6. you will get a notification when the code is committed, right after that
222       you must either do another cvs update or check out the complete module
223       again in order to have the right CVS information.