reactos/tools/rbuild/doc/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" allowwarnings="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         allowwarnings - 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         autoregister, bootstrap, component, compilationunit, define, dependency, directory, file, if, importlibrary, include, invoke, library, linkerscript, 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 Autoregister element
 158 --------------------
 159 An autoregister element specifies that the generated executable should be registered in the registry during second stage setup.
 160
 161 Syntax:
 162         <autoregister infsection="OleControlDlls" type="Both" />
 163
 164 Attributes:
 165         infsection - Name of section in syssetup.inf.
 166         type - Type of registration. Can be either DllRegisterServer, DllInstall, or Both.
 167
 168 Value:
 169         None.
 170
 171 Elements:
 172         None.
 173
 174
 175 Bootstrap element
 176 -----------------
 177 A bootstrap element specifies that the generated file should be put on the bootable CD as a bootstrap file.
 178
 179 Syntax:
 180         <bootstrap base="reactos" nameoncd="halmp.dll" />
 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         None.
 188
 189 Elements:
 190         None.
 191
 192
 193 CDFile element
 194 --------------
 195 A cdfile element specifies the name of a file that is to be put on the bootable CD.
 196
 197 Syntax:
 198         <cdfile base="reactos" nameoncd="ReadMe.txt">ReadMe.txt</cdfile>
 199
 200 Attributes:
 201         base - Put file in this directory on the bootable CD. This attribute is optional.
 202         nameoncd - Name of file on the bootable CD. This attribute is optional.
 203
 204 Value:
 205         Name of file.
 206
 207 Elements:
 208         None.
 209
 210
 211 CompilationUnit element
 212 -----------------------
 213 A compilationunit element specifies that one or more source code files are to be compiled as a single compilation unit.
 214
 215 Syntax:
 216         <compilationunit name="kernel32.c">
 217                 ...
 218         </compilationunit>
 219
 220 Attributes:
 221         name - Name of generated source code file.
 222
 223 Value:
 224         None.
 225
 226 Elements:
 227         directory, file, if.
 228
 229
 230 Component element
 231 -----------------
 232 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.
 233
 234 Syntax:
 235         <component name="ntdll.dll">
 236                 ...
 237         </component>
 238
 239 Attributes:
 240         name - Name of library.
 241
 242 Value:
 243         None.
 244
 245 Elements:
 246         Symbol.
 247
 248
 249 Symbol element
 250 --------------
 251 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.
 252
 253 Syntax:
 254         <symbol newname="RtlAllocateHeap">HeapAlloc@12</symbol>
 255
 256 Attributes:
 257         newname - New name of symbol. This attribute is optional.
 258
 259 Value:
 260         Name of symbol.
 261
 262 Elements:
 263         None.
 264
 265
 266 Define element
 267 --------------
 268 A define element specifies the name and (optionally) value of a define for the C/C++ compiler and resource compiler.
 269
 270 Syntax:
 271         <define name="WINVER">0x501</define>
 272
 273 Attributes:
 274         name - Name of define.
 275
 276 Value:
 277         Value of define. The value is optional.
 278
 279 Elements:
 280         None.
 281
 282
 283 Dependency element
 284 ------------------
 285 A dependency element specifies the name of a module (usually of type buildtool) that is to be processed before the current module.
 286
 287 Syntax:
 288         <dependency>OtherModule</dependency>
 289
 290 Attributes:
 291         None.
 292
 293 Value:
 294         Name of module.
 295
 296 Elements:
 297         None.
 298
 299
 300 Directory element
 301 -----------------
 302 A directory element specifies the name of a subdirectory.
 303
 304 Syntax:
 305         <directory name="MyDirectory">
 306                 ...
 307         </directory>
 308
 309 Attributes:
 310         name - Name of directory.
 311
 312 Value:
 313         None.
 314
 315 Elements:
 316         cdfile, directory, file, if, property.
 317
 318
 319 File element
 320 ------------
 321 A file element specifies the name of a file that is to be processed.
 322
 323 Syntax:
 324         <file>MyFile.c</file>
 325
 326 Attributes:
 327         None.
 328
 329 Value:
 330         Name of file.
 331
 332 Elements:
 333         None.
 334
 335
 336 If element
 337 ----------
 338 An if element allows for conditional processing of other elements.
 339
 340 Syntax:
 341         <if property="DBG" value="1">
 342                 ...
 343         </if>
 344
 345 Attributes:
 346         property - Name of the property that is to be evaluated.
 347         value - Value to compare to the value of the property. If the property has the specified value, then the subelements are processed.
 348
 349 Value:
 350         None.
 351
 352 Elements:
 353         compilationunit, compilerflag, define, directory, file, if, include, property.
 354
 355
 356 Importlibrary element
 357 ---------------------
 358 An importlibrary element specifies that an import library should be generated which other modules can use to link with the current module.
 359
 360 Syntax:
 361         <importlibrary definition="MyModule.def" />
 362
 363 Attributes:
 364         definition - Filename of definition file (.def) used to generate the import library. The filename is relative to the current module.
 365
 366 Value:
 367         None.
 368
 369 Elements:
 370         None.
 371
 372
 373 Include element
 374 ---------------
 375 An include element specifies an include directory for the C/C++ compiler and resource compiler.
 376
 377 Syntax:
 378         <include base="MyLibraryModule">include</include>
 379
 380 Attributes:
 381         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.
 382
 383 Value:
 384         Relative include directory.
 385
 386 Elements:
 387         None.
 388
 389
 390 Installfile element
 391 -------------------
 392 An installfile element specifies the name of a file that is to be installed when using 'make install'.
 393
 394 Syntax:
 395         <installfile base="reactos" newname="ReadMe.txt">ReadMe.txt</installfile>
 396
 397 Attributes:
 398         base - Put file in this directory within the install directory. This attribute is optional.
 399         newname - Name of file within the install directory. This attribute is optional.
 400
 401 Value:
 402         Name of file.
 403
 404 Elements:
 405         None.
 406
 407
 408 Invoke element
 409 --------------
 410 An invoke element specifies the name of a module which is to be executed before the current module is processed.
 411
 412 Syntax:
 413         <invoke module="wmc">
 414                 <input>
 415                         <inputfile>ntoskrnl.mc</inputfile>
 416                 </input>
 417                 <output>
 418                         <outputfile switches="-H">../include/reactos/bugcodes.h</outputfile>
 419                         <outputfile switches="-o">bugcodes.rc</outputfile>
 420                 </output>
 421         </invoke>
 422
 423 Attributes:
 424         None.
 425
 426 Value:
 427         Name of the module to execute.
 428
 429 Elements:
 430         input, output.
 431
 432
 433 Input element
 434 -------------
 435 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.
 436
 437 Attributes:
 438         None.
 439
 440 Value:
 441         None.
 442
 443 Elements:
 444         inputfile.
 445
 446
 447 Inputfile element
 448 -----------------
 449 An inputfile element specifies a filename that is to be passed as a parameter to a build tool.
 450
 451 Attributes:
 452         switches - Switches that is passed as parameters just before the filename. This attribute is optional.
 453
 454 Value:
 455         Name of file that is to be passed as a parameter to the build tool.
 456
 457 Elements:
 458         None.
 459
 460
 461 Output element
 462 --------------
 463 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.
 464
 465 Attributes:
 466         None.
 467
 468 Value:
 469         None.
 470
 471 Elements:
 472         outputfile.
 473
 474
 475 Outputfile element
 476 ------------------
 477 An outputfile element specifies a filename that is to be passed as a parameter to a build tool.
 478
 479 Attributes:
 480         switches - Switches that is passed as parameters just before the filename. This attribute is optional.
 481
 482 Value:
 483         Name of file that is to be passed as a parameter to the build tool.
 484
 485 Elements:
 486         None.
 487
 488
 489 Library
 490 -------
 491 An importlibrary element specifies the name of another module which is to be linked with the current module.
 492
 493 Syntax:
 494         <library>MyLibraryModule</library>
 495
 496 Attributes:
 497         None.
 498
 499 Value:
 500         Name of the module to link with.
 501
 502 Elements:
 503         None.
 504
 505
 506 Linkerscript
 507 ------------
 508 A linkerscript element specifies the filename of a binutils linker script.
 509
 510 Syntax:
 511         <linkerscript base="mymodule">MyLinkerScript</linkerscript>
 512
 513 Attributes:
 514         base - Module which the value of this element is relative to. This attribute is optional. If left out, the linker script is relative to the position of the top-level xml build file.
 515
 516 Value:
 517         Relative linker script filename.
 518
 519 Elements:
 520         None.
 521
 522
 523 Property
 524 --------
 525 A property element specifies the name and value of a property that can be used for conditional processing of the xml build file.
 526
 527 Syntax:
 528         <property name="mypropertyname" value="mypropertyvalue" />
 529
 530 Attributes:
 531         name - Name of property.
 532         value - Value of property.
 533
 534 Value:
 535         None.
 536
 537 Elements:
 538         None.