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