]>
Commit | Line | Data |
---|---|---|
6c1a9d9e | 1 | This README describes the procedure to create a customized component |
2 | library for the ALICE HLT. | |
3 | ||
4 | Please send corrections/suggestions/bugreports to | |
5 | Matthias.Richter@ift.uib.no | |
6 | ||
7 | Part A describes a library embedded into the ALICE HLT build system | |
8 | Part B gives a recipe for using this package stand-alone | |
9 | ||
10 | Note: You can not mix the two alternatives since this would confuse aototools. | |
11 | Our suggestions: If you are developing anyway with the AliRoot HLT module | |
12 | choose alternative A. If you don't use the HLT module explicitly choose | |
13 | alternative B. | |
14 | ||
15 | If you have downloaded the 'alice-hlt-sample' package and want to build and | |
16 | modify it, go directly to Part B. | |
17 | ||
18 | =============================================================================== | |
19 | ===== ===== | |
20 | ===== Part A: The embedded case ===== | |
21 | ===== ===== | |
22 | =============================================================================== | |
23 | ||
24 | This describes how to create a new component library embedded into the | |
25 | ALICE HLT build system. We asume that you have a version of the AliRoot | |
26 | HLT module installed. The top level directory of the package is referred | |
27 | as 'topdir' from now on. | |
28 | ||
29 | 1. Choose a name for your library and the sub-folder: | |
30 | e.g. 'libAliHLTTest' in folder 'Test' | |
31 | 2. Go to the topdir: | |
7b969ef7 | 32 | $ cd <topdir> |
6c1a9d9e | 33 | |
34 | 3. Copy the SampleLib folder as new 'Test' folder | |
7b969ef7 | 35 | $ cp -a SampleLib Test |
6c1a9d9e | 36 | |
2d7ff710 | 37 | 4. Copy libAliHLTSample.pkg to libAliHLTTest.pkg |
7b969ef7 | 38 | $ cp libAliHLTSample.pkg libAliHLTTest.pkg |
6c1a9d9e | 39 | |
2d7ff710 | 40 | 5. Change dir to the new folder |
7b969ef7 | 41 | $ cd Test |
6c1a9d9e | 42 | |
43 | 6. Open 'Makefile.am' with an editor | |
44 | This is the Makefile template for the autotools build system. In particular | |
45 | one defines the library to be built to the lib_LTLIBRARIES variable. | |
46 | Furthermore, source and header files have to be specified, but in our case | |
47 | this is done in the 'lib***.pkg file. By using such a file the library can | |
48 | later easily be added to AliRoot. | |
49 | 6.1. replace all strings 'AliHLTSample' with 'AliHLTTest' | |
50 | ||
51 | 7. Now, you can think about implementing a new component. The packge contains | |
52 | three example components: | |
53 | - AliHLTDummyComponent: a real component which copies data from the input | |
54 | to the output | |
55 | - AliHLTSampleComponent1/2: two dummy components which just demonstrate | |
56 | how several components can be implemented in one library | |
57 | Each of the components has a header file '<component>.h' and a source code | |
7b969ef7 | 58 | file '<component>.cxx' |
6c1a9d9e | 59 | 7.1 Take the DummyComponent, copy the two files (to your component name): |
7b969ef7 | 60 | $ cp AliHLTDummyComponent.h MyTestComponent.h |
61 | $ cp AliHLTDummyComponent.cxx MyTestComponent.cxx | |
6c1a9d9e | 62 | 7.2 Implement the required methods. A tutorial will be added to this package |
63 | soon. A comprehensive online tutorial is available at | |
64 | http://www.kip.uni-heidelberg.de/wiki/HLT | |
65 | ||
66 | 8. Once you are finnished with the first code development, you have to add | |
2d7ff710 | 67 | the new component files to the build system. Open 'libAliHLTTest.pkg' in |
68 | the package topdir | |
6c1a9d9e | 69 | 8.1. Add all your source files to the SRCS variable, remove the files from |
70 | the libAliHLTSample | |
71 | 8.2. Add all header files of classes which should be added to the ROOT | |
72 | dictionary to the CLASS_HDRS variable, remove the files from the | |
73 | libAliHLTSample | |
74 | 8.3. All other header files must be added to the HDRS variable, including the | |
75 | content of the CLASS_HEADERS | |
76 | ||
77 | 9. Now we just have to add our new library to the build system. | |
78 | 9.1 Open Makefile.am in the topdir and add 'Test' to the list of SUBDIRS | |
79 | 9.2 Open configure.ac in the topdir and add 'Test/Makefile' to the list of | |
80 | files to be created: AC_CONFIG_FILES at the end of configure.ac | |
81 | ||
82 | 10.Make sure that all files are saved. Now follow the instruction from the | |
83 | README in the topdir. In principle its enough to go to your build directory | |
84 | and simply type | |
7b969ef7 | 85 | $ make |
86 | $ make install | |
6c1a9d9e | 87 | |
88 | ||
89 | ||
90 | =============================================================================== | |
91 | ===== ===== | |
92 | ===== Part B: Stand-alone package ===== | |
93 | ===== ===== | |
94 | =============================================================================== | |
95 | ||
96 | TOC | |
97 | === | |
98 | 1. Overview | |
99 | 2. Requirements | |
100 | 3. Setting up a version retrieved from CVS | |
101 | 4. Modifying a distributed package | |
102 | 5. Installation | |
103 | 6. Code development | |
104 | 7. Documentation | |
105 | 8. Reporting bugs/Asking for support | |
106 | 9. Committing to the AliRoot CVS | |
107 | ||
108 | 1. Overview | |
109 | =========== | |
110 | This package provides a compilation of shared libraries of the ALICE | |
111 | HLT project and is intended for stand-alone compilation, i.e. not as part | |
112 | of the AliRoot compilation. | |
113 | ||
114 | ||
115 | 2. Requirements | |
116 | =============== | |
2d7ff710 | 117 | At this point you should have downloaded and unpacked a package with name |
118 | alice-hlt-sample.tar.gz. If not, please download it from | |
119 | http://www.kip.uni-heidelberg.de/ti/HLT/software/download/alice-hlt-sample.tar.gz | |
120 | The following description refers to that package. | |
121 | ||
6c1a9d9e | 122 | The package needs both ROOT and AliRoot. Both must be set up in the |
123 | usual way (ROOTSYS, ALICE_ROOT, library locations evtl. specified in | |
124 | LD_LIBRARY_PATH, ...). The package also needs the ALICE HLT component | |
125 | framework. This is part of AliRoot from version v4-05-Release on. You can | |
126 | also download the package from | |
127 | http://www.kip.uni-heidelberg.de/wiki/HLT | |
128 | ||
129 | To set up a version retrieved from CVS, autoconf 2.57, automake 1.6 | |
130 | ,and libtool 1.4 or higher versions are required. Thats the versions | |
131 | which come with the Scientific Linux CERN 3. The same applies if | |
132 | you want to change the Makefiles. | |
133 | ||
134 | If your GNU build tools are too old, ask the maintainers for a distributed | |
135 | package. | |
136 | ||
137 | 3. Setting up a version retrieved from CVS | |
138 | ========================================== | |
139 | Skip this section if you have started from the tar ball. | |
140 | ||
141 | A version checked out from CVS requires a few steps to set up the Makefiles. | |
142 | Go to the directory and run | |
143 | autoreconf -i -f | |
144 | ||
145 | Then continue with the package configuration described in the 'Installation' | |
146 | section. | |
147 | ||
148 | 4. Modifying a distributed package | |
149 | ================================== | |
150 | If you are going the modify a distributed package you might need to re-make | |
151 | the GNU build system by running | |
152 | autoreconf -f -i | |
153 | ||
154 | Please notify the authors about bug fixes/corrections/extensions you made if | |
155 | you consider them worth to be merged into the project. | |
156 | ||
157 | Then continue with the package configuration described in the 'Installation' | |
158 | section. | |
159 | ||
160 | 5. Installation | |
161 | =============== | |
162 | Package build relies on the GNU triplet configure, make and make install. | |
163 | In order to keep the development directory clean, it is recommended to | |
2d7ff710 | 164 | use a separate build directory. Please read the full section before you |
165 | start. The build is in priciple done like | |
6c1a9d9e | 166 | |
167 | mkdir build | |
168 | cd build | |
169 | ../configure | |
170 | make | |
171 | make install | |
172 | ||
173 | You should redirect the output of the make into a file. | |
174 | The default install directory is set to the current directory ($PWD). To | |
175 | override the default directory use the option --prefix=<dir>. More information | |
176 | can be obtained from the configure script by running it with option --help. | |
177 | All binary libraries will be installed under <prefix>/lib. | |
178 | If the directory is equal to $ALICE_ROOT, the libraries will be installed under | |
179 | <prefix>/lib/tgt_<arch> as used for AliRoot. This is a custom extension in | |
180 | order to adapt to the specific AliRoot installation directories. | |
181 | ||
182 | You might need to specify the installation path of the ALICE HLT component | |
183 | framework during packge configuration. This can be done by the option | |
184 | --with-hltbase. | |
185 | Please follow correctly the installation procedure of the framework package. | |
186 | ||
187 | Note: You can have several build directories with different configure options, | |
188 | (e.g. AliRoot versions) but using the same source code. | |
189 | ||
190 | If you need further information on the GNU build system, execute from the | |
191 | top directory: | |
192 | ./configure --help | less | |
193 | ||
194 | 6. Code Development | |
195 | =================== | |
196 | Once you are finnished with the build of the package, you can think about | |
197 | changing the code. The packge contains three example components: | |
198 | - AliHLTDummyComponent: a real component which copies data from the input | |
199 | to the output | |
200 | - AliHLTSampleComponent1/2: two dummy components which just demonstrate | |
201 | how several components can be implemented in one library | |
202 | Each of the components has aheader file '<component>.h' and a source code | |
203 | file '<component>.cxx | |
204 | ||
205 | Leave your build directory and go back to the top directory where you can find | |
2d7ff710 | 206 | the source code as well as the Makefile template Makefile.am. |
207 | 1. Choose a new name of your library (the tutorial uses AliHLTTest) | |
208 | ||
209 | 2. Copy libAliHLTSample.pkg to libAliHLTTest.pkg | |
210 | > cp libAliHLTSample.pkg libAliHLTTest.pkg | |
211 | ||
212 | 3. follow the instructions 6 to 8 of Part A (embedded case). | |
6c1a9d9e | 213 | |
214 | When you are done with this, you can build the library by typing 'make' in your | |
215 | build directory, and install it by make install. | |
216 | ||
217 | 7. Documentation | |
218 | ================ | |
219 | NOTE: DOXYGEN GENERATED DOCUMENTATION WILL BE ADDED SOON !!! | |
220 | Documentation is generated from the source code at compile time if | |
221 | doxygen is installed on the machine. From the build directory, open | |
222 | doc/html/index.html with a web browser. | |
223 | ||
224 | A wiki with detailed information is set up at | |
225 | http://www.kip.uni-heidelberg.de/wiki/HLT | |
226 | ||
227 | 8. Reporting bugs/Asking for support | |
228 | ==================================== | |
229 | Please include the following information into your request: | |
230 | - config.log from your build directory | |
231 | - output of the make process. Note: Redirect BOTH the stdout and stderr | |
232 | channel to a log file. Redirection depends on the shell you are using: | |
233 | bash: make 2>&1 | tee make.log | |
234 | csh: make |& tee make.log | |
235 | The 'tee' command just duplicates the output. | |
236 | - history of the commands you are using for compilation | |
237 | history > history.log | |
238 | ||
239 | 9. Committing to the AliRoot CVS | |
240 | ================================ | |
241 | At some point you might want to add the library to the AliRoot HLT module. | |
242 | Please contact Matthias.Richter@ift.uib.no and send a stable version as a | |
243 | tar archive. |