RALICE/doc.txt

   1 //*CMZ :  1.00/01 04/07/97  16.43.13  by  Nick van Eijndhoven (UU/CERN)
   2 //*-- Author :    Nick van Eijndhoven (UU/CERN)   04/07/97
   3
   4 This RALICE cmz file is an attempt to provide an Object Oriented framework,
   5 consisting of C++ classes, in which event reconstruction of the ALICE
   6 detector data can be performed.
   7 In switching to Object Oriented programming, I myself have started to
   8 perform the WA93 and WA98 data analysis within the ROOT [1] framework.
   9 Having seen the great advantages of this system I have started to make my
  10 C++ classes more general in order to use them as an onset for an ALICE
  11 reconstruction (and physics analysis) framework.
  12 The RALICE package can be compiled on all platforms using the GNU G++
  13 compiler and the various classes can be used in standalone mode.
  14 However, running the programs within the ROOT framework greatly enlarges
  15 the analysis capabilities (e.g. histogramming, fitting, graphics etc...).
  16 In addition the high level of interactivity of the ROOT/CINT system allows
  17 program development without the time consuming compile/link/load/execute cycle,
  18 whereas also the ROOT tree output format provides a completely machine
  19 independent data format providing efficient and easy to use data access
  20 capable to cope with the most complex data analyses programs.
  21
  22 Only the (proposed) C++ ANSI standard is used in the source code and as
  23 such is fully compatible with all standard C++ compilers as well as with
  24 the ROOT/CINT interpreting system.
  25
  26 The comments in the source code are placed in the locations proposed
  27 in the ROOT manual pages [1] such that the automatic source code
  28 documentation system of ROOT can be used directly from the source code.
  29 This has turned out to be very convenient (time saving) and guarantees
  30 always updated documentation compatible with the current source code.
  31
  32 Coding conventions :
  33 --------------------
  34 In order not to clash with the (class) names of the ROOT framework
  35 and (future) packages of other groups, a few rules concerning names
  36 of classes, (member)functions and variables have to be obeyed.
  37 The rules are the following :
  38
  39  1) Only (proposed) ANSI standard C++ is allowed, with an even stricter
  40     requirement that the code should compile without any warnings
  41     under the GNU g++, msvc++ and the native C++ compilers of HP
  42     and DECAlpha machines.
  43     This will assure the programs to run on all standard ALICE platforms.
  44  2) Class names start with "Ali" followed by an uppercase character,
  45     all other characters are lowercase.
  46     Example : AliCalorimeter
  47     In this way the RALICE class names will NEVER clash with the ones
  48     of ROOT whereas the probability of a clash with the class names of
  49     other group's code (e.g. ATLAS, CDF, PHENIX etc...) is minimised.
  50     To prevent name clashes within the various (future) ALICE packages,
  51     please refer to the general note at the end.
  52  3) Names of detector specific classes should start with "Ali" followed
  53     by the detector name in uppercase, all other characters are lowercase
  54     except the first character following the detector name, which has to
  55     be uppercase..
  56     Example : AliTPCSegment or AliPPCTiming.
  57     These detector specific classes should only be introduced when there
  58     is really a need for it.
  59     E.g. when a track segment of the TPC and ITS have a lot in common
  60     it would be better to introduce a general AliTracksegment class
  61     instead of AliTPCSegment and AliITSSegment classes.
  62  4) Class headers should be under the control of "#ifndef" and the name
  63     should consist of "CLASSNAME_H" (i.e. the classname in uppercase).
  64     Example : #ifndef ALITRACK_H
  65               #define ALITRACK_H
  66     In this way also the ifdefs will be unique and prevents the danger
  67     of having the name of an ifdef being the same as a Classname.
  68  5) The private area in the class header has to be defined as the last item.
  69     Macros, like the ROOT ClassDef() statement (if needed) must be put
  70     appear at the right location, i.e. just before the "};" of the
  71     class definition.
  72  6) Names of member functions should start with a capital character
  73     and should NOT contain underscores (which drop out with HTML).
  74     From the name it should be clear what the functionality is and
  75     capital characters should be used to indicate various "words".
  76     Example : AliTrack::Set3Momentum(float* p)
  77  7) Names of datamembers of a class should start with a lowercase "f"
  78     and the next character has to be uppercase.
  79     Example : float fEnergy
  80     This will allow directly identification of datamembers in the code.
  81     The names of all other local variables may be chosen freely by the
  82     author.
  83     Note : It is recommended to use only lowercase characters
  84            for local variables.
  85  8) Names of global variables should start with "gAli" and the next
  86     character has to be uppercase.
  87     Example : gAliRun
  88     This will allow directly identification of global variables in the
  89     code and will not clash with the existing ROOT globals like
  90     for instance gDirectory etc...
  91     Note : Usage of global variables should be avoided as much as
  92            possible. Most of the data transfer should go via the classes
  93            and their member functions (data hiding).
  94  9) Comments should be placed at the positions as outlined in the ROOT docs.
  95     This will enable the automatic HTML machinery of ROOT.
  96 10) Each class header should contain a short description of the class
  97     functionality including some examples.
  98
  99 General note :
 100 --------------
 101 Within the ALICE software pool it may happen that e.g. in simulation
 102 applications one wants to define for instance a Track class which
 103 contains as data members some additional information (e.g. which was
 104 the corresponding parent particle) compared to the AliTrack class.
 105 Since objects reconstructed from real data will always contain the
 106 minimal amount of information compared to e.g. objects from simulation,
 107 it is in the above case then necessary to introduce a new class
 108 AliSTrack (simulation track).
 109 Obviously such a newly defined object (AliSTrack) can be derived from
 110 the reconstruction object (AliTrack) and just have some data members
 111 and/or memberfunctions added to it.
 112 In such a way maximum flexibility is provided within every (future)
 113 ALICE project, whereas all produced data can always be analysed using
 114 the RALICE tools.
 115 In view of this it might even be preferred to impose as a convention
 116 for future projects to adopt a unique prefix for their specific classes.
 117 For example the prefixes "AliS" and "AliD" could be used to indicate
 118 the simulation and DAQ specific classes respectively.
 119
 120 Installation :
 121 --------------
 122 The RALICE library can be automatically installed using the automatic CMZ
 123 installation procedure.
 124
 125 Available installation modes :
 126 ------------------------------
 127 cmz -install ralice              --> GNU G++ loadable libralice.a
 128 cmz -install ralice shared       --> GNU G++ loadable shared library ralice.sl
 129 cmz -install ralice root         --> ROOT (G++ based) loadable library ralice.sl
 130 cmz -install ralice   -    msvc  --> MSVC++ loadable library
 131 cmz -install ralice shared msvc  --> MSVC++ loadable shared library ralice.dll
 132 cmz -install ralice root   msvc  --> ROOT (MSVC++ based) loadable library ralice.dll
 133 cmz -install ralice   -    hpcc  --> HP CC loadable library
 134 cmz -install ralice shared hpcc  --> HP CC loadable shared library ralice.sl
 135 cmz -install ralice root   hpcc  --> ROOT (HP CC based) loadable library ralice.sl
 136
 137
 138 [1] http://root.cern.ch
 139
 140
 141
 142                                            Nick van Eijndhoven
 143                                            Subatomic Physics Dept.
 144                                            Utrecht University/NIKHEF
 145                                            P.O. Box 80.000
 146                                            NL-3508 TA Utrecht
 147                                            The Netherlands
 148                                            Email: nick@phys.uu.nl
 149                                            WWW: http://www.phys.uu.nl/~nick