# ReactOS Build System Documentation

$Id$
Casper
Hornstrup
Emanuele
Aliberti
2005

## Building ReactOS

### Building ReactOS

To generate GNU make makefiles and building ReactOS, do the following:

1. Go to the top-level `reactos` directory;

2. Run the command:

       mingw32-make

   This will start building ReactOS.

To build a bootable CD, run the following command:

    mingw32-make bootcd

This will create `ReactOS.iso` in the top-level `reactos` directory.

## How build directions are stored

XML files are used throughout the ReactOS source tree to drive the build system.

### Top-level XML Build File

The top-level XML build file (`ReactOS.rbuild`) is processed by `rbuild`. The following is an example of how it could look like:

    <?xml version="1.0"?>
    <!DOCTYPE project SYSTEM "tools/rbuild/project.dtd">
    <project name="ReactOS" makefile="Makefile.auto" xmlns:xi="http://www.w3.org/2001/XInclude">
      <xi:include href="config.rbuild">
        <xi:fallback>
          <xi:include href="config.template.rbuild" />
        </xi:fallback>
      </xi:include>

      <define name="_M_IX86" />
      <if property="DBG" value="1">
        <define name="DBG" value="1" />
        <property name="DBG_OR_KDBG" value="true" />
      </if>

      <include base="ReactOS">include</include>

      <directory name="boot">
        <xi:include href="boot/boot.rbuild" />
      </directory>

      <module name="bootcd" type="iso">
      </module>
    </project>

### XInclude

XML files used by `rbuild` are modular and use XInclude to include other chunks of XML in the top-level `ReactOS.rbuild` file. The namespace used by XInclude is `xi`.

#### xi:include

It is possible to split an XML build file over several files. The include element in the `xi` namespace is used to accomplish this.

##### Syntax

    <xi:include href="config.rbuild">
      <xi:fallback>
        <xi:include href="config.template.rbuild" />
      </xi:fallback>
    </xi:include>

##### Attributes

href

  Name of XML build file to include. The filename is relative to the location of the current XML build file.

##### Content

None.

##### Children

xi:fallback.

#### xi:fallback

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.

##### Syntax

    <xi:fallback>
      <xi:include href="config.template.rbuild" />
    </xi:fallback>

##### Attributes

None.

##### Content

None.

##### Parents

xi:include.

##### Children

xi:include.

### Element reference

#### Bootstrap element

A bootstrap element specifies that the generated file should be put on the bootable CD as a bootstrap file.

##### Syntax

    <bootstrap base="reactos" nameoncd="halmp.dll" />

##### Attributes

base

  Put file in this directory on the bootable CD. This attribute is optional.

nameoncd

  Name of file on the bootable CD. This attribute is optional.

##### Content

None.

##### Parents

module.

##### Children

None.

#### CDFile element

A cdfile element specifies the name of a file that is to be put on the bootable CD.

##### Syntax

    <cdfile base="reactos" nameoncd="ReadMe.txt">ReadMe.txt</cdfile>

##### Attributes

base

  Put file in this directory on the bootable CD. This attribute is optional.

nameoncd

  Name of file on the bootable CD. This attribute is optional.

##### Content

Name of file.

##### Children

None.

#### Compilerflag element

A compilerflag element specifies additional flags to be bassed to the compiler.

##### Syntax

    <compilerflags>-Wpointer-arith</compilerflag>

##### Attributes.

None.

##### Content

The compiler flags.

##### Parents

if, project.

##### Children

None.

#### Component element

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.

##### Syntax

    <component name="ntdll.dll">
      ...
    </component>

##### Attributes

name

  Name of library.

##### Content

None.

##### Children

symbol.

#### Define element

A define element specifies the name and (optionally) value of a define for the C/C++ compiler and resource compiler.

##### Syntax

    <define name="WINVER">0x501</define>

##### Attributes

name

  Name of define.

##### Content

Value of define. The value is optional.

##### Parents

project, module.

##### Children

None.

#### Dependency element

A dependency element specifies the name of a module (usually of type buildtool) that is to be processed before the current module.

##### Syntax

    <dependency>OtherModule</dependency>

##### Attributes

None.

##### Content

Name of module.

##### Children

None.

#### Directory element

A directory element specifies the name of a subdirectory.

##### Syntax

    <directory name="MyDirectory">
      ...
    </directory>

##### Attributes

name

  Name of directory.

##### Content

None.

##### Parents

directory, if, project.

##### Children

cdfile, directory, file, if, pch, property.

#### File element

A file element specifies the name of a file that is to be processed.

##### Syntax

    <file>MyFile.c</file>

##### Attributes

None.

##### Content

Name of file.

##### Parents

directory, module.

##### Children

None.

#### Group element

A group element's purpose is grouping subelements.

##### Syntax

    <group>
      <file>i386-dis.c</file>
      <file>kdb_help.S</file>
      <file>longjmp.S</file>
      <file>setjmp.S</file>
    </group>

##### Attributes

None.

##### Content

None.

##### Parents

if.

##### Children

file.

#### If element

An if element allows for conditional processing of other elements.

##### Syntax

    <if property="DBG" value="1">
      ...
    </if>

##### Attributes

property

  Name of the property that is to be evaluated.

value

  Value to compare to the value of the property. If the property has the specified value, then the subelements are processed.

##### Content

None.

##### Parents

project, directory.

##### Children

compilerflag, define, directory, file, if, include, property.

#### Importlibrary element

An importlibrary element specifies that an import library should be generated which other modules can use to link with the current module.

##### Syntax

    <importlibrary definition="MyModule.def" />

##### Attributes

definition

  Filename of definition file (`.def`) used to generate the import library. The filename is relative to the current module.

##### Content

None.

##### Parents

module.

##### Children

None.

#### Include element

An include element specifies an include directory for the C/C++ compiler and resource compiler.

##### Syntax

    <include base="MyLibraryModule">include</include>

##### Attributes

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.

##### Content

Relative include directory.

##### Parents

project, module.

##### Children

None.

#### Input element

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.

##### Syntax

    <input>
      ...
    </input>

##### Attributes

None.

##### Content

None.

##### Parents

invoke.

##### Children

inputfile.

#### Inputfile element

An inputfile element specifies a filename that is to be passed as a parameter to a build tool.

##### Syntax

    <inputfile>ntoskrnl.mc</inputfile>

##### Attributes

switches

  Switches that is passed as parameters just before the filename. This attribute is optional.

##### Content

Name of file that is to be passed as a parameter to the build tool.

##### Parents

input.

##### Children

None.

#### Installfile element

An installfile element specifies the name of a file that is to be installed when using '`make install`'.

##### Syntax

    <installfile base="reactos" newname="ReadMe.txt">ReadMe.txt</installfile>

##### Attributes

base

  Put file in this directory within the install directory. This attribute is optional.

newname

  Name of file within the install directory. This attribute is optional.

##### Content

Name of file.

##### Children

None.

#### Invoke element

An invoke element specifies the name of a module which is to be executed before the current module is processed.

##### Syntax

    <invoke module="wmc">
      <input>
        <inputfile>ntoskrnl.mc</inputfile>
      </input>
      <output>
        <outputfile switches="-H">../include/reactos/bugcodes.h</outputfile>
        <outputfile switches="-o">bugcodes.rc</outputfile>
      </output>
    </invoke>

##### Attributes

module

  Name of the module to execute.

##### Content

None.

##### Children

input, output.

#### Library element

A library element specifies the name of another module which is to be linked with the current module.

##### Syntax

    <library>MyLibraryModule</library>

##### Attributes

None.section

##### Parents

module.

##### Children

None.

#### Linkerflag element

A likerflag element specifies flags to be passed to the linker tool.

##### Syntax

    <linkerflag>-lgcc</linkerflag>

##### Attributes

None.

##### Content

The switches to pass to the linker.

##### Parents

module.

##### Children

None.

#### Module element

There can be zero or more `module`s per XML build file.

##### Syntax

    <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">
      ...
    </module>

##### Attributes

if

  If the value is 1, then the module is enabled, otherwise it is disabled. A disabled module is not processed.

ifnot

  If the value is 1, then the module is disabled, otherwise it is enabled. A disabled module is not processed.

name

  Name of the module. Also the base name of the generated file if such file is generated for the particular module type.

type

  Type of module. See below for an explanation of module types. The module type determines the actions that is to be carried out to process the module. The defined module types are seen below:

  ###### Module Types

  Value | Output name suffix | Entrypoint | Baseaddress | Mangledsymbols | Description
  --- | --- | --- | --- | --- | ---
  buildtool
  `.exe` (Windows) | none (Linux)
  - | - | - | Builds a tool that can be run (invoked) when building ReactOS.
  staticlibrary | `.a` | - | - | - | Builds a static library containing object files that can be linked together with other modules.
  objectlibrary | `.o` | - | - | - | Builds object files that can be linked together with other modules.
  kernel | `.exe` | `_NtProcessStartup` | - | - | Builds `ntoskrnl.exe`.
  kernelmodedll | `.dll` | `_DriverEntry@8` | - | - | Builds a kernel-mode DLL.
  kernelmodedriver | `.sys` | `_DriverEntry@8` | - | - | Builds a kernel-mode driver.
  nativecui | .exe | `_NtProcessStartup` | - | - | Build a native NT/ROS program (no enviroment subsystem required to run).
  nativedll | `.dll` | `_DllMainCRTStartup@12` | - | - | Builds a native DLL.
  win32dll | `.dll` | `_DllMain@12` | - | - | Builds a Win32 DLL.
  win32cui | `.exe` | `_mainCRTStartup` | - | - | Builds a Win32 console executable.
  win32gui | `.exe` | `_WinMainCRTStartup` | - | - | Builds a Win32 GUI executable.
  bootloader | - | - | - | - | Builds a bootloader.
  bootsector | - | - | - | - | Builds one or more bootsector binaries.
  iso | - | - | - | -. | Builds a bootable CD.
  test | .exe | `_mainCRTStartup` | - | - | Builds a testsuite.
  rpcserver | `.o` | - | - | - | Generates and builds server code for an RPC interface.
  rpcclient | `.o` | - | - | - | Generates and builds client code for an RPC interface.
  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.

extension

  Extension of the generated file if such file is generated for the particular module type.

entrypoint

  Entrypoint symbol of the generated file if such file is generated for the particular module type.

baseaddress

  Base address of the generated file if such file is generated for the particular module type.

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.

installbase

  Base directory of the generated file in the installation directory. This attribute is optional.

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.

usewrc

  Use WRC to compile resources if true. If false, windres is used. This attribute is optional. If not specified, WRC will be used.

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.

aliasof

  Name of module that is aliased.

##### Content

None.

##### Parents

project, directory.

##### Children

bootstrap, component, define, dependency, directory, file, if, importlibrary, include, invoke, library, linkerflag, property.

#### Output element

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.

##### Syntax

    <output>
      ...
    </output>

##### Attributes

None.

##### Content

None.

##### Parents

invoke

##### Children

outputfile.

#### Outputfile element

An outputfile element specifies a filename that is to be passed as a parameter to a build tool.

##### Syntax

    <outputfile switches="-H">../include/reactos/bugcodes.h</outputfile>

##### Attributes

switches

  Switches that are passed as parameters just before the filename. This attribute is optional.

##### Content

Name of file that is to be passed as a parameter to the build tool.

##### Parents

output.

##### Children

None.

#### Pch element

A pch element specifies a GCC precompiled header file.

##### Syntax

    <pch>ntdll.h</pch>

##### Attributes

None.

##### Content

Name of the include file to be precompiled.

##### Parents

directory.

##### Children

None.

#### Project element

There can be one `project` per top-level XML build file. A project can only be defined in a top-level XML build file.

##### Syntax

    <project name="ReactOS" makefile="Makefile.auto" xmlns:xi="http://www.w3.org/2001/XInclude">
      ...
    </project>

##### Attributes

name

  Name of the project.

makefile

  Filename of the GNU makefile that is to be created.

##### Content

None.

##### Parents

None. This is the top-level (root) element of `ReactOS.rbuild` file.

##### Children

define, directory, if, include, module, property.

#### Property element

A property element specifies the name and value of a property that can be used for conditional processing of the XML build file.

##### Syntax

    <property name="mypropertyname" value="mypropertyvalue" />

##### Attributes

name

  Name of property.

value

  Value of property.

##### Content

None.

##### Parents

##### Children

None.

#### Symbol element

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.

##### Syntax

    <symbol newname="RtlAllocateHeap">HeapAlloc@12</symbol>

##### Attributes

newname

  New name of symbol. This attribute is optional.

##### Content

Name of symbol.

##### Children

None.

## Bibliography

### Extensible Markup Language (XML) 1.0 (Third Edition)

W3C Recommendation
François
Yergeau
Tim
Bray
Jean
Paoli
C. M.
Sperberg-McQueen
Eve
Maler
4th February 2004

### XML Inclusions (XInclude) Version 1.0

W3C Recommendation
Jonathan
Marsh
Microsoft
jmarsh@microsoft.com
David
Orchard
BEA Systems
dorchard@bea.com
20 December 2004