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