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. Change dir to the new folder
  38 > cd Test
  39
  40 5. Rename libAliHLTSample.pkg to libAliHLTTest.pkg
  41 > mv libAliHLTSample.pkg libAliHLTTest.pkg
  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'
  68 8.1. Add all your source files to the SRCS variable, remove the files from
  69      the libAliHLTSample
  70 8.2. Add all header files of classes which should be added to the ROOT
  71      dictionary to the CLASS_HDRS variable, remove the files from the
  72      libAliHLTSample
  73 8.3. All other header files must be added to the HDRS variable, including the
  74      content of the CLASS_HEADERS
  75
  76 9. Now we just have to add our new library to the build system.
  77 9.1 Open Makefile.am in the topdir and add 'Test' to the list of SUBDIRS
  78 9.2 Open configure.ac in the topdir and add 'Test/Makefile' to the list of
  79     files to be created: AC_CONFIG_FILES at the end of configure.ac
  80
  81 10.Make sure that all files are saved. Now follow the instruction from the
  82    README in the topdir. In principle its enough to go to your build directory
  83    and simply type
  84 > make
  85 > make install
  86
  87
  88
  89 ===============================================================================
  90 =====                                                                     =====
  91 =====                Part B: Stand-alone package                          =====
  92 =====                                                                     =====
  93 ===============================================================================
  94
  95 TOC
  96 ===
  97 1. Overview
  98 2. Requirements
  99 3. Setting up a version retrieved from CVS
 100 4. Modifying a distributed package
 101 5. Installation
 102 6. Code development
 103 7. Documentation
 104 8. Reporting bugs/Asking for support
 105 9. Committing to the AliRoot CVS
 106
 107 1. Overview
 108 ===========
 109 This package provides a compilation of shared libraries of the ALICE
 110 HLT project and is intended for stand-alone compilation, i.e. not as part
 111 of the AliRoot compilation.
 112
 113
 114 2. Requirements
 115 ===============
 116 The package needs both ROOT and AliRoot. Both must be set up in the
 117 usual way (ROOTSYS, ALICE_ROOT, library locations evtl. specified in
 118 LD_LIBRARY_PATH, ...). The package also needs the ALICE HLT component
 119 framework. This is part of AliRoot from version v4-05-Release on. You can
 120 also download the package from
 121 http://www.kip.uni-heidelberg.de/wiki/HLT
 122
 123 To set up a version retrieved from CVS, autoconf 2.57, automake 1.6
 124 ,and libtool 1.4 or higher versions are required. Thats the versions
 125 which come with the Scientific Linux CERN 3. The same applies if
 126 you want to change the Makefiles.
 127
 128 If your GNU build tools are too old, ask the maintainers for a distributed
 129 package.
 130
 131 3. Setting up a version retrieved from CVS
 132 ==========================================
 133 Skip this section if you have started from the tar ball.
 134
 135 A version checked out from CVS requires a few steps to set up the Makefiles.
 136 Go to the directory and run
 137 autoreconf -i -f
 138
 139 Then continue with the package configuration described in the 'Installation'
 140 section.
 141
 142 4. Modifying a distributed package
 143 ==================================
 144 If you are going the modify a distributed package you might need to re-make
 145 the GNU build system by running
 146  autoreconf -f -i
 147
 148 Please notify the authors about bug fixes/corrections/extensions you made if
 149 you consider them worth to be merged into the project.
 150
 151 Then continue with the package configuration described in the 'Installation'
 152 section.
 153
 154 5. Installation
 155 ===============
 156 Package build relies on the GNU triplet configure, make and make install.
 157 In order to keep the development directory clean, it is recommended to
 158 use a separate build directory.
 159
 160   mkdir build
 161   cd build
 162   ../configure
 163   make
 164   make install
 165
 166 You should redirect the output of the make into a file.
 167 The default install directory is set to the current directory ($PWD). To
 168 override the default directory use the option --prefix=<dir>. More information
 169 can be obtained from the configure script by running it with option --help.
 170 All binary libraries will be installed under <prefix>/lib.
 171 If the directory is equal to $ALICE_ROOT, the libraries will be installed under
 172 <prefix>/lib/tgt_<arch> as used for AliRoot. This is a custom extension in
 173 order to adapt to the specific AliRoot installation directories.
 174
 175 You might need to specify the installation path of the ALICE HLT component
 176 framework during packge configuration. This can be done by the option
 177 --with-hltbase.
 178 Please follow correctly the installation procedure of the framework package.
 179
 180 Note: You can have several build directories with different configure options,
 181 (e.g. AliRoot versions) but using the same source code.
 182
 183 If you need further information on the GNU build system, execute from the
 184 top directory:
 185 ./configure --help | less
 186
 187 6. Code Development
 188 ===================
 189 Once you are finnished with the build of the package, you can think about
 190 changing the code. The packge contains three example components:
 191 - AliHLTDummyComponent: a real component which copies data from the input
 192   to the output
 193 - AliHLTSampleComponent1/2: two dummy components which just demonstrate
 194   how several components can be implemented in one library
 195 Each of the components has aheader file '<component>.h' and a source code
 196 file '<component>.cxx
 197
 198 Leave your build directory and go back to the top directory where you can find
 199 the source code as well as the Makefile template Makefile.am. Choose a new
 200 name of your library (the tutorial uses AliHLTTest) and follow the instructions
 201 5 to 8 of Part A (embedded case).
 202
 203 When you are done with this, you can build the library by typing 'make' in your
 204 build directory, and install it by make install.
 205
 206 7. Documentation
 207 ================
 208 NOTE: DOXYGEN GENERATED DOCUMENTATION WILL BE ADDED SOON !!!
 209 Documentation is generated from the source code at compile time if
 210 doxygen is installed on the machine. From the build directory, open
 211 doc/html/index.html with a web browser.
 212
 213 A wiki with detailed information is set up at
 214 http://www.kip.uni-heidelberg.de/wiki/HLT
 215
 216 8. Reporting bugs/Asking for support
 217 ====================================
 218 Please include the following information into your request:
 219 - config.log from your build directory
 220 - output of the make process. Note: Redirect BOTH the stdout and stderr
 221   channel to a log file. Redirection depends on the shell you are using:
 222     bash: make 2>&1 | tee make.log
 223     csh: make |& tee make.log
 224   The 'tee' command just duplicates the output.
 225 - history of the commands you are using for compilation
 226   history > history.log
 227
 228 9. Committing to the AliRoot CVS
 229 ================================
 230 At some point you might want to add the library to the AliRoot HLT module.
 231 Please contact Matthias.Richter@ift.uib.no and send a stable version as a
 232 tar archive.