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