RBuild File Reference

Structure

Each .rbuild file is an XML document. Thus, they should begin with:

 <?xml version="1.0"?>
 <!DOCTYPE module SYSTEM "../../../tools/rbuild/project.dtd">

Adjust the path to the DTD as necessary, depending on how deep within the directory structure your .rbuild file is.

Most elements within an .rbuild file are single-line. That is, you'd usually close the element on the same line as you opened it. Exceptions to this include module, directory and compilationunit.

A simple example probably illustrates this best:

 <?xml version="1.0"?>
 <!DOCTYPE module SYSTEM "../../../tools/rbuild/project.dtd">
 
 <module>
     <library>user32</library>
     <file>foo.c</file>
     <directory name="extra">
         <file>bar.c</file>
     </directory>
 </module>

Element Reference

<compilationunit>

If you wish to merge several files together and compile them as one file, you will wrap <file> elements with this.

Usage Example

 <compilationunit name="allfoo.c">
     <file>main.c</file>
 </compilationunit>

Attributes

name

The name of the file to be created as a result of merging the source files.

<define>

Has pretty much the same effect as a #define in your source code. Using this will make it a global for all files.

 <define name="_WIN32_WINNT">0x0501</define>

is equivalent to:

 #define _WIN32_WINNT 0x0501

Attributes

name

The name of the definition, as can be used in the source code.

<dependency>

Specifies what other modules your module is dependent upon, so that the compiler knows to recompile your module in the event there's a change in the other one. This element also makes sure that this other module is processed before yours.

Cannot be used within an <if> or <ifnot> element.

Usage Example

 <dependency>wineheaders</dependency>

<directory>

Specifies a sub-directory where you want to do something. Typically, you'll use this when you have your source code files laid-out with their own directory structure. All files listed in the child <file> elements are then used without requiring the directory name to be specified for each one.

Usage Example

 <directory name="core">
     <file>main.c</file>
     <file>stuff.c</file>
     ...
 </directory>

Attributes

name

The name of the sub-directory.

<file>

Each file element specifies a file to be compiled as part of the module.

Usage Example

 <file>main.c</file>
 <file>functions.c</file>
 ...

<if>

If you want to make use use of ROS config flags, you can use this element for conditional options.

Usage Example

 <if property="CONFIGFLAG" value="setting">
     ...
 </if>

Attributes

property

...

value

...

<ifnot>

The the opposite of the <if> element - ie, if the property does not match the value, the elements within this tag take effect.

Usage Example

 <ifnot property="CONFIGFLAG" value="setting">
     ...
 </ifnot>

Attributes

property

...

value

...

<importlibrary>

This element is only needed if you're trying to export functions. This is most frequently used in DLLs, in which case your file would be located in something like /dll/*/foo. Drivers sometimes also export functions.

Only one importlibrary is allowed per module.

Usage Example

 <importlibrary definition="foo.def" />

Attributes

definition

Specifies the name of the export definition file.

<include>

This is only needed if you need some special header that are not located in the base include directories. Otherwise you don't need to add it in.

Usage Example

 <include base="namedir">actualdir</include>

With this, you can do something like #include "namedir/foo.h".

Attributes

base

The name of the module whose directory you want to use as a base. Is this correct?

<invoke>

? Cannot be used within an <if> or <ifnot> element.

<library>

Next is which libraries you will be using. If you use more than one library, the declaration becomes multi-line.

For this, you need to know what libraries your program will need. If you don't know, you can try compiling the program and see which functions GCC complains about no finding and figure out where they're from.

Usage Example

 <library>user32</library>
 <library>shell32</library>
 ...

<linkerflag>

Use this element to pass flags to the linker.

Usage Example

 <linkerflag>-nostdlib</linkerflag>

<metadata>

? Cannot be used within an <if> or <ifnot> element.

<module>

The module element defines the thing to be built.

Usage Example

 <module name="foo" installname="foo.exe" type="win32gui" unicode="true">
     ...
 </module>

Attributes

aliasof

?

allowwarnings

• true - Compilation will not fail if warnings are generated
• false - Compilation will fail if warnings are generated

baseaddress

The base address at which this module is loaded. Used mostly for API DLLs.

buildtype

Applicable only when the module has a type of bootprogram or elfexecutable.

description

?

entrypoint

Defines the entry-point function - typically used with drivers.

 entrypoint="DriverEntry@8"

extension

?

host

• true - ?
• false - ?

if

?

installbase

The base directory where the module will ultimately become installed.

installname

The final program/library file name, once compiled and linked.

 installname="regedit.exe"

This attribute over-rides the output attribute.

isstartuplib

• true - ?
• false - ?

layoutid

? Related to keyboard layout

layoutnameresid

? Related to keyboard layout

lcid

? Related to keyboard layout

mangledsymbols

• true - Enable symbol mangling
• false - Disable symbol mangling

name

Each module in the ReactOS tree has a unique name, which acts as an identifier when referring to the module elsewhere in other .rbuild files. In most cases, it will just be the same as the installname, without the extension.

 name="regedit"

output

See installname above.

payload

Applicable only for modules which have a type attribute of bootprogram

prefix

?

type

• win32cui - Console application
• win32gui - Windows application
• win32dll - Dynamic Linked Library
• win32ocx - OLE custom control
• win32scr - Screensaver
• nativedll
• nativecui
• staticlibrary
• objectlibrary - Statically-linked library
• exportdriver - Drivers that export public symbols
• kernelmodedll
• kernelmodedriver - .sys driver
• rpcserver
• rpcclient
• rpcproxy
• bootloader
• bootsector
• bootprogram
• buildtool
• hoststaticlibrary
• kernel
• keyboardlayout
• iso
• liveiso
• isoregtest
• liveisoregtest
• test
• alias
• idlheader
• embeddedtypelib
• elfexecutable
• cabinet
• messageheader

underscoresymbols

• true - ?
• false - ?

unicode

• true - Use UNICODE strings (wide-character strings)
• false - Use regular strings

<pch>

Designates the use of a precompiled header. Basically this tells the compiler to precompile the specified header and any other header which it, in turn, includes.

Usage Example

 <pch>precomp.h</pch>

Example RBuild Files

Often when creating an RBuild file, it's just a case of copying a similar module's RBuild file and tailoring it to suit your needs. Whilst this approach works, it can be a bit messy.

Bare-bones

Change the path to the DTD and fill in the blanks.

 <?xml version="1.0"?>
 <!DOCTYPE module SYSTEM "../tools/rbuild/project.dtd">
 <module name="" type="" allowwarnings="" unicode="">
   <library></library>
   <file></file>
 </module>

Win32 DLL Example

Here's an RBuild for a fictional library called "foolib":

 <?xml version="1.0"?>
 <!DOCTYPE module SYSTEM "../../../tools/rbuild/project.dtd">
 <module name="foolib.dll" type="win32dll" allowwarnings="false" unicode="yes">
   <importlibrary definition="foolib.def">
   <library>user32</library>
   <file>main.c</file>
   <file>another.c</file>
   <directory name="utils">
       <file>string.c</file>
       <file>number.c</file>
   </directory>
 </module>