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