HLT/SampleLib/README

   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:
  32 $ cd <topdir>
  33
  34 3. Copy the SampleLib folder as new 'Test' folder
  35 $ cp -a SampleLib Test
  36
  37 4. Copy libAliHLTSample.pkg to libAliHLTTest.pkg
  38 $ cp libAliHLTSample.pkg libAliHLTTest.pkg
  39
  40 5. Change dir to the new folder
  41 $ cd Test
  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
  58    file '<component>.cxx'
  59 7.1 Take the DummyComponent, copy the two files (to your component name):
  60 $ cp AliHLTDummyComponent.h MyTestComponent.h
  61 $ cp AliHLTDummyComponent.cxx MyTestComponent.cxx
  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
  67    the new component files to the build system. Open 'libAliHLTTest.pkg' in
  68    the package topdir
  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
  85 $ make
  86 $ make install
  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 ===============
 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
 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
 164 use a separate build directory. Please read the full section before you
 165 start. The build is in priciple done like
 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
 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).
 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.