kernel/fiasco/src/README

   1  Fiasco's build system
   2
   3  Michael Hohmuth
   4
   5 Motivation
   6 ##########
   7
   8 My main goal when I designed Fiasco's build system was to allow for
   9 multiple configurations of the kernel, based on different
  10 implementations of the same interface, to coexist in multiple object
  11 directories.
  12
  13
  14 Configuration
  15 #############
  16
  17 Fiasco's build system consists of a number of configuration files, and
  18 it also makes use of the L4 source tree's global Make configuration
  19 file, l4/Makeconf.  All configuration files are written in Makefile
  20 language.
  21
  22 :l4/Makeconf:
  23   Global Make rules and search paths
  24
  25 :l4/kernel/fiasco/src/Makefile:
  26   ``Fiasco's build system'' rules
  27
  28 :l4/kernel/fiasco/src/Modules.in:
  29   Standard configuration for Fiasco
  30
  31 :<object directory>  /Modules:
  32   Current configuration for Fiasco
  33
  34 :l4/kernel/fiasco/src/Makerules.*:
  35   Make rules for each subsystem defined in Modules
  36
  37 :l4/kernel/fiasco/src/Makerules.local':
  38   (Optional) User-specific configuration files
  39
  40 :l4/Makeconf.local':
  41   (Optional) User-specific configuration files
  42
  43 (By default, the object directory is the main source directory,
  44 l4/kernel/fiasco/src/.  See the next section on how to use other
  45 object directories with custom configurations.)
  46
  47 Users configure the build system by creating a Modules file.  If no
  48 Modules file exists, the standard configuration Modules.in is copied
  49 to Modules.  The build system warns the user if (after a "cvs update")
  50 Modules.in is newer than Modules.
  51
  52 The Modules file defines a number of subsystems that should be built.
  53 For each subsystem, there must be a Makerules.<subsystem> file that
  54 defines rules for building the subsystem's targets.
  55
  56 In the remainder of this section, I describe by example the language
  57 used in Modules file and the contents of the Makerules.* files.
  58
  59 !SUBSYSTEMS = FOO BAR
  60 !       # Defines two subsystems, FOO and BAR.  This means that there
  61 !       # exist two files, Makerules.FOO and Makerules.BAR, that
  62 !       # contain rules on how to build the targets of these
  63 !       # subsystems.  These targets are defined later.
  64 !
  65 !### Definitions for subsystem FOO follow
  66 !
  67 !FOO = foo
  68 !       # Defines the main target of subsystem FOO: a file named
  69 !       # "foo".
  70 !
  71 !FOO_EXTRA = foo.man
  72 !       # (Optional) Defines more targets that should be built for
  73 !       # subsystem FOO.
  74 !
  75 !INTERFACES_FOO = foo1 foo2 foo3
  76 !       # (Optional) C++ modules for subsystem FOO (written in
  77 !       # `preprocess' format; see
  78 !       # <URL:http://os.inf.tu-dresden.de/~hohmuth/prj/preprocess/>)
  79 !       # Each module normally consists of one implementation file
  80 !       # such as foo1.cpp -- unless IMPL definitions such as the
  81 !       # following ones are given:
  82 !
  83 !foo2_IMPL = foo2 foo2-more
  84 !       # (Optional) C++ module foo2 is implemented in two files
  85 !       # foo2.cpp and foo2-more.cpp (instead of just foo2.cpp).  The
  86 !       # public header file generated from these implementation files
  87 !       # will be called foo2.h.
  88 !
  89 !foo3_IMPL = foo3-debug
  90 !       # (Optional) C++ module foo3 is implemented in foo3-debug.cpp,
  91 !       # not foo3.cpp.  The public header file generated from this
  92 !       # implementation file will be called foo3.h.
  93 !
  94 !CXXSRC_FOO = frob1.cc frob2.cc
  95 !       # (Optional) Additional C++ sources for subsystem FOO (not in
  96 !       # `preprocess' format)
  97 !
  98 !CSRC_FOO = frob3.c frob4.c
  99 !       # (Optional) Additional C sources for subsystem FOO
 100 !
 101 !ASSRC_FOO = frob5.S
 102 !       # (Optional) Additional assembly-language sources for
 103 !       # subsystem FOO
 104 !
 105 !OBJ_FOO = frob6.o
 106 !       # (Optional) Additional objects for subsystem FOO.  These
 107 !       # objects can be precompiled or generated using custom rules
 108 !       # in Makerules.FOO.
 109 !
 110 !NOPROFILE += frob2
 111 !       # (Optional) Basenames of objects that should not be compiled
 112 !       # with profiling options in profiling builds.
 113 !
 114 !NOOPT += frob3
 115 !       # (Optional) Basenames of objects that should not be compiled
 116 !       # with optimization options.
 117 !
 118 !PRIVATE_INCDIR += incdir
 119 !       # (Optional) Add incdir to the include path for all source
 120 !       # files.  (This feature is implemented by l4/Makeconf.)
 121 !
 122 !VPATH += foodir
 123 !       # (Optional) Add foodir to Make's source-file search
 124 !       # path.  (This feature is implemented internally by Make.)
 125 !
 126 !### Definitions for subsystem BAR follow
 127 !### (similar to FOO's definitions)
 128
 129
 130 The Makerules.FOO file usually contains just rules for linking the
 131 subsystem's targets.  Additionally, it must contain a rule
 132 "clean-FOO:" that cleans the object directory from files created by
 133 this configuration file.
 134
 135 It can access the following Make variables:
 136
 137 :'FOO', 'FOO_EXTRA':
 138   names of targets
 139
 140 :'OBJ_FOO':
 141   expanded to contain _all_ objects that will be created for subsystem FOO
 142
 143 :'BAR':
 144   targets of other subsystems
 145
 146
 147 Building in separate object directories
 148 #######################################
 149
 150 It is possible to configure multiple directories, each with its own
 151 Modules file, as separate object directories.  (This usage is
 152 supported only if the main source directory [the one containing
 153 Modules.in] is not also used as an object directory.)
 154
 155 To use a directory as an object directory, create in it a Makefile
 156 like this:
 157
 158 !srcdir = ..
 159 !
 160 !all:
 161 !
 162 !%:
 163 !          $(MAKE) -I $(srcdir) -f $(srcdir)/Makefile \
 164 !                  srcdir=$(srcdir) $@
 165
 166 Change the "srcdir" definition to point to the main source directory.
 167 You can then create custom Modules files (and custom source files and
 168 Makerules.* files) in each object directory.