Import Geant4 8.1.0 source tree

examples/extended/persistency/P01/README

@@ -0,0 +1,92 @@
+
+     =========================================================
+     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.
+
+