121622c34b92db5b7d926f8852011645d9c28aed
[reactos.git] / reactos / tools / rbuild / rbuild.txt
1 ReactOS Build System Documentation
2 ==================================
3
4 Building ReactOS
5 ----------------
6 To generate GNU make makefiles and building ReactOS do the following:
7
8 1) Go to the top-level reactos directory
9 2) Run the command: mingw32-make
10
11 This will start building ReactOS.
12
13 To build a bootable CD run the following command:
14
15 mingw32-make bootcd
16
17 This will create ReactOS.iso in the top-level reactos directory.
18
19
20 Top-level XML Build File
21 ------------------------
22 The top-level xml build file (ReactOS.xml) is processed by rbuild. The following is an example of how it could look like:
23
24 <?xml version="1.0"?>
25 <!DOCTYPE project SYSTEM "tools/rbuild/project.dtd">
26 <project name="ReactOS" makefile="Makefile.auto" xmlns:xi="http://www.w3.org/2001/XInclude">
27 <xi:include href="config.xml">
28 <xi:fallback>
29 <xi:include href="config.template.xml" />
30 </xi:fallback>
31 </xi:include>
32
33 <define name="_M_IX86" />
34 <if property="DBG" value="1">
35 <define name="DBG" value="1" />
36 <property name="DBG_OR_KDBG" value="true" />
37 </if>
38
39 <include base="ReactOS">include</include>
40
41 <directory name="boot">
42 <xi:include href="boot/boot.xml" />
43 </directory>
44
45 <module name="bootcd" type="iso">
46 </module>
47 </project>
48
49
50 xi:include
51 ----------
52 It is possible to split an xml build file over several files. The include element in the xi namespace is used to accomplish this.
53
54 Syntax:
55 <xi:include href="config.xml">
56 <xi:fallback>
57 <xi:include href="config.template.xml" />
58 </xi:fallback>
59 </xi:include>
60
61 Attributes:
62 href - Name of xml build file to include. The filename is relative to the location of the current xml build file.
63
64 Value:
65 None.
66
67 Elements:
68 xi:fallback
69
70
71 xi:fallback
72 -----------
73 This element is used to provide the name of an alternate file that is to be included if the first include file did not exists.
74
75 Attributes:
76 None.
77
78 Value:
79 None.
80
81 Elements:
82 xi:include.
83
84
85 Project element
86 ---------------
87 There can be one project per top-level XML build file. A project can only be defined in a top-level xml build file.
88
89 Syntax:
90 <project name="ReactOS" makefile="Makefile.auto" xmlns:xi="http://www.w3.org/2001/XInclude">
91 ...
92 </project>
93
94 Attributes:
95 name - Name of the project.
96 makefile - Filename of the GNU makefile that is to be created.
97
98 Value:
99 None.
100
101 Elements:
102 define, directory, if, include, module, property
103
104
105 Module element
106 --------------
107 There can be zero or more modules per xml build file.
108
109 Syntax:
110 <module name="msvcrt" type="win32dll" extension=".dll" entrypoint="_DllMain@12" baseaddress="0x70000000" mangledsymbols="true">
111 ...
112 </module>
113
114 Attributes:
115 name - Name of the module. Also the base name of the generated file if such file is generated for the particular module type.
116 type - Type of module. See below for an explanation of module types.
117 extension - Extension of the generated file if such file is generated for the particular module type.
118 entrypoint - Entrypoint symbol of the generated file if such file is generated for the particular module type.
119 baseaddress - Base address of the generated file if such file is generated for the particular module type.
120 mangledsymbols - Controls wether or not to pass --kill-at to dlltool. If this attribute has the value false then --kill-at is passed to dlltool. If the value is true, then --kill-at is not passed to dlltool. If the generated file exports C++ classes then this need to be true.
121
122 Value:
123 None.
124
125 Elements:
126 define, dependency, directory, file, if, importlibrary, include, invoke, library, property.
127
128
129 Module types
130 ------------
131 The module type determines the actions that is to be carried out to process the module. The defined module types are seen below:
132 buildtool - Builds a tool that can be run (invoked) when building ReactOS. Default extension is .exe when building on Windows and nothing when building on Linux. The entrypoint, baseaddress, and mangledsymbols module attributes are not applicable for this module type.
133 staticlibrary - Builds a static library containing object files that can be linked together with other modules. Default extension is .a. The entrypoint, baseaddress, and mangledsymbols module attributes are not applicable for this module type.
134 objectlibrary - Builds object files that can be linked together with other modules. Default extension is .o. The entrypoint, baseaddress, and mangledsymbols module attributes are not applicable for this module type.
135 kernel - Builds ntoskrnl.exe. Default extension is .exe. Default entrypoint is _NtProcessStartup.
136 kernelmodedll - Builds a kernel-mode DLL. Default extension is .dll. Default entrypoint is _DriverEntry@8.
137 kernelmodedriver - Builds a kernel-mode driver. Default extension is .sys. Default entrypoint is _DriverEntry@8.
138 nativedll - Builds a native DLL. Default extension is .dll. Default entrypoint is _DllMainCRTStartup@12.
139 win32dll - Builds a Win32 DLL. Default extension is .dll. Default entrypoint is _DllMain@12.
140 win32gui - Builds a Win32 GUI executable. Default extension is .exe. Default entrypoint is _WinMainCRTStartup. The baseaddress module attribute is not applicable for this module type.
141 bootloader - Builds a bootloader. The entrypoint, baseaddress, and mangledsymbols module attributes are not applicable for this module type.
142 bootsector - Builds one or more bootsector binaries. The entrypoint, baseaddress, and mangledsymbols module attributes are not applicable for this module type.
143 iso - Builds a bootable CD. The entrypoint, baseaddress, and mangledsymbols module attributes are not applicable for this module type.
144
145
146 Define element
147 --------------
148 A define element specifies the name and (optionally) value of a define for the C/C++ compiler and resource compiler.
149
150 Syntax:
151 <define name="WINVER">0x501</define>
152
153 Attributes:
154 name - Name of define.
155
156 Value:
157 Value of define. The value is optional.
158
159 Elements:
160 None.
161
162
163 Dependency element
164 ------------------
165 A dependency element specifies the name of a module (usually of type buildtool) that is to be processed before the current module.
166
167 Syntax:
168 <dependency>OtherModule</dependency>
169
170 Attributes:
171 None.
172
173 Value:
174 Name of module.
175
176 Elements:
177 None.
178
179
180 Directory element
181 -----------------
182 A directory element specifies the name of a subdirectory.
183
184 Syntax:
185 <directory name="MyDirectory">
186 ...
187 </directory>
188
189 Attributes:
190 name - Name of directory.
191
192 Value:
193 None.
194
195 Elements:
196 directory, file, if, property.
197
198
199 File element
200 ------------
201 A file element specifies the name of a file that is to be processed.
202
203 Syntax:
204 <file>MyFile.c</file>
205
206 Attributes:
207 None.
208
209 Value:
210 Name of file.
211
212 Elements:
213 None.
214
215
216 If element
217 ----------
218 An if element allows for conditional processing of other elements.
219
220 Syntax:
221 <if property="DBG" value="1">
222 ...
223 </if>
224
225 Attributes:
226 property - Name of the property that is to be evaluated.
227 value - Value to compare to the value of the property. If the property has the specified value, then the subelements are processed.
228
229 Value:
230 None.
231
232 Elements:
233 define, directory, file, if, include, property.
234
235
236 Importlibrary element
237 ---------------------
238 An importlibrary element specifies that an import library should be generated which other modules can use to link with the current module.
239
240 Syntax:
241 <importlibrary definition="MyModule.def" />
242
243 Attributes:
244 definition - Filename of definition file (.def) used to generate the import library. The filename is relative to the current module.
245
246 Value:
247 None.
248
249 Elements:
250 None.
251
252
253 Include element
254 ---------------
255 An include element specifies an include directory for the C/C++ compiler and resource compiler.
256
257 Syntax:
258 <include base="MyLibraryModule">include</include>
259
260 Attributes:
261 base - Module or project which the value of this element is relative to. This attribute is optional. If left out, the include directory is relative to the position of the top-level xml build file.
262
263 Value:
264 Relative include directory.
265
266 Elements:
267 None.
268
269
270 Invoke element
271 --------------
272 An invoke element specifies the name of a module which is to be executed before the current module is processed.
273
274 Syntax:
275 <invoke module="wmc">
276 <input>
277 <inputfile>ntoskrnl.mc</inputfile>
278 </input>
279 <output>
280 <outputfile switches="-H">../include/reactos/bugcodes.h</outputfile>
281 <outputfile switches="-o">bugcodes.rc</outputfile>
282 </output>
283 </invoke>
284
285 Attributes:
286 None.
287
288 Value:
289 Name of the module to execute.
290
291 Elements:
292 input, output.
293
294
295 Input element
296 -------------
297 An input element specifies a group of filenames that is to be passed as parameters to a build tool. Input filename parameters are located after output filename parameters on the command line.
298
299 Attributes:
300 None.
301
302 Value:
303 None.
304
305 Elements:
306 inputfile.
307
308
309 Inputfile element
310 -----------------
311 An inputfile element specifies a filename that is to be passed as a parameter to a build tool.
312
313 Attributes:
314 switches - Switches that is passed as parameters just before the filename. This attribute is optional.
315
316 Value:
317 Name of file that is to be passed as a parameter to the build tool.
318
319 Elements:
320 None.
321
322
323 Output element
324 --------------
325 An output element specifies a group of filenames that is to be passed as parameters to a build tool. Output filename parameters are located before input filename parameters on the command line.
326
327 Attributes:
328 None.
329
330 Value:
331 None.
332
333 Elements:
334 outputfile.
335
336
337 Outputfile element
338 ------------------
339 An outputfile element specifies a filename that is to be passed as a parameter to a build tool.
340
341 Attributes:
342 switches - Switches that is passed as parameters just before the filename. This attribute is optional.
343
344 Value:
345 Name of file that is to be passed as a parameter to the build tool.
346
347 Elements:
348 None.
349
350
351 Library
352 -------
353 An importlibrary element specifies the name of another module which is to be linked with the current module.
354
355 Syntax:
356 <library>MyLibraryModule</library>
357
358 Attributes:
359 None.
360
361 Value:
362 Name of the module to link with.
363
364 Elements:
365 None.
366
367
368 Property
369 --------
370 A property element specifies the name and value of a property that can be used for conditional processing of the xml build file.
371
372 Syntax:
373 <property name="mypropertyname" value="mypropertyvalue" />
374
375 Attributes:
376 name - Name of property.
377 value - Value of property.
378
379 Value:
380 None.
381
382 Elements:
383 None.