- Replace MODULE_OBJECT with LDR_DATA_TABLE_ENTRY.
[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 if="${MP}" ifnot="${MP}" name="msvcrt" type="win32dll" extension=".dll" entrypoint="_DllMain@12" baseaddress="0x70000000" mangledsymbols="true" installbase="system32" installname="msvcrt.dll" usewrc="false" warnings="true" aliasof="module1">
111 ...
112 </module>
113
114 Attributes:
115 if - If the value is 1, then the module is enabled, otherwise it is disabled. A disabled module is not processed.
116 ifnot - If the value is 1, then the module is disabled, otherwise it is enabled. A disabled module is not processed.
117 name - Name of the module. Also the base name of the generated file if such file is generated for the particular module type.
118 type - Type of module. See below for an explanation of module types.
119 extension - Extension of the generated file if such file is generated for the particular module type.
120 entrypoint - Entrypoint symbol of the generated file if such file is generated for the particular module type.
121 baseaddress - Base address of the generated file if such file is generated for the particular module type.
122 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.
123 installbase - Base directory of the generated file in the installation directory. This attribute is optional.
124 installname - Name of generated file in the installation directory. This attribute is optional, but if not specified, the generated file is not copied to the installation directory.
125 usewrc - Use WRC to compile resources if true. If false, windres is used. This attribute is optional. If not specified, WRC will be used.
126 warnings - Error out if false and at least one warning is emitted during building of this module. This attribute is optional. If not specified, it is assumed to be false.
127 aliasof - Name of module that is aliased.
128 Value:
129 None.
130
131 Elements:
132 bootstrap, component, define, dependency, directory, file, if, importlibrary, include, invoke, library, property.
133
134
135 Module types
136 ------------
137 The module type determines the actions that is to be carried out to process the module. The defined module types are seen below:
138 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.
139 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.
140 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.
141 kernel - Builds ntoskrnl.exe. Default extension is .exe. Default entrypoint is _NtProcessStartup.
142 kernelmodedll - Builds a kernel-mode DLL. Default extension is .dll. Default entrypoint is _DriverEntry@8.
143 kernelmodedriver - Builds a kernel-mode driver. Default extension is .sys. Default entrypoint is _DriverEntry@8.
144 nativedll - Builds a native DLL. Default extension is .dll. Default entrypoint is _DllMainCRTStartup@12.
145 win32dll - Builds a Win32 DLL. Default extension is .dll. Default entrypoint is _DllMain@12.
146 win32cui - Builds a Win32 console executable. Default extension is .exe. Default entrypoint is _mainCRTStartup. The baseaddress module attribute is not applicable for this module type.
147 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.
148 bootloader - Builds a bootloader. The entrypoint, baseaddress, and mangledsymbols module attributes are not applicable for this module type.
149 bootsector - Builds one or more bootsector binaries. The entrypoint, baseaddress, and mangledsymbols module attributes are not applicable for this module type.
150 iso - Builds a bootable CD. The entrypoint, baseaddress, and mangledsymbols module attributes are not applicable for this module type.
151 test - Builds a testsuite. Default extension is .exe. Default entrypoint is _mainCRTStartup. The baseaddress module attribute is not applicable for this module type.
152 rpcserver - Generates and builds server code for an RPC interface. Default extension is .o. The entrypoint, baseaddress, and mangledsymbols module attributes are not applicable for this module type.
153 rpcclient - Generates and builds client code for an RPC interface. Default extension is .o. The entrypoint, baseaddress, and mangledsymbols module attributes are not applicable for this module type.
154 alias - Module is an alias for another module. This module type is the only module type for which the aliasof attribute is applicable. Only the module install functionality is aliased.
155
156
157 Bootstrap element
158 -----------------
159 A bootstrap element specifies that the generated file should be put on the bootable CD as a bootstrap file.
160
161 Syntax:
162 <bootstrap base="reactos" nameoncd="halmp.dll" />
163
164 Attributes:
165 base - Put file in this directory on the bootable CD. This attribute is optional.
166 nameoncd - Name of file on the bootable CD. This attribute is optional.
167
168 Value:
169 None.
170
171 Elements:
172 None.
173
174
175 CDFile element
176 --------------
177 A cdfile element specifies the name of a file that is to be put on the bootable CD.
178
179 Syntax:
180 <cdfile base="reactos" nameoncd="ReadMe.txt">ReadMe.txt</cdfile>
181
182 Attributes:
183 base - Put file in this directory on the bootable CD. This attribute is optional.
184 nameoncd - Name of file on the bootable CD. This attribute is optional.
185
186 Value:
187 Name of file.
188
189 Elements:
190 None.
191
192
193 Component element
194 -----------------
195 A component element specifies that imports from a library are to be stubbed so tests can be run without actually calling the functions in the library. This element can only be used for modules of type test.
196
197 Syntax:
198 <component name="ntdll.dll">
199 ...
200 </component>
201
202 Attributes:
203 name - Name of library.
204
205 Value:
206 None.
207
208 Elements:
209 Symbol.
210
211
212 Symbol element
213 --------------
214 A symbol element specifies an imported function from a library that is to be stubbed so tests can be run without actually calling the function in the library.
215
216 Syntax:
217 <symbol newname="RtlAllocateHeap">HeapAlloc@12</symbol>
218
219 Attributes:
220 newname - New name of symbol. This attribute is optional.
221
222 Value:
223 Name of symbol.
224
225 Elements:
226 None.
227
228
229 Define element
230 --------------
231 A define element specifies the name and (optionally) value of a define for the C/C++ compiler and resource compiler.
232
233 Syntax:
234 <define name="WINVER">0x501</define>
235
236 Attributes:
237 name - Name of define.
238
239 Value:
240 Value of define. The value is optional.
241
242 Elements:
243 None.
244
245
246 Dependency element
247 ------------------
248 A dependency element specifies the name of a module (usually of type buildtool) that is to be processed before the current module.
249
250 Syntax:
251 <dependency>OtherModule</dependency>
252
253 Attributes:
254 None.
255
256 Value:
257 Name of module.
258
259 Elements:
260 None.
261
262
263 Directory element
264 -----------------
265 A directory element specifies the name of a subdirectory.
266
267 Syntax:
268 <directory name="MyDirectory">
269 ...
270 </directory>
271
272 Attributes:
273 name - Name of directory.
274
275 Value:
276 None.
277
278 Elements:
279 cdfile, directory, file, if, property.
280
281
282 File element
283 ------------
284 A file element specifies the name of a file that is to be processed.
285
286 Syntax:
287 <file>MyFile.c</file>
288
289 Attributes:
290 None.
291
292 Value:
293 Name of file.
294
295 Elements:
296 None.
297
298
299 If element
300 ----------
301 An if element allows for conditional processing of other elements.
302
303 Syntax:
304 <if property="DBG" value="1">
305 ...
306 </if>
307
308 Attributes:
309 property - Name of the property that is to be evaluated.
310 value - Value to compare to the value of the property. If the property has the specified value, then the subelements are processed.
311
312 Value:
313 None.
314
315 Elements:
316 compilerflag, define, directory, file, if, include, property.
317
318
319 Importlibrary element
320 ---------------------
321 An importlibrary element specifies that an import library should be generated which other modules can use to link with the current module.
322
323 Syntax:
324 <importlibrary definition="MyModule.def" />
325
326 Attributes:
327 definition - Filename of definition file (.def) used to generate the import library. The filename is relative to the current module.
328
329 Value:
330 None.
331
332 Elements:
333 None.
334
335
336 Include element
337 ---------------
338 An include element specifies an include directory for the C/C++ compiler and resource compiler.
339
340 Syntax:
341 <include base="MyLibraryModule">include</include>
342
343 Attributes:
344 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.
345
346 Value:
347 Relative include directory.
348
349 Elements:
350 None.
351
352
353 Installfile element
354 -------------------
355 An installfile element specifies the name of a file that is to be installed when using 'make install'.
356
357 Syntax:
358 <installfile base="reactos" newname="ReadMe.txt">ReadMe.txt</installfile>
359
360 Attributes:
361 base - Put file in this directory within the install directory. This attribute is optional.
362 newname - Name of file within the install directory. This attribute is optional.
363
364 Value:
365 Name of file.
366
367 Elements:
368 None.
369
370
371 Invoke element
372 --------------
373 An invoke element specifies the name of a module which is to be executed before the current module is processed.
374
375 Syntax:
376 <invoke module="wmc">
377 <input>
378 <inputfile>ntoskrnl.mc</inputfile>
379 </input>
380 <output>
381 <outputfile switches="-H">../include/reactos/bugcodes.h</outputfile>
382 <outputfile switches="-o">bugcodes.rc</outputfile>
383 </output>
384 </invoke>
385
386 Attributes:
387 None.
388
389 Value:
390 Name of the module to execute.
391
392 Elements:
393 input, output.
394
395
396 Input element
397 -------------
398 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.
399
400 Attributes:
401 None.
402
403 Value:
404 None.
405
406 Elements:
407 inputfile.
408
409
410 Inputfile element
411 -----------------
412 An inputfile element specifies a filename that is to be passed as a parameter to a build tool.
413
414 Attributes:
415 switches - Switches that is passed as parameters just before the filename. This attribute is optional.
416
417 Value:
418 Name of file that is to be passed as a parameter to the build tool.
419
420 Elements:
421 None.
422
423
424 Output element
425 --------------
426 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.
427
428 Attributes:
429 None.
430
431 Value:
432 None.
433
434 Elements:
435 outputfile.
436
437
438 Outputfile element
439 ------------------
440 An outputfile element specifies a filename that is to be passed as a parameter to a build tool.
441
442 Attributes:
443 switches - Switches that is passed as parameters just before the filename. This attribute is optional.
444
445 Value:
446 Name of file that is to be passed as a parameter to the build tool.
447
448 Elements:
449 None.
450
451
452 Library
453 -------
454 An importlibrary element specifies the name of another module which is to be linked with the current module.
455
456 Syntax:
457 <library>MyLibraryModule</library>
458
459 Attributes:
460 None.
461
462 Value:
463 Name of the module to link with.
464
465 Elements:
466 None.
467
468
469 Property
470 --------
471 A property element specifies the name and value of a property that can be used for conditional processing of the xml build file.
472
473 Syntax:
474 <property name="mypropertyname" value="mypropertyvalue" />
475
476 Attributes:
477 name - Name of property.
478 value - Value of property.
479
480 Value:
481 None.
482
483 Elements:
484 None.