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