]> rtime.felk.cvut.cz Git - l4.git/blob - kernel/fiasco/src/README
update
[l4.git] / 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.