This commit was generated by cvs2svn to compensate for changes in r165,
[u/mrichter/AliRoot.git] / RALICE / doc.txt
CommitLineData
d88f97cc 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
4This RALICE cmz file is an attempt to provide an Object Oriented framework,
5consisting of C++ classes, in which event reconstruction of the ALICE
6detector data can be performed.
7In switching to Object Oriented programming, I myself have started to
8perform the WA93 and WA98 data analysis within the ROOT [1] framework.
9Having seen the great advantages of this system I have started to make my
10C++ classes more general in order to use them as an onset for an ALICE
11reconstruction (and physics analysis) framework.
12The RALICE package can be compiled on all platforms using the GNU G++
13compiler and the various classes can be used in standalone mode.
14However, running the programs within the ROOT framework greatly enlarges
15the analysis capabilities (e.g. histogramming, fitting, graphics etc...).
16In addition the high level of interactivity of the ROOT/CINT system allows
17program development without the time consuming compile/link/load/execute cycle,
18whereas also the ROOT tree output format provides a completely machine
19independent data format providing efficient and easy to use data access
20capable to cope with the most complex data analyses programs.
21
22Only the (proposed) C++ ANSI standard is used in the source code and as
23such is fully compatible with all standard C++ compilers as well as with
24the ROOT/CINT interpreting system.
25
26The comments in the source code are placed in the locations proposed
27in the ROOT manual pages [1] such that the automatic source code
28documentation system of ROOT can be used directly from the source code.
29This has turned out to be very convenient (time saving) and guarantees
30always updated documentation compatible with the current source code.
31
32Coding conventions :
33--------------------
34In order not to clash with the (class) names of the ROOT framework
35and (future) packages of other groups, a few rules concerning names
36of classes, (member)functions and variables have to be obeyed.
37The 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.
9610) Each class header should contain a short description of the class
97 functionality including some examples.
98
99General note :
100--------------
101Within the ALICE software pool it may happen that e.g. in simulation
102applications one wants to define for instance a Track class which
103contains as data members some additional information (e.g. which was
104the corresponding parent particle) compared to the AliTrack class.
105Since objects reconstructed from real data will always contain the
106minimal amount of information compared to e.g. objects from simulation,
107it is in the above case then necessary to introduce a new class
108AliSTrack (simulation track).
109Obviously such a newly defined object (AliSTrack) can be derived from
110the reconstruction object (AliTrack) and just have some data members
111and/or memberfunctions added to it.
112In such a way maximum flexibility is provided within every (future)
113ALICE project, whereas all produced data can always be analysed using
114the RALICE tools.
115In view of this it might even be preferred to impose as a convention
116for future projects to adopt a unique prefix for their specific classes.
117For example the prefixes "AliS" and "AliD" could be used to indicate
118the simulation and DAQ specific classes respectively.
119
120Installation :
121--------------
122The RALICE library can be automatically installed using the automatic CMZ
123installation procedure.
124
125Available installation modes :
126------------------------------
127cmz -install ralice --> GNU G++ loadable libralice.a
128cmz -install ralice shared --> GNU G++ loadable shared library ralice.sl
129cmz -install ralice root --> ROOT (G++ based) loadable library ralice.sl
130cmz -install ralice - msvc --> MSVC++ loadable library
131cmz -install ralice shared msvc --> MSVC++ loadable shared library ralice.dll
132cmz -install ralice root msvc --> ROOT (MSVC++ based) loadable library ralice.dll
133cmz -install ralice - hpcc --> HP CC loadable library
134cmz -install ralice shared hpcc --> HP CC loadable shared library ralice.sl
135cmz -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