Difference between revisions of "RBuild File Reference"

From ReactOS Wiki
Jump to: navigation, search
m (‎)
(unicode)
Line 430: Line 430:
  
 
==== unicode ====
 
==== unicode ====
* true - Use UNICODE strings (wide-character strings)
+
* yes - Use a Unicode entry point (''wmain'' or ''wWinMain'' depending on the application type) and define UNICODE and _UNICODE
* false - Use regular strings
+
* no (default) - Use regular strings
 
 
  
 
== <pch> ==
 
== <pch> ==

Revision as of 17:28, 5 July 2008

Contents

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

<autoregister>

?

Restrictions

  • Only one <autoregister> is allowed per <module>.


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


<bootstrap>

?


<compilerflag>

Use this element to pass flags to the compiler.


<component>

?


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

Restrictions

  • 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 part of the module. It depends on the file and module type how this file is later processed in the build.

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.

Restrictions

  • 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="somemodule">actualdir</include>

With this, you can do something like #include <foo.h>, where foo.h is located in the sub-directory actualdir of the module somemodule.

Attributes

base (optional)

The name of the module whose directory you want to use as a base. Not allowed for global includes specified outside of a module.

root (optional)

Possible values are:

intermediate Build the include path to the module using the intermediate directory as the root
output Build the include path to the module using the output directory as the root

<invoke>

?

Restrictions

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


<linkerscript>

?

Restrictions

  • Cannot be used within an <if> or <ifnot> element.
  • Only one instance of this element may be within a <module> element.


<metadata>

?

Restrictions

  • 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

?

ifnot

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

type explanation notes
win32cui Win32 Console application
win32gui Win32 Windowed application
win32dll Win32 Dynamic Linked Library
win32ocx Win32 OLE custom control
win32scr Win32 Screensaver (same as win32gui, but the output file will have the .scr extension)
nativedll Native Dynamic Linked Library
nativecui Native Console application
staticlibrary Static Library
objectlibrary Statically-linked library
kernelmodedll Kernel-Mode Dynamic Linked Library
kernelmodedriver Kernel-Mode Driver (usually all .sys drivers)
rpcserver RPC Server application described by an .idl file (processed by widl)
rpcclient RPC Client application described by an .idl file (processed by widl)
rpcproxy RPC Proxy application described by an .idl file (processed by widl)
bootloader Custom module type for the FreeLdr boot loader
bootsector Custom module type for the boot sectors
bootprogram Currently unused looks deprecated
buildtool Tool compiled for the host platform needed for building
hoststaticlibrary Static library compiled for the host platform (useful in conjunction with buildtool modules)
kernel Custom module type for the kernel (ntoskrnl)
keyboardlayout Custom module type for keyboard layouts
iso Custom module type for the Boot-CD ISO
liveiso Custom module type for the Live-CD ISO
isoregtest Custom module type for the Boot-CD ISO containing an information file for unattended installation (useful for the sysreg regression testing tool)
liveisoregtest Custom module type for the Live-CD ISO containing an information file for unattended installation (useful for the sysreg regression testing tool)
test Used for some application tests looks deprecated
alias Module aliasing concept (currently only used in hal and looks hackish :D) looks deprecated
idlheader Uses widl to process .idl files and creates a header file out of them
embeddedtypelib Type Library described by an .idl file (processed by widl)
elfexecutable Currently only internally used by PowerPC stuff
cabinet Uses cabman to put the child <file> elements into a cabinet file
messageheader Uses wmc to process the child <file> element (must be only one and a .mc file)

underscoresymbols

  • true - ?
  • false - ?

unicode

  • yes - Use a Unicode entry point (wmain or wWinMain depending on the application type) and define UNICODE and _UNICODE
  • no (default) - 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.

Restrictions

  • Cannot be used within an <if> or <ifnot> element.
  • Only one instance of this element may be a child of a <module> element.

Usage Example

 <pch>precomp.h</pch>


<property>

?

Restrictions

  • Cannot be a child element of a <module> element.


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>