provide OCDB URI as macro argument
[u/mrichter/AliRoot.git] / HLT / README
index b9eb8b7..8af0689 100644 (file)
@@ -1,6 +1,9 @@
 Package: ALICE HLT
 
-This package implements the ALICE High Level Trigger framework.
+This package implements the ALICE High Level Trigger analysis framework
+and analysis component libraries. All files are property of and copyright
+by the ALICE HLT Project unless stated differently.
+
 All contributions are under the terms of the 
 GNU General Public License as published by the Free Software 
 Foundation. Also see files AUTHORS and THANKS.
@@ -8,35 +11,76 @@ Foundation. Also see files AUTHORS and THANKS.
 This packages is maintained by Matthias.Richter@ift.uib.no
 Comments, bug reports, suggestions welcome! 
 
-Overview
-========
-This package provides is a compilation of shared libraries of the ALICE
-HLT project. 
-- BASE: The base library (libHLTbase.so) provides the common interface for HLT 
-processing components, the binding into the ALICE offline project AliRoot
-and a pure C interface to the HLT on-line framework (Publisher/Subscriber
-framework)
-- SampleLib: The sample library contains examples for component 
-implementation and a tutorial.
-- TPCLib: The HLT code for the TPC
-
-Setting up a version retrieved from CVS
-=======================================
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
++ TOC
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
++ 1. Overview
++ 2. Requirements
++ 3. Setting up a version retrieved from SVN
++ 4. Modifying a distributed package
++ 5. Installation
++ 6. Documentation
++ 7. Further information
++ 8. Reporting bugs/Asking for support
++ 9. Committing to the AliRoot SVN
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+1. Overview
+===========
+This package provides a compilation of shared libraries of the ALICE
+HLT project and is intended for stand-alone compilation, i.e. not as part 
+of the AliRoot compilation. 
+
+ - \b BASE: The base library (libHLTbase.so) provides the common interface for
+   HLT processing components, the binding into the ALICE offline project
+   AliRoot and a pure C interface to the HLT on-line framework 
+   (Publisher/Subscriber framework)
+
+ - \b SampleLib: The sample library contains examples for component 
+   implementation and a tutorial.
+
+ - \b TPCLib: The HLT code for the TPC
+ - \b TPCLib/OnlineDisplay: HLT visualization code for the TPC
+
+ - \b PHOS: The HLT code for PHOS
+
+ - \b TRD: The HLT code for TRD
+
+ - \b MUON: The HLT code for MUON
+
+2. Requirements
+===============
+The package needs both ROOT and AliRoot. Both must be set up in the
+usual way (ROOTSYS, ALICE_ROOT, library locations evtl. specified in
+LD_LIBRARY_PATH, ...). Actually, the BASE and SampleLib modules are
+not dependend on AliRoot. The TPCLib does.
+
+To set up a version retrieved from SVN, autoconf 2.57, automake 1.6
+,and libtool 1.4 or higher versions are required. Thats the versions
+which come with the Scientific Linux CERN 3. The same applies if
+you want to change the Makefiles.
+
+If your GNU build tools are too old, ask the maintainers for a distributed
+package.  
+
+3. Setting up a version retrieved from SVN
+==========================================
 Skip this section if you have started from the tar ball.
 
-A version checked out from CVS requires a few steps to set up the Makefiles
-and to set some links which are related to the CVS structure at the IFT.
+A version checked out from SVN requires a few steps to set up the Makefiles.
 Go to the directory and run
-autoreconf -i -f
+
+  autoreconf -i -f
 
 Then continue with the package configuration described in the 'Installation'
 section.
 
-Modifying a distributed package
-===============================
+4. Modifying a distributed package
+==================================
 If you are going the modify a distributed package you might need to re-make 
 the GNU build system by running
- autoreconf -f -i
+
+  autoreconf -f -i
 
 Please notify the authors about bug fixes/corrections/extensions you made if
 you consider them worth to be merged into the project.
@@ -44,11 +88,19 @@ you consider them worth to be merged into the project.
 Then continue with the package configuration described in the 'Installation'
 section.
 
-Installation
-============
+5. Installation
+===============
 Package build relies on the GNU triplet configure, make and make install.
-It is suggested to use a separate build directory, e.g. from the
-top directory do
+In order to keep the development directory clean, it is recommended to
+use a separate build directory. 
+
+\b NOTE: Autotools creates the Makefiles from templates. All \b changes have to
+be done to the \b Makefile.am templates.
+
+It is recommended to read the complete section before the build process.
+
+5.1 For the impatiant user
+--------------------------
 
   mkdir build
   cd build
@@ -56,22 +108,138 @@ top directory do
   make
   make install
 
-The default install directories are set to the current directory ($PWD). Try
+5.2 Installation directory
+--------------------------
+The default install directory is set to the current directory ($PWD). To
+override the default directory use the option 
+  --prefix=<dir>. 
+More information can be obtained from the configure script by running it with
+option --help. All binary libraries will be installed under
+  <prefix>/lib.
+
+If the directory is equal to $ALICE_ROOT, the libraries will be installed under
+  <prefix>/lib/tgt_<arch>
+as used for AliRoot. This is a custom extension in
+order to adapt to the specific AliRoot installation directories.
+
+5.3 For the AliRoot user
+------------------------
+To install all libraries in the AliRoot lib dir:
+
+  mkdir build
+  cd build
+  ../configure --prefix=$ALICE_ROOT
+  make
+  make install
+
+5.4 Package options
+-------------------
+Some important options (all options are on by default):
 
-To override the default prefix use
---prefix=<dir>           
+  --disable-sample           # disable compilation the sample library
+  --disable-util             # disable compilation the util library
+  --disable-tpc              # disable compilation the TPC library
+  --disable-phos             # disable compilation the PHOS library
+  --disable-trd              # disable compilation the TRD library
+  --disable-dimuon           # disable compilation the MUON library
+  --disable-aliroot-logging  # disable logging
+  --disable-doc                     # disable creation of doxygen documentation
+  --disable-strict           # disable strict coding conventions and compilation flags
 
-Some important options:
---enable-logging  # Enable/Disable logging (default enabled)
---enable-sample   # Compile the sample library
---enable-tpc      # Compile the TPC library
+
+All detector libraries (including sample and util lib) require AliRoot,
+compilation is disabled if no working AliRoot version was found. This can
+occur even if an AliRoot version is set up correctly since the configure
+script checks for the usability of the AliRoot libraries (mainly STEER and
+the ones it depends on). If new dependencies are introduced, the check
+might fail.
+
+Compilation of detector libraries can be forced by the switch
+
+  --enable-detector, e.g. --enable-phos
+
+Compilation can also be forced by typing 'make' in the detector
+sub-directory.
+Debugging (default disabled)
+
+  --enable-debug             # enable debugging: symbols & messages
+
+Optimization (default -O2)
+
+  --disable-optimization     # disable compiler optimization
+  --enable-optimization<=l>  # enable compiler optimization level l
+
+5.5 External packages
+---------------------
+PubSub framework: the TPC online display needs the HOMER interface, which
+is currently part of the PubSub framework. It is planned to integrate it
+into AliRoot.<br>
+If the TPC online display is not necessary one can skip this option.
+
+  --with-pubsub=<dir>        # the top dir of the HLT PubSub framework
+
+5.6 Final remarks/further information 
+-------------------------------------
+\b Note: You can have several build directories with different configure
+options, but using the same source code. 
 
 If you need further information on the GNU build system, execute from the 
 top directory:
-./configure --help | less
 
+  ./configure --help | less
+
+
+6. Documentation
+================
+Documentation is build as part of the build process if \b doxygen is installed.
+The documentation can be opended from the
+  doc/html/
+sub-folder of your build directory. E.g with a web browser like firefox
+(assuming you are in the build directory):<br>
+  firefox file://`pwd`/doc/html/index.html
+
+A special target can be used to make a tar ball out of the documentation (again
+provided you are in the build directory):<br>
+  (cd doc && make tar-ball)
+
+On-line documentation is available at
+  http://web.ift.uib.no/~kjeks/doc/alice-hlt/
 
-Further information
-===================
+7. Further information
+======================
 A wiki with detailed information is set up at
-http://www.kip.uni-heidelberg.de/wiki/HLT
+  http://www.kip.uni-heidelberg.de/wiki/HLT
+
+8. Reporting bugs/Asking for support
+====================================
+Please include the following information into your report/request:
+ - config.log from your build directory
+ - output of the make process. Note: Redirect BOTH the stdout and stderr
+   channel to a log file. Redirection depends on the shell you are using:     <br>
+    bash: make 2>&1 | tee make.log                                            <br>
+    csh: make |& tee make.log                                                 <br>
+   The 'tee' command just duplicates the output.
+ - history of the commands you are using for compilation
+   history > history.log
+
+9. Committing to the AliRoot SVN
+================================
+For development of HLT analysis code check out a HEAD version from the 
+repository and implement your code. 
+
+For committing do:
+ - 1. make sure that the code changes are correct                    <br><tt>
+      svn diff | less                                                </tt><br>
+      \b Remember to restore all temporary changes you made (e.g. log level)
+ - 2. svn update
+ - 3. correct merging conflicts
+ - 4. compile and test your code again
+ - 5. depending on where you changes are send the whole HLT module except the build
+      sub-directories or your HLT sub- directory to
+      Matthias.Richter@ift.uib.no
+      Please include a message/description for the check in
+ - 6. you will get a notification when the code is committed, right after that
+      you must either do another svn update or check out the complete module
+      again in order to have the right SVN information. Please check that your
+      code has been correctly committed.