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