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