Create a subdir for rbuild documentation. Move rbuild.txt there. Convert rbuild.txt in Docbook. Fix some minor inconsistencies in the element reference. Added: trunk/reactos/tools/rbuild/doc/ Added: trunk/reactos/tools/rbuild/doc/rbuild.dbk Added: trunk/reactos/tools/rbuild/doc/rbuild.txt Deleted: trunk/reactos/tools/rbuild/rbuild.txt _____
Added: trunk/reactos/tools/rbuild/doc/rbuild.dbk --- 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%22%3E; + <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%22%3E; + ... +</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></par a> + </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]
-
ea＠svn.reactos.com