ec6992cb4329fab416accd1c4f7e45e35d6204f0
[u/mrichter/AliRoot.git] / build / README
1 ****************************************************
2 *                                                   *
3 *         Flat makefile for AliRoot                 *
4 *                                                   *
5 *   This README describes how to use the             *
6 *   Makefile.flat for AliRoot                       *
7 *                                                   *
8 *   Author: Jan-Erik Revsbech <revsbech@fys.ku.dk>  *
9 *****************************************************
10
11 ** RUNNING **
12
13 Use these makefile with
14
15 make -f Makefile.flat
16
17
18 ** DESCRIPTION **
19
20 As the name suggests this is a flat makefile structure for
21 Aliroot. That means that there is only one makefile for aliroot and
22 not as before on makefile for every package. This way the
23 Makefile.flat knows about all dependencies and does not have to
24 recursively go through all directories several time.
25
26 Instead of having a makefile for each package, all the packages have
27 one module.mk file. This file contains information about the package.
28 Each package can contain several libraries
29 and binaries to be made. The module.mk file is automatically created
30 by a script, by using a template. The script must know about what
31 files each desired library or binary consists of. This is specified
32 in .pkg files. For example a module in directory STEER could make two
33 libraries libSTEER and libSTEERDummy.so and one binary called
34 STEERTest. In this example the directory STEER would contain three
35 files: libSTEER.pkg, libSTEERDummy.pkg and binSTEERTest.pkg. These
36 files will contain information about which source and header files the
37 library or binary consists of and specific options. See the section package file for
38 further information about what the pkg files contains.
39 The libraries are put in the directory LIBPATH, set in Makefile.flat
40 and binaries in BINPATH. These directories are set to
41 bin/tgt_$ALICE_TARGET and lib/tgt_$ALICE_TARGET respectively.
42 In this example we would produce three outoutfiles called libSTEER.so,
43 libSTEERDummy.so and STEERTest. These names are created from the name
44 of the .pkg files!!
45
46 The module.mk files will be automatically generated by Makefile.flat
47 if they do not exist. Also the build/moudle.dep contains a list of
48 dependencies for the module.mk files. This means that for the above
49 example the build/module.dep would contain a line like this:
50
51 STEER/module.mk:   libSTEER.pkg libSTEERDummy.pkg binSTEERTest.pkg
52
53 In this way if a change is made to one of the package-files (a
54 source-file is added or something), the module.mk file will be re-generated.
55
56 The Makefile.flat has in the start a variable called MODULES, this
57 variables lists all the subdirectories to look for module.mk files.
58
59 ** PACKAGE FILES **
60
61 The .pkg files uses make syntax, so be careful with tabs!!!
62
63 As a minimum all package files must specify which source-code files and
64 headers it consist of. This is done with the variables
65 HDRS,SRCS,FSRCS,CSRCS which is Heades, C++ sources, Fortran sources
66 and C-source-files.
67
68 For example the Package libSTEERDummy.pkg could consist of 
69
70 SRCS:= AliSTEERDummy.cxx
71
72 FSRCS:= AliSTEERFortranRoutines.f
73
74 HDRS:= AliSTEERDummy.cxx
75
76 Since the pkg files use make syntax HDRS can also be specified as
77
78 HDRS:=$(SRCS:.cxx=.h)
79
80 which is useful if there is a lot of files.
81
82 If the library (or binary) uses include files in other directories
83 than its own it should be specified in the variable EHDRS (for External
84 headers). By default the Makefile.flat will look in $ALICE_ROOT,
85 $ALICE_ROOT/MODULE (in this case $ALICE_ROOT/STEER), $ROOTSYS/inlude
86 and in $ALICE_ROOT/include. If more include directories is needed it
87 can be specified with the variable EINCLUDE. *DO NOT* put the -I flag
88 it will be put automatically, just write the name of the directory.
89
90 If the package exports any header files fo use by other libraries it can be put
91 in the variable EXPORT. These files will be copied to   
92 $ALICE_ROOT/include and can be used by other libraries without directly
93 including this module.
94
95 If a root dictionary file is used it can be specified with
96
97 DHDR:= STEERLinkdef.h
98
99 This will be processed with rootcint with all the header-files
100 (specified in HDRS), and default cint includedir (set in CINTFLAGS)
101 plus the directories specified in EINCLUDE
102
103 By default all libraries are linked against libraries specified in
104 SHLIB and binaries against LIBS. If desired extra libraries can be
105 specified with the ELIBS variable. *DO NOT* specify the -l flag, just
106 write the library like
107
108 ELIBS:= CONTAINERS
109
110 this will be translated into -lCONTAINERS
111
112 Extra library directories can be specified with ELIBSDIR
113
114 If very special compilation flags is needed it can be specified with
115 the three variables:
116
117 PACKFFLAGS:=
118 PACKCXXFLAGS:=
119 PACKCFLAGS:=
120
121 *WARNING* if these flags are set, the default FFLAGS,CXXFLAGS and CFLAGS
122  will be overwritten. Normally they  will be used like this:
123
124 PACKCXXFLAGS:= $(filter-out -O%,CXXFLAGS) 
125
126 This will set the C++ compiler-flags to the default ones, but without
127 optimisation.
128
129 ** LIST OF Variables in .pkg files **
130
131 SRCS:=
132 HDRS:=
133 FSRCS:=
134 DHDR:=
135 CSRCS:=
136 CHDRS:=
137 EINCLUDE:=
138 ELIBS:=
139 ELIBSDIR:=
140 PACKFFLAGS:=
141 PACKCXXFLAGS:=
142 PACKCFLAGS:=
143 EXPORT:=
144 EHDRS:=
145
146
147 ** ADDING NEW DIRECTORIES **
148
149 When adding a new direcotry you must make a new .pkg file. If your
150 library is going to be libEXAMPLE.so then make a new file called
151 libEXAMPLE.pkg in the new direcotry. Now you need to add this
152 direcotry to the Makefile.flat. Add it to the MODULES variable.
153 A last step is to edit the build/module.dep file. Add a line like
154 this:
155
156 NEWDIR/module.mk: libEXAMPLE.pkg
157
158 Please let the module.mk file depend on all .pkg files in the new
159 directory. If you want aliroot to be linked against it, then edit
160 ALIROOT/binaliroot.pkg and add you new lirbrary to the ELIBS variable.
161
162