warning fixed
[u/mrichter/AliRoot.git] / 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