This README describes the procedure to create a customized component library for the ALICE HLT. Please send corrections/suggestions/bugreports to Matthias.Richter@ift.uib.no Part A describes a library embedded into the ALICE HLT build system Part B gives a recipe for using this package stand-alone Note: You can not mix the two alternatives since this would confuse aototools. Our suggestions: If you are developing anyway with the AliRoot HLT module choose alternative A. If you don't use the HLT module explicitly choose alternative B. If you have downloaded the 'alice-hlt-sample' package and want to build and modify it, go directly to Part B. =============================================================================== ===== ===== ===== Part A: The embedded case ===== ===== ===== =============================================================================== This describes how to create a new component library embedded into the ALICE HLT build system. We asume that you have a version of the AliRoot HLT module installed. The top level directory of the package is referred as 'topdir' from now on. 1. Choose a name for your library and the sub-folder: e.g. 'libAliHLTTest' in folder 'Test' 2. Go to the topdir: > cd 3. Copy the SampleLib folder as new 'Test' folder > cp -a SampleLib Test 4. Copy libAliHLTSample.pkg to libAliHLTTest.pkg > cp libAliHLTSample.pkg libAliHLTTest.pkg 5. Change dir to the new folder > cd Test 6. Open 'Makefile.am' with an editor This is the Makefile template for the autotools build system. In particular one defines the library to be built to the lib_LTLIBRARIES variable. Furthermore, source and header files have to be specified, but in our case this is done in the 'lib***.pkg file. By using such a file the library can later easily be added to AliRoot. 6.1. replace all strings 'AliHLTSample' with 'AliHLTTest' 7. Now, you can think about implementing a new component. The packge contains three example components: - AliHLTDummyComponent: a real component which copies data from the input to the output - AliHLTSampleComponent1/2: two dummy components which just demonstrate how several components can be implemented in one library Each of the components has a header file '.h' and a source code file '.cxx 7.1 Take the DummyComponent, copy the two files (to your component name): > cp AliHLTDummyComponent.h MyTestComponent.h > cp AliHLTDummyComponent.cxx MyTestComponent.cxx 7.2 Implement the required methods. A tutorial will be added to this package soon. A comprehensive online tutorial is available at http://www.kip.uni-heidelberg.de/wiki/HLT 8. Once you are finnished with the first code development, you have to add the new component files to the build system. Open 'libAliHLTTest.pkg' in the package topdir 8.1. Add all your source files to the SRCS variable, remove the files from the libAliHLTSample 8.2. Add all header files of classes which should be added to the ROOT dictionary to the CLASS_HDRS variable, remove the files from the libAliHLTSample 8.3. All other header files must be added to the HDRS variable, including the content of the CLASS_HEADERS 9. Now we just have to add our new library to the build system. 9.1 Open Makefile.am in the topdir and add 'Test' to the list of SUBDIRS 9.2 Open configure.ac in the topdir and add 'Test/Makefile' to the list of files to be created: AC_CONFIG_FILES at the end of configure.ac 10.Make sure that all files are saved. Now follow the instruction from the README in the topdir. In principle its enough to go to your build directory and simply type > make > make install =============================================================================== ===== ===== ===== Part B: Stand-alone package ===== ===== ===== =============================================================================== TOC === 1. Overview 2. Requirements 3. Setting up a version retrieved from CVS 4. Modifying a distributed package 5. Installation 6. Code development 7. Documentation 8. Reporting bugs/Asking for support 9. Committing to the AliRoot CVS 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. 2. Requirements =============== At this point you should have downloaded and unpacked a package with name alice-hlt-sample.tar.gz. If not, please download it from http://www.kip.uni-heidelberg.de/ti/HLT/software/download/alice-hlt-sample.tar.gz The following description refers to that package. 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, ...). The package also needs the ALICE HLT component framework. This is part of AliRoot from version v4-05-Release on. You can also download the package from http://www.kip.uni-heidelberg.de/wiki/HLT To set up a version retrieved from CVS, 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 CVS ========================================== 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. Go to the directory and run autoreconf -i -f Then continue with the package configuration described in the 'Installation' section. 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 Please notify the authors about bug fixes/corrections/extensions you made if you consider them worth to be merged into the project. Then continue with the package configuration described in the 'Installation' section. 5. Installation =============== Package build relies on the GNU triplet configure, make and make install. In order to keep the development directory clean, it is recommended to use a separate build directory. Please read the full section before you start. The build is in priciple done like mkdir build cd build ../configure make make install You should redirect the output of the make into a file. The default install directory is set to the current directory ($PWD). To override the default directory use the option --prefix=. More information can be obtained from the configure script by running it with option --help. All binary libraries will be installed under /lib. If the directory is equal to $ALICE_ROOT, the libraries will be installed under /lib/tgt_ as used for AliRoot. This is a custom extension in order to adapt to the specific AliRoot installation directories. You might need to specify the installation path of the ALICE HLT component framework during packge configuration. This can be done by the option --with-hltbase. Please follow correctly the installation procedure of the framework package. Note: You can have several build directories with different configure options, (e.g. AliRoot versions) but using the same source code. If you need further information on the GNU build system, execute from the top directory: ./configure --help | less 6. Code Development =================== Once you are finnished with the build of the package, you can think about changing the code. The packge contains three example components: - AliHLTDummyComponent: a real component which copies data from the input to the output - AliHLTSampleComponent1/2: two dummy components which just demonstrate how several components can be implemented in one library Each of the components has aheader file '.h' and a source code file '.cxx Leave your build directory and go back to the top directory where you can find the source code as well as the Makefile template Makefile.am. 1. Choose a new name of your library (the tutorial uses AliHLTTest) 2. Copy libAliHLTSample.pkg to libAliHLTTest.pkg > cp libAliHLTSample.pkg libAliHLTTest.pkg 3. follow the instructions 6 to 8 of Part A (embedded case). When you are done with this, you can build the library by typing 'make' in your build directory, and install it by make install. 7. Documentation ================ NOTE: DOXYGEN GENERATED DOCUMENTATION WILL BE ADDED SOON !!! Documentation is generated from the source code at compile time if doxygen is installed on the machine. From the build directory, open doc/html/index.html with a web browser. A wiki with detailed information is set up at http://www.kip.uni-heidelberg.de/wiki/HLT 8. Reporting bugs/Asking for support ==================================== Please include the following information into your 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: bash: make 2>&1 | tee make.log csh: make |& tee make.log The 'tee' command just duplicates the output. - history of the commands you are using for compilation history > history.log 9. Committing to the AliRoot CVS ================================ At some point you might want to add the library to the AliRoot HLT module. Please contact Matthias.Richter@ift.uib.no and send a stable version as a tar archive.