Documented the compilation stages
[people/dverkamp/gpxe.git] / src / doc / build_sys.dox
1 /** @page build_sys Build system
2
3 @section overview Overview
4
5 Building an Etherboot image consists of two stages:
6
7   -# @ref compilation : Compiling all the source files into object files
8
9   -# @ref linking : Building a particular image from select object files
10
11 Though this is a remarkably complex process, it is important to note
12 that it all happens automatically.  Whatever state your build tree is
13 in, you can always type, for example
14
15 @code
16
17         make bin/rtl8139.dsk
18
19 @endcode
20
21 and know that you will get a floppy disk image with an RTL8139 driver
22 built from the current sources.
23
24 @section compilation Compilation
25
26 @subsection comp_general Overview
27
28 Each source file (a @c .c or a @c .S file) is compiled into a @c .o
29 file in the @c bin/ directory.  Etherboot makes minimal use of
30 conditional compilation (see @ref ifdef_harmful), and so you will find
31 that all objects get built, even the objects that correspond to
32 features that you are not intending to include in your image.  For
33 example, all network card drivers will be compiled even if you are
34 just building a ROM for a 3c509 card.  This is a deliberate design
35 decision; please do @b not attempt to "fix" the build system to avoid
36 doing this.
37
38 Source files are defined to be any @c .c or @c .S files found in a
39 directory listed in the Makefile variable #SRCDIRS.  You therefore do
40 @b not need to edit the Makefile just because you have added a new
41 source file (although you will need to edit the Makefile if you have
42 added a new source directory).  To see a list of all source
43 directories and source files that the build system currently knows
44 about, you can use the commands
45
46 @code
47
48         make srcdirs
49         make srcs
50
51 @endcode
52
53 Rules for compiling @c .c and @c .S files are defined in the Makefile
54 variables #RULE_c and #RULE_S.  Makefile rules are automatically
55 generated for each source file using these rules.  The generated rules
56 can be found in the @c .d file corresponding to each source file;
57 these are located in <tt>bin/deps/</tt>.  For example, the rules
58 generated for <tt>drivers/net/rtl8139.c</tt> can be found in
59 <tt>bin/deps/drivers/net/rtl8139.c.d</tt>.  These rules allow you to
60 type, for example
61
62 @code
63
64         make bin/rtl8139.o
65
66 @endcode
67
68 and have <tt>rtl8139.o</tt> be built from
69 <tt>drivers/net/rtl8139.c</tt> using the generic rule #RULE_c for
70 compiling @c .c files.
71
72 You can see the full list of object files that will be built using
73
74 @code
75
76         make bobjs
77
78 @endcode
79
80 @subsection comp_custom Customising compilation
81
82 The Makefile rules for a particular object can be customised to a
83 certain extent by defining the Makefile variable CFLAGS_@<object@>.
84 For example, if you were to set
85
86 @code
87
88         CFLAGS_rtl8139 = -DFOO
89
90 @endcode
91
92 then <tt>bin/rtl8139.o</tt> would be compiled with the additional
93 flags <tt>-DFOO</tt>.  To see the flags that will be used when
94 compiling a particular object, you can use e.g.
95
96 @code
97
98         make bin/rtl8139.flags
99
100 @endcode
101
102 If you need more flexibility than the CFLAGS_@<object@> mechanism
103 provides, then you can exclude source files from the automatic rule
104 generation process by listing them in the Makefile variable
105 #NON_AUTO_SRCS.  The command
106
107 @code
108
109         make autosrcs
110
111 @endcode
112
113 will show you which files are currently part of the automatic rule
114 generation process.
115
116 @subsection comp_multiobj Multiple objects
117
118 A single source file can be used to generate multiple object files.
119 This is used, for example, to generate the decompressing and the
120 non-decompressing prefixes from the same source files.
121
122 By default, a single object will be built from each source file.  To
123 override the list of objects for a source file, you can define the
124 Makefile variable OBJS_@<object@>.  For example, the
125 <tt>arch/i386/prefix/dskprefix.S</tt> source file is built into two
126 objects, <tt>bin/dskprefix.o</tt> and <tt>zdskprefix.o</tt> by
127 defining the Makefile variable
128
129 @code
130
131         OBJS_dskprefix = dskprefix zdskprefix
132
133 @endcode
134
135 Since there would be little point in building two identical objects,
136 customised compilation flags (see @ref comp_custom) are defined as
137
138 @code
139
140         CFLAGS_zdskprefix = -DCOMPRESS
141
142 @endcode
143
144 Thus, <tt>arch/i386/prefix/dskprefix.S</tt> is built into @c
145 dskprefix.o using the normal set of flags, and into @c zdskprefix.o
146 using the normal set of flags plus <tt>-DCOMPRESS</tt>.
147
148 @subsection comp_debug Special debugging targets
149
150 In addition to the basic rules #RULE_c and #RULE_S for compiling
151 source files into object files, there are various other rules that can
152 be useful for debugging.
153
154 @subsubsection comp_debug_c_to_c Preprocessed C
155
156 You can see the results of preprocessing a @c .c file (including the
157 per-object flags defined via CFLAGS_@<object@> if applicable) using
158 e.g.
159
160 @code
161
162         make bin/rtl8139.c
163
164 @endcode
165
166 and examining the resulting file (<tt>bin/rtl8139.c</tt> in this
167 case).
168
169 @subsubsection comp_debug_x_to_s Assembler
170
171 You can see the results of assembling a @c .c file, or of
172 preprocessing a @c .S file, using e.g.
173
174 @code
175
176         make bin/rtl8139.s
177         make bin/zdskprefix.s
178
179 @endcode
180
181 @subsubsection comp_debug_dbg Debugging-enabled targets
182
183 You can build targets with debug messages (DBG()) enabled using e.g.
184
185 @code
186
187         make bin/rtl8139.dbg.o
188         make bin/rtl8139.dbg2.o
189
190 @endcode
191
192 You will probably not need to use these targets directly, since a
193 mechanism exists to select debugging levels at link-time; see @ref
194 link_debug.
195
196 @section linking Linking
197
198 @subsection link_debug Debugging-enabled builds
199
200 */