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.