Difference between revisions of "RBuild Files"

From ReactOS Wiki
Jump to: navigation, search
m
 
(11 intermediate revisions by 7 users not shown)
Line 1: Line 1:
'''work in progress by Z98'''
+
{{Notice| RBuild isn't used anymore in ReactOS. Plese see [[CMake]] instead.}}
 +
This is an overview of how to construct an .rbuild file, which is useful when writing one from scratch. For a general reference of the options available to you when writing RBuild files, see the [[RBuild File Reference]].
  
 
If you have another program that you wish to compile into ReactOS, you will need the source code as well as create an rbuild config file for it.  In this example, we will assume that the program is called foo.  The order in which I explain the various options are the order they technically should be in when you create an .rbuild file.
 
If you have another program that you wish to compile into ReactOS, you will need the source code as well as create an rbuild config file for it.  In this example, we will assume that the program is called foo.  The order in which I explain the various options are the order they technically should be in when you create an .rbuild file.
  
In the first line, you define a new module (executable).  For type, you have the option of using win32cui (console application), win32gui (Windows application), win32ocx (OLE custom control), win32dll (Dynamic Linked Libraries), objectlibrary (statically-linked library), exportdriver (drivers that export public symbols), and kernelmodedriver (.sys driver).  The other two are self explanatory.  Another option that could be added is unicode="true/false". If you are compiling a driver you should also add entrypoint="DriverEntry@8".
+
Each .rbuild file is an XML document, so should begin with the '''xml''' tag and a reference to the DTD. The path to the DTD will vary depending on whereabouts in the source tree your code is. An example:
  <module name="foo" type="win32gui" installname="foo.exe">
+
<syntaxhighlight lang="xml">
 +
  <?xml version="1.0"?>
 +
  <!DOCTYPE module SYSTEM "../../../tools/rbuild/project.dtd">
 +
</syntaxhighlight>
 +
Following this, you define a new module (executable).  For type, you have the option of using:
 +
* win32cui (console application)
 +
* win32gui (Windows application)
 +
* win32ocx (OLE custom control)
 +
* win32dll (Dynamic Linked Libraries)
 +
* objectlibrary (statically-linked library)
 +
* exportdriver (drivers that export public symbols)
 +
* kernelmodedriver (.sys driver)
 +
 
  
 +
Another option that could be added is unicode="true/false". If you are compiling a driver you should also add entrypoint="DriverEntry@8".
 +
<syntaxhighlight lang="xml">
 +
  <module name="foo" type="win32gui" installname="foo.exe" allowwarnings="true">
 +
</syntaxhighlight>
 
This line 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.
 
This line 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.
 +
<syntaxhighlight lang="xml">
 
   <importlibrary definition="foo.def" />
 
   <importlibrary definition="foo.def" />
 
+
</syntaxhighlight>
 
This line 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.
 
This line 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.
 +
<syntaxhighlight lang="xml">
 
   <include base="namedir">actualdir</include>
 
   <include base="namedir">actualdir</include>
 +
</syntaxhighlight>
 
With this, you can do something like #include "namedir/foo.h".
 
With this, you can do something like #include "namedir/foo.h".
  
 
This statement is the same as a #define in your source code.  Using this will make it a global for all files.
 
This statement is the same as a #define in your source code.  Using this will make it a global for all files.
 +
<syntaxhighlight lang="xml">
 
   <define name="_WIN32_WINNT">0x0501</define>
 
   <define name="_WIN32_WINNT">0x0501</define>
 
+
</syntaxhighlight>
 
This statement is used to designate the use of a precompiled header.  Basically this tells the compiler to precompile the specified header and all its includes.
 
This statement is used to designate the use of a precompiled header.  Basically this tells the compiler to precompile the specified header and all its includes.
 +
<syntaxhighlight lang="xml">
 
   <pch>precomp.h</pch>
 
   <pch>precomp.h</pch>
 
+
</syntaxhighlight>
 
This statement specifies a subdirectory where you want to do something.  Once you are done supplying config information, you must close it.  You will see one of the uses for this further down.
 
This statement specifies a subdirectory where you want to do something.  Once you are done supplying config information, you must close it.  You will see one of the uses for this further down.
 +
<syntaxhighlight lang="xml">
 
   <directory name="stuff">
 
   <directory name="stuff">
 
       (various other config options)
 
       (various other config options)
 
   </directory>
 
   </directory>
 
+
</syntaxhighlight>
 
If you want to make use use of ROS config flags, you can use the following lines for conditional options.
 
If you want to make use use of ROS config flags, you can use the following lines for conditional options.
 +
<syntaxhighlight lang="xml">
 
   <if property="CONFIGFLAG" value="setting">
 
   <if property="CONFIGFLAG" value="setting">
 
       (various other config options)
 
       (various other config options)
 
   </if>
 
   </if>
 
+
</syntaxhighlight>
 
This statement 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 statement 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.
 +
<syntaxhighlight lang="xml">
 
   <dependency>wineheaders</dependency>
 
   <dependency>wineheaders</dependency>
 
+
</syntaxhighlight>
 
Next is which libraries you will be using.  If you use more than one library, the declaration becomes multi-line.
 
Next is which libraries you will be using.  If you use more than one library, the declaration becomes multi-line.
 +
<syntaxhighlight lang="xml">
 
   <library>user32</library>
 
   <library>user32</library>
 
   <library>shell32</library>
 
   <library>shell32</library>
 +
</syntaxhighlight>
 
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.
 
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.
  
 
If you want to specify special linkerflags, use something like the following statement:
 
If you want to specify special linkerflags, use something like the following statement:
 +
<syntaxhighlight lang="xml">
 
   <linkerflag>-nostdlib</linkerflag>
 
   <linkerflag>-nostdlib</linkerflag>
 
+
</syntaxhighlight>
 
If you wish to merge several files together and compile them as one file, you will wrap <file> with this.
 
If you wish to merge several files together and compile them as one file, you will wrap <file> with this.
 +
<syntaxhighlight lang="xml">
 
   <compilationunit name = allfoo.c>
 
   <compilationunit name = allfoo.c>
 
+
</syntaxhighlight>
 
Next comes the files that will be compiled.
 
Next comes the files that will be compiled.
 +
<syntaxhighlight lang="xml">
 
   <file>main.c</file>
 
   <file>main.c</file>
 
   <file>functions.c</file>
 
   <file>functions.c</file>
 
+
</syntaxhighlight>
 
If you had used <compliationunit> above, you must close it.
 
If you had used <compliationunit> above, you must close it.
 +
<syntaxhighlight lang="xml">
 
   </compliationunit>
 
   </compliationunit>
 
+
</syntaxhighlight>
 
You end the module definition with this.
 
You end the module definition with this.
 +
<syntaxhighlight lang="xml">
 
   </module>
 
   </module>
 
+
</syntaxhighlight>
 
Once you're done creating your rbuild file, you must go one level up and add this to the rbuild file there.
 
Once you're done creating your rbuild file, you must go one level up and add this to the rbuild file there.
   <directory name = "foo"
+
<syntaxhighlight lang="xml">
 +
   <directory name = "foo">
 
       <x:include href="foo/foo.rbuild">
 
       <x:include href="foo/foo.rbuild">
 
   </directory>
 
   </directory>
 
+
</syntaxhighlight>
 
Now you should be able to compile the new module with "make foo".
 
Now you should be able to compile the new module with "make foo".
  
 
Here's a more continuous example.
 
Here's a more continuous example.
 
+
<syntaxhighlight lang="xml">
 +
  <?xml version="1.0"?>
 +
 
 +
  <!DOCTYPE module SYSTEM "../../../tools/rbuild/project.dtd">
 +
 
 
   <module name="foo" type="win32gui" installname="foo.exe">
 
   <module name="foo" type="win32gui" installname="foo.exe">
 
    
 
    
Line 69: Line 106:
 
    
 
    
 
   </module>
 
   </module>
 
+
</syntaxhighlight>
Notes:
+
=== Notes ===
 
* Use of backslashes is liable to break Linux builds.  Always use forward(/) slashes.  mingw can figure out what you mean.
 
* Use of backslashes is liable to break Linux builds.  Always use forward(/) slashes.  mingw can figure out what you mean.
 
* Also, use tab for indentation.
 
* Also, use tab for indentation.
 +
 +
[[Category:Building]]
 +
[[Category:Documentation]]
 +
[[Category:Tutorial]]

Latest revision as of 08:20, 15 May 2014

Imbox notice.png

Notice: RBuild isn't used anymore in ReactOS. Plese see CMake instead.

This is an overview of how to construct an .rbuild file, which is useful when writing one from scratch. For a general reference of the options available to you when writing RBuild files, see the RBuild File Reference.

If you have another program that you wish to compile into ReactOS, you will need the source code as well as create an rbuild config file for it. In this example, we will assume that the program is called foo. The order in which I explain the various options are the order they technically should be in when you create an .rbuild file.

Each .rbuild file is an XML document, so should begin with the xml tag and a reference to the DTD. The path to the DTD will vary depending on whereabouts in the source tree your code is. An example:

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

Following this, you define a new module (executable). For type, you have the option of using:

  • win32cui (console application)
  • win32gui (Windows application)
  • win32ocx (OLE custom control)
  • win32dll (Dynamic Linked Libraries)
  • objectlibrary (statically-linked library)
  • exportdriver (drivers that export public symbols)
  • kernelmodedriver (.sys driver)


Another option that could be added is unicode="true/false". If you are compiling a driver you should also add entrypoint="DriverEntry@8".

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

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

  <importlibrary definition="foo.def" />

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

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

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

This statement is the same as a #define in your source code. Using this will make it a global for all files.

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

This statement is used to designate the use of a precompiled header. Basically this tells the compiler to precompile the specified header and all its includes.

  <pch>precomp.h</pch>

This statement specifies a subdirectory where you want to do something. Once you are done supplying config information, you must close it. You will see one of the uses for this further down.

  <directory name="stuff">
      (various other config options)
  </directory>

If you want to make use use of ROS config flags, you can use the following lines for conditional options.

  <if property="CONFIGFLAG" value="setting">
      (various other config options)
  </if>

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

  <dependency>wineheaders</dependency>

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

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

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.

If you want to specify special linkerflags, use something like the following statement:

  <linkerflag>-nostdlib</linkerflag>

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

  <compilationunit name = allfoo.c>

Next comes the files that will be compiled.

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

If you had used <compliationunit> above, you must close it.

  </compliationunit>

You end the module definition with this.

  </module>

Once you're done creating your rbuild file, you must go one level up and add this to the rbuild file there.

  <directory name = "foo">
      <x:include href="foo/foo.rbuild">
  </directory>

Now you should be able to compile the new module with "make foo".

Here's a more continuous example.

  <?xml version="1.0"?>
  
  <!DOCTYPE module SYSTEM "../../../tools/rbuild/project.dtd">
  
  <module name="foo" type="win32gui" installname="foo.exe">
  
      <library>user32</library>
  
      <file>foo.c</file>
  
  </module>

Notes

  • Use of backslashes is liable to break Linux builds. Always use forward(/) slashes. mingw can figure out what you mean.
  • Also, use tab for indentation.