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
  84 External headers). By default the Makefile.flat will look in
  85 $ALICE_ROOT, $ALICE_ROOT/MODULE (in this case $ALICE_ROOT/STEER),
  86 $ROOTSYS/include and in $ALICE_ROOT/include. If more include
  87 directories is needed it can be specified with the variable
  88 EINCLUDE. *DO NOT* put the -I flag it will be put automatically, just
  89 write the name of the directory. To have extra parameters passed to
  90 the compiler (like macro defines) use the variable EDEFINE (see
  91 libAliGeant4 for an example).
  92
  93 If the package exports any header files fo use by other libraries it can be put
  94 in the variable EXPORT. These files will be copied to
  95 $ALICE_ROOT/include and can be used by other libraries without directly
  96 including this module.
  97
  98 If a root dictionary file is used it can be specified with
  99
 100 DHDR:= STEERLinkdef.h
 101
 102 This will be processed with rootcint with all the header-files
 103 (specified in HDRS), and default cint includedir (set in CINTFLAGS)
 104 plus the directories specified in EINCLUDE
 105
 106 By default all libraries are linked against libraries specified in
 107 SHLIB and binaries against LIBS. If desired extra libraries can be
 108 specified with the ELIBS variable. *DO NOT* specify the -l flag, just
 109 write the library like
 110
 111 ELIBS:= CONTAINERS
 112
 113 this will be translated into -lCONTAINERS
 114
 115 Extra library directories can be specified with ELIBSDIR
 116
 117 If very special compilation flags is needed it can be specified with
 118 the three variables:
 119
 120 PACKFFLAGS:=
 121 PACKCXXFLAGS:=
 122 PACKCFLAGS:=
 123
 124 *WARNING* if these flags are set, the default FFLAGS,CXXFLAGS and CFLAGS
 125  will be overwritten. Normally they  will be used like this:
 126
 127 PACKCXXFLAGS:= $(filter-out -O%,CXXFLAGS)
 128
 129 This will set the C++ compiler-flags to the default ones, but without
 130 optimisation.
 131
 132 ** LIST OF Variables in .pkg files **
 133
 134 SRCS:=
 135 HDRS:=
 136 FSRCS:=
 137 DHDR:=
 138 CSRCS:=
 139 CHDRS:=
 140 EINCLUDE:=
 141 ELIBS:=
 142 ELIBSDIR:=
 143 EDEFINE:=
 144 PACKFFLAGS:=
 145 PACKCXXFLAGS:=
 146 PACKCFLAGS:=
 147 EXPORT:=
 148 EHDRS:=
 149
 150
 151 ** ADDING NEW DIRECTORIES **
 152
 153 When adding a new direcotry you must make a new .pkg file. If your
 154 library is going to be libEXAMPLE.so then make a new file called
 155 libEXAMPLE.pkg in the new direcotry. Now you need to add this
 156 direcotry to the Makefile.flat. Add it to the MODULES variable.
 157 A last step is to edit the build/module.dep file. Add a line like
 158 this:
 159
 160 NEWDIR/module.mk: libEXAMPLE.pkg
 161
 162 Please let the module.mk file depend on all .pkg files in the new
 163 directory. If you want aliroot to be linked against it, then edit
 164 ALIROOT/binaliroot.pkg and add you new lirbrary to the ELIBS variable.
 165
 166