RBuild File Reference

From ReactOS Wiki
Revision as of 15:10, 5 July 2008 by Silverblade (talk | contribs)
Jump to: navigation, search

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.

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

...


<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.

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?


<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>


<module>

The module element defines the thing to be built.

Usage Example

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

Attributes

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


allowwarnings

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

entrypoint

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

 entrypoint="DriverEntry@8"

installname

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

 installname="regedit.exe"

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"

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>