--- trunk/reactos/tools/rbuild/doc/rbuild.dbk 2005-07-30 16:25:35 UTC (rev 16894)
+++ trunk/reactos/tools/rbuild/doc/rbuild.dbk 2005-07-30 16:53:09 UTC (rev 16895)
@@ -0,0 +1,1529 @@
+<?xml version="1.0" encoding="US-ASCII"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<book>
+ <title>ReactOS Build System Documentation</title>
+
+ <bookinfo>
+ <releaseinfo>$Id$</releaseinfo>
+
+ <author>
+ <firstname>Casper</firstname>
+
+ <surname>Hornstrup</surname>
+ </author>
+
+ <othercredit>
+ <surname>Emanuele Aliberti</surname>
+ </othercredit>
+
+ <copyright>
+ <year>2005</year>
+ </copyright>
+ </bookinfo>
+
+ <chapter>
+ <title>Building ReactOS</title>
+
+ <section>
+ <title>Building ReactOS</title>
+
+ <para>To generate GNU make makefiles and building ReactOS, do the
+ following:<orderedlist>
+ <listitem>
+ <para>Go to the top-level <filename>reactos</filename>
+ directory;</para>
+ </listitem>
+
+ <listitem>
+ <para>Run the command:<screen>mingw32-make</screen></para>
+
+ <para>This will start building ReactOS.</para>
+ </listitem>
+ </orderedlist></para>
+
+ <para>To build a bootable CD, run the following command:<screen>mingw32-make bootcd</screen>This
+ will create <filename>ReactOS.iso</filename> in the top-level
+ <filename>reactos</filename> directory.</para>
+ </section>
+ </chapter>
+
+ <chapter>
+ <title>How build directions are stored</title>
+
+ <para>XML files are used throughout the ReactOS source tree to drive the
+ build system.</para>
+
+ <section>
+ <title>Top-level XML Build File</title>
+
+ <para>The top-level XML build file (<filename>ReactOS.xml</filename>) is
+ processed by <command>rbuild</command>. The following is an example of
+ how it could look like:<programlisting><?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.xml">
+ <xi:fallback>
+ <xi:include href="config.template.xml" />
+ </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.xml" />
+ </directory>
+
+ <module name="bootcd" type="iso">
+ </module>
+</project></programlisting></para>
+
+ <section>
+ <title>XInclude</title>
+
+ <para>XML files used by <command>rbuild</command> are modular and use
+ XInclude to include other chunks of XML in the top-level ReactOS.xml
+ file. The namespace used by XInclude is <literal>xi</literal>.</para>
+
+ <section>
+ <title>xi:include</title>
+
+ <para>It is possible to split an XML build file over several files.
+ The include element in the <literal>xi</literal> namespace is used
+ to accomplish this.</para>
+
+ <section>
+ <title>Syntax</title>
+
+ <programlisting> <xi:include href="config.xml">
+ <xi:fallback>
+ <xi:include href="config.template.xml" />
+ </xi:fallback>
+ </xi:include></programlisting>
+ </section>
+
+ <section>
+ <title>Attributes</title>
+
+ <para><variablelist>
+ <varlistentry>
+ <term>href</term>
+
+ <listitem>
+ <para>Name of XML build file to include. The filename is
+ relative to the location of the current XML build
+ file.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist></para>
+ </section>
+
+ <section>
+ <title>Value</title>
+
+ <para>None.</para>
+ </section>
+
+ <section>
+ <title>Elements</title>
+
+ <para>xi:fallback</para>
+ </section>
+ </section>
+
+ <section>
+ <title>xi:fallback</title>
+
+ <para>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.</para>
+
+ <section>
+ <title>Attributes</title>
+
+ <para>None.</para>
+ </section>
+
+ <section>
+ <title>Value</title>
+
+ <para>None.</para>
+ </section>
+
+ <section>
+ <title>Elements</title>
+
+ <para>xi:include</para>
+ </section>
+ </section>
+ </section>
+
+ <section>
+ <title xreflabel="element_project">Project element</title>
+
+ <para>There can be one <sgmltag class="element">project</sgmltag> per
+ top-level XML build file. A project can only be defined in a top-level
+ XML build file.</para>
+
+ <section>
+ <title>Syntax</title>
+
+ <para><programlisting><project name="ReactOS" makefile="Makefile.auto" xmlns:xi="http://www.w3.org/2001/XInclude">
+ ...
+</project></programlisting></para>
+ </section>
+
+ <section>
+ <title>Attributes</title>
+
+ <para><variablelist>
+ <varlistentry>
+ <term>name</term>
+
+ <listitem>
+ <para>Name of the project.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>makefile</term>
+
+ <listitem>
+ <para>Filename of the GNU makefile that is to be
+ created.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist></para>
+ </section>
+
+ <section>
+ <title>Value</title>
+
+ <para>None.</para>
+ </section>
+
+ <section>
+ <title>Elements</title>
+
+ <para><link linkend="element_define">define</link>, <link
+ linkend="element_directory">directory</link>, <link
+ linkend="element_if">if</link>, <link
+ linkend="element_include">include</link>, <link
+ linkend="element_module">module</link>, <link
+ linkend="element_property">property</link>.</para>
+ </section>
+ </section>
+
+ <section>
+ <title xreflabel="element_module">Module element</title>
+
+ <para>There can be zero or more <sgmltag
+ class="element">module</sgmltag>s per XML build file.</para>
+
+ <section>
+ <title>Syntax</title>
+
+ <para><programlisting><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" warnings="true" aliasof="module1">
+ ...
+</module></programlisting></para>
+ </section>
+
+ <section>
+ <title>Attributes</title>
+
+ <para><variablelist>
+ <varlistentry>
+ <term>if</term>
+
+ <listitem>
+ <para>If the value is 1, then the module is enabled,
+ otherwise it is disabled. A disabled module is not
+ processed.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ifnot</term>
+
+ <listitem>
+ <para>If the value is 1, then the module is disabled,
+ otherwise it is enabled. A disabled module is not
+ processed.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>name</term>
+
+ <listitem>
+ <para>Name of the module. Also the base name of the
+ generated file if such file is generated for the particular
+ module type.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>type</term>
+
+ <listitem>
+ <para>Type of module. See below for an explanation of module
+ types. <emphasis><emphasis>The module type determines the
+ actions that is to be carried out to process the module. The
+ defined module types are seen
+ below:</emphasis></emphasis></para>
+
+ <table>
+ <title>Module Types</title>
+
+ <tgroup cols="6">
+ <thead>
+ <row>
+ <entry>Value</entry>
+
+ <entry>Output name suffix</entry>
+
+ <entry>Entrypoint</entry>
+
+ <entry>Baseaddress</entry>
+
+ <entry>Mangledsymbols</entry>
+
+ <entry>Description</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>buildtool</entry>
+
+ <entrytbl cols="2">
+ <tbody>
+ <row>
+ <entry><filename>.exe</filename> (Windows)</entry>
+
+ <entry>none (Linux)</entry>
+ </row>
+ </tbody>
+ </entrytbl>
+
+ <entry>-</entry>
+
+ <entry>-</entry>
+
+ <entry>-</entry>
+
+ <entry>Builds a tool that can be run (invoked) when
+ building ReactOS.</entry>
+ </row>
+
+ <row>
+ <entry>staticlibrary</entry>
+
+ <entry><filename>.a</filename></entry>
+
+ <entry>-</entry>
+
+ <entry>-</entry>
+
+ <entry>-</entry>
+
+ <entry>Builds a static library containing object
+ files that can be linked together with other
+ modules.</entry>
+ </row>
+
+ <row>
+ <entry>objectlibrary</entry>
+
+ <entry><filename>.o</filename></entry>
+
+ <entry>-</entry>
+
+ <entry>-</entry>
+
+ <entry>-</entry>
+
+ <entry>Builds object files that can be linked
+ together with other modules.</entry>
+ </row>
+
+ <row>
+ <entry>kernel</entry>
+
+ <entry><filename>.exe</filename></entry>
+
+ <entry><function>_NtProcessStartup</function></entry>
+
+ <entry>-</entry>
+
+ <entry>-</entry>
+
+ <entry>Builds
+ <filename>ntoskrnl.exe</filename>.</entry>
+ </row>
+
+ <row>
+ <entry>kernelmodedll</entry>
+
+ <entry><filename>.dll</filename></entry>
+
+ <entry><function>_DriverEntry@8</function></entry>
+
+ <entry>-</entry>
+
+ <entry>-</entry>
+
+ <entry>Builds a kernel-mode DLL.</entry>
+ </row>
+
+ <row>
+ <entry>kernelmodedriver</entry>
+
+ <entry><filename>.sys</filename></entry>
+
+ <entry><function>_DriverEntry@8</function></entry>
+
+ <entry>-</entry>
+
+ <entry>-</entry>
+
+ <entry>Builds a kernel-mode driver.</entry>
+ </row>
+
+ <row>
+ <entry>nativedll</entry>
+
+ <entry><filename>.dll</filename></entry>
+
+ <entry><function>_DllMainCRTStartup@12</function></entry>
+
+ <entry>-</entry>
+
+ <entry>-</entry>
+
+ <entry>Builds a native DLL.</entry>
+ </row>
+
+ <row>
+ <entry>win32dll</entry>
+
+ <entry><filename>.dll</filename></entry>
+
+ <entry><function>_DllMain@12</function></entry>
+
+ <entry>-</entry>
+
+ <entry>-</entry>
+
+ <entry>Builds a Win32 DLL.</entry>
+ </row>
+
+ <row>
+ <entry>win32cui</entry>
+
+ <entry><filename>.exe</filename></entry>
+
+ <entry><function>_mainCRTStartup</function></entry>
+
+ <entry>-</entry>
+
+ <entry>-</entry>
+
+ <entry>Builds a Win32 console executable.</entry>
+ </row>
+
+ <row>
+ <entry>win32gui</entry>
+
+ <entry><filename>.exe</filename></entry>
+
+ <entry><function>_WinMainCRTStartup</function></entry>
+
+ <entry>-</entry>
+
+ <entry>-</entry>
+
+ <entry>Builds a Win32 GUI executable.</entry>
+ </row>
+
+ <row>
+ <entry>bootloader</entry>
+
+ <entry>-</entry>
+
+ <entry>-</entry>
+
+ <entry>-</entry>
+
+ <entry>-</entry>
+
+ <entry>Builds a bootloader.</entry>
+ </row>
+
+ <row>
+ <entry>bootsector</entry>
+
+ <entry>-</entry>
+
+ <entry>-</entry>
+
+ <entry>-</entry>
+
+ <entry>-</entry>
+
+ <entry>Builds one or more bootsector binaries. The
+ entrypoint, baseaddress, and mangledsymbols module
+ attributes are not applicable for this module
+ type.</entry>
+ </row>
+
+ <row>
+ <entry>iso</entry>
+
+ <entry>-</entry>
+
+ <entry>-</entry>
+
+ <entry>-</entry>
+
+ <entry>-.</entry>
+
+ <entry>Builds a bootable CD.</entry>
+ </row>
+
+ <row>
+ <entry>test</entry>
+
+ <entry>.exe</entry>
+
+ <entry>_mainCRTStartup</entry>
+
+ <entry>-</entry>
+
+ <entry>-</entry>
+
+ <entry>Builds a testsuite.</entry>
+ </row>
+
+ <row>
+ <entry>rpcserver</entry>
+
+ <entry><filename>.o</filename></entry>
+
+ <entry>-</entry>
+
+ <entry>-</entry>
+
+ <entry>-</entry>
+
+ <entry>Generates and builds server code for an RPC
+ interface.</entry>
+ </row>
+
+ <row>
+ <entry>rpcclient</entry>
+
+ <entry><filename>.o</filename></entry>
+
+ <entry>-</entry>
+
+ <entry>-</entry>
+
+ <entry>-</entry>
+
+ <entry>Generates and builds client code for an RPC
+ interface.</entry>
+ </row>
+
+ <row>
+ <entry>alias</entry>
+
+ <entry>-</entry>
+
+ <entry>-</entry>
+
+ <entry>-</entry>
+
+ <entry>-</entry>
+
+ <entry>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.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>extension</term>
+
+ <listitem>
+ <para>Extension of the generated file if such file is
+ generated for the particular module type.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>entrypoint</term>
+
+ <listitem>
+ <para>Entrypoint symbol of the generated file if such file
+ is generated for the particular module type.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>baseaddress</term>
+
+ <listitem>
+ <para>Base address of the generated file if such file is
+ generated for the particular module type.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>mangledsymbols</term>
+
+ <listitem>
+ <para>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.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>installbase</term>
+
+ <listitem>
+ <para>Base directory of the generated file in the
+ installation directory. This attribute is optional.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>installname</term>
+
+ <listitem>
+ <para>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.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>usewrc</term>
+
+ <listitem>
+ <para>Use WRC to compile resources if true. If false,
+ windres is used. This attribute is optional. If not
+ specified, WRC will be used.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>warnings</term>
+
+ <listitem>
+ <para>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.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>aliasof</term>
+
+ <listitem>
+ <para>Name of module that is aliased.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist></para>
+ </section>
+
+ <section>
+ <title>Value</title>
+
+ <para>None.</para>
+ </section>
+
+ <section>
+ <title>Elements</title>
+
+ <para><link linkend="element_bootstrap">bootstrap</link>, <link
+ linkend="element_component">component</link>, <link
+ linkend="element_define">define</link>, <link
+ linkend="element_dependency">dependency</link>, <link
+ linkend="element_directory">directory</link>, <link
+ linkend="element_file">file</link>, <link
+ linkend="element_if">if</link>, <link
+ linkend="element_importlibrary">importlibrary</link>, <link
+ linkend="element_include">include</link>, <link
+ linkend="element_invoke">invoke</link>, <link
+ linkend="element_library">library</link>, <link
+ linkend="element_property">property</link>.</para>
+ </section>
+ </section>
+
+ <section>
+ <title xreflabel="element_bootstrap">Bootstrap element</title>
+
+ <para>A bootstrap element specifies that the generated file should be
+ put on the bootable CD as a bootstrap file.</para>
+
+ <section>
+ <title>Syntax</title>
+
+ <para><programlisting><bootstrap base="reactos" nameoncd="halmp.dll" /></programlisting></para>
+ </section>
+
+ <section>
+ <title>Attributes</title>
+
+ <para><variablelist>
+ <varlistentry>
+ <term>base</term>
+
+ <listitem>
+ <para> Put file in this directory on the bootable CD. This
+ attribute is optional.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>nameoncd</term>
+
+ <listitem>
+ <para> Name of file on the bootable CD. This attribute is
+ optional.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist></para>
+ </section>
+
+ <section>
+ <title>Value</title>
+
+ <para>None.</para>
+ </section>
+
+ <section>
+ <title>Elements</title>
+
+ <para>None.</para>
+ </section>
+ </section>
+
+ <section>
+ <title xreflabel="element_cdfile">CDFile element</title>
+
+ <para>A cdfile element specifies the name of a file that is to be put
+ on the bootable CD.</para>
+
+ <section>
+ <title>Syntax</title>
+
+ <para><programlisting><cdfile base="reactos" nameoncd="ReadMe.txt">ReadMe.txt</cdfile></programlisting></para>
+ </section>
+
+ <section>
+ <title>Attributes</title>
+
+ <para><variablelist>
+ <varlistentry>
+ <term>base</term>
+
+ <listitem>
+ <para> Put file in this directory on the bootable CD. This
+ attribute is optional.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>nameoncd</term>
+
+ <listitem>
+ <para>Name of file on the bootable CD. This attribute is
+ optional.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist></para>
+ </section>
+
+ <section>
+ <title>Value</title>
+
+ <para>Name of file.</para>
+ </section>
+
+ <section>
+ <title>Elements</title>
+
+ <para>None.</para>
+ </section>
+ </section>
+
+ <section>
+ <title xreflabel="element_component">Component element</title>
+
+ <para>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.</para>
+
+ <section>
+ <title>Syntax</title>
+
+ <para><programlisting><component name="ntdll.dll">
+ ...
+</component></programlisting></para>
+ </section>
+
+ <section>
+ <title>Attributes</title>
+
+ <para><variablelist>
+ <varlistentry>
+ <term>name</term>
+
+ <listitem>
+ <para>Name of library.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist></para>
+ </section>
+
+ <section>
+ <title>Value</title>
+
+ <para>None.</para>
+ </section>
+
+ <section>
+ <title>Elements</title>
+
+ <para><link linkend="element_symbol">symbol</link>.</para>
+ </section>
+ </section>
+
+ <section>
+ <title xreflabel="element_symbol">Symbol element</title>
+
+ <para>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.</para>
+
+ <section>
+ <title>Syntax</title>
+
+ <para><programlisting><symbol newname="RtlAllocateHeap">HeapAlloc@12</symbol></programlisting></para>
+ </section>
+
+ <section>
+ <title>Attributes</title>
+
+ <para><variablelist>
+ <varlistentry>
+ <term>newname</term>
+
+ <listitem>
+ <para>New name of symbol. This attribute is optional.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist></para>
+ </section>
+
+ <section>
+ <title>Value</title>
+
+ <para>Name of symbol.</para>
+ </section>
+
+ <section>
+ <title>Elements</title>
+
+ <para>None.</para>
+ </section>
+ </section>
+
+ <section>
+ <title xreflabel="element_define">Define element</title>
+
+ <para>A define element specifies the name and (optionally) value of a
+ define for the C/C++ compiler and resource compiler.</para>
+
+ <section>
+ <title>Syntax</title>
+
+ <para><programlisting><define name="WINVER">0x501</define></programlisting></para>
+ </section>
+
+ <section>
+ <title>Attributes</title>
+
+ <para><variablelist>
+ <varlistentry>
+ <term>name</term>
+
+ <listitem>
+ <para> Name of define.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist></para>
+ </section>
+
+ <section>
+ <title>Value</title>
+
+ <para>Value of define. The value is optional.</para>
+ </section>
+
+ <section>
+ <title>Elements</title>
+
+ <para>None.</para>
+ </section>
+ </section>
+
+ <section>
+ <title xreflabel="element_dependency">Dependency element</title>
+
+ <para>A dependency element specifies the name of a module (usually of
+ type buildtool) that is to be processed before the current
+ module.</para>
+
+ <section>
+ <title>Syntax</title>
+
+ <para><programlisting><dependency>OtherModule</dependency></programlisting></para>
+ </section>
+
+ <section>
+ <title>Attributes</title>
+
+ <para>None.</para>
+ </section>
+
+ <section>
+ <title>Value</title>
+
+ <para>Name of module.</para>
+ </section>
+
+ <section>
+ <title>Elements</title>
+
+ <para>None.</para>
+ </section>
+ </section>
+
+ <section>
+ <title xreflabel="element_directory">Directory element</title>
+
+ <para>A directory element specifies the name of a subdirectory.</para>
+
+ <section>
+ <title>Syntax</title>
+
+ <para><programlisting><directory name="<replaceable>MyDirectory</replaceable>">
+ ...
+</directory></programlisting></para>
+ </section>
+
+ <section>
+ <title>Attributes</title>
+
+ <para><variablelist>
+ <varlistentry>
+ <term>name</term>
+
+ <listitem>
+ <para>Name of directory.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist></para>
+ </section>
+
+ <section>
+ <title>Value</title>
+
+ <para>None.</para>
+ </section>
+
+ <section>
+ <title>Elements</title>
+
+ <para><link linkend="element_cdfile">cdfile</link>, <link
+ linkend="element_directory">directory</link>, <link
+ linkend="element_file">file</link>, <link
+ linkend="element_if">if</link>, <link
+ linkend="element_property">property</link>.</para>
+ </section>
+ </section>
+
+ <section>
+ <title xreflabel="element_file">File element</title>
+
+ <para>A file element specifies the name of a file that is to be
+ processed.</para>
+
+ <section>
+ <title>Syntax</title>
+
+ <para><programlisting><file><replaceable>MyFile.c</replaceable></file></programlisting></para>
+ </section>
+
+ <section>
+ <title>Attributes</title>
+
+ <para>None.</para>
+ </section>
+
+ <section>
+ <title>Value</title>
+
[truncated at 1000 lines; 1031 more skipped]