source: trunk/examples/extended/persistency/P01/README@ 1337

     =========================================================
     Geant4 - an Object-Oriented Toolkit for Simulation in HEP
     =========================================================

                            ExampleP01
                            ----------

        General description
        -------------------

        This example shows how to store produced hits in a file using
the 'reflection' technique for persistency provided by the Reflex tool
also included in ROOT. The Reflex tool allows to create a dictionary
for the hit class, making then possible to save hit objects in a .root
file.  The general simulation setup (geometry, physics list, user
actions, etc...) is taken from ExampleN02.

The provided makefile produces two executables: 'persEx02' and
'readHits'. The first one is the actual Geant4 simulation application
with hits persistency. The second one, is just a simple 'reader' for
the produced .root file (you need to specify the name of the .root
file as argument).


        Building and running the example
        --------------------------------

        Before buidling and/or running the example you need to set the
following environment variables:

ROOTSYS - ROOT installation directory, it is required to run ROOT

GCCXMLPATH - gccxml binary directory, it is needed by ROOT for the
             dictionary generation
LD_LIBRARY_PATH - to include the ROOT library path and the path to
                  the dictionary library, i.e., for tcsh UNIX shell:
   setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:$ROOTSYS/lib:
                          $G4WORKDIR/tmp/$G4SYSTEM/exampleP01

The present version of the example requires that Geant4 headers are
installed in a single directory referenced by G4INCLUDE, as the standard
Geant4 installation procedure allows to do.

Once those variables are set (together with the standard Geant4 setup)
the example can be build by issueing the 'make' command. The final
executable file can be found in the usual directory:

$G4WORKDIR/bin/$G4SYSTEM/

Ten events will be generated and the produced hits will be stored in
the hits.root file. In addition, the hits will be printed out on the
screen so one can then compare them with the 'reader' output.
        
In order to read the persistified hits, a small 'reader' application
has been implemented. It is build by the same makefile as the example
executable. It can be run in the following way:

readHits hits.root

where the argument is the name of the file to be read. All the hits
saved in that file will be then read and printed on the screen.


        Remark on dictionary generation
        -------------------------------

        The dictionary is generated by ${ROOTSYS}/bin/genreflex
tool. The header file including headers for all the classes we want to
generate the dictionary for should be given as argument. Additionally,
a so called selection file (xml) should be provided (with -s flag) to
the genreflex tool (see the GNUmakefile). The role of this file is to
specify which classes we want to generate the dictionary for. The
selection file for our dictionary is in xml/ directory. Please refer
to genreflex manual for more details concerning the usage of that
tool.  

Concerning generating dictionary for the Geant4 objects, there are
also two technical remarks that need to be made here. The gccxml tool
(version 0.6.0_patch1) requires all the templated classes to be
explicitely used somewhere in the included header files in order for
the generation of the dictionary to be possible. For those templated
classes for which it is not the case, the problem can be very easily
solved by instaciating them in the headerfile which is given to
genreflex (see includes/Classes.h) as argument.  
The second remark is that there is an unfortunate clash of names as
far as G4String class is concerned. The header of G4String class
defines __G4String which happens to be the name of a variable used
within the generated dictionary code. The solution for that is to do
#undef __G4String in include/Classes.h file.