31 Jul
2005
31 Jul
'05
7:08 a.m.
Document pch and linkerflag elements.
Rename Elements sections into Children.
Add Parents sections for some elements.
Make link work (tested with DBK=>HTML).
Modified: trunk/reactos/tools/rbuild/doc/rbuild.dbk
_____
Modified: trunk/reactos/tools/rbuild/doc/rbuild.dbk
--- trunk/reactos/tools/rbuild/doc/rbuild.dbk 2005-07-31 07:07:26 UTC
(rev 16914)
+++ trunk/reactos/tools/rbuild/doc/rbuild.dbk 2005-07-31 07:08:15 UTC
(rev 16915)
@@ -83,100 +83,31 @@
<module name="bootcd" type="iso">
</module>
</project></programlisting
</para>
+ </section>
- <section>
- <title>XInclude</title>
+ <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>
+ <para>XML files used by <command>rbuild</command> are modular
and
use
+ XInclude to include other chunks of XML in the top-level
+ <filename>ReactOS.xml</filename> file. The namespace used by
XInclude is
+ <literal>xi</literal>.</para>
- <section>
- <title>xi:include</title>
+ <section id="element.xi.include">
+ <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>
+ <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>
+ <programlisting><xi:include
href="<replaceable>config.xml</replaceable>">
+ <xi:fallback>
+ <xi:include
href="<replaceable>config.template.xml</replaceable>" />
+ </xi:fallback>
+</xi:include></programlisting>
</section>
<section>
@@ -184,21 +115,14 @@
<para><variablelist>
<varlistentry>
- <term>name</term>
+ <term>href</term>
<listitem>
- <para>Name of the project.</para>
+ <para>Name of XML build file to include. The filename
is
+ relative to the location of the current XML build
+ file.</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>
@@ -209,447 +133,31 @@
</section>
<section>
- <title>Elements</title>
+ <title>Children</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>
+ <para><link
linkend="???">xi:fallback</link>.</para>
</section>
</section>
- <section>
- <title xreflabel="element_module">Module element</title>
+ <section id="element.xi.fallback">
+ <title>xi:fallback</title>
- <para>There can be zero or more <sgmltag
- class="element">module</sgmltag>s per XML build
file.</para>
+ <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>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>
+ <programlisting><xi:fallback>
+ <xi:include
href="<replaceable>config.template.xml</replaceable>"
/>
+</xi:fallback></programlisting>
</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>
+
<para>None.</para>
</section>
<section>
@@ -659,26 +167,25 @@
</section>
<section>
- <title>Elements</title>
+ <title>Parents</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>
+ <para><link
linkend="element.xi.include">xi:include</link>.</para>
</section>
+
+ <section>
+ <title>Children</title>
+
+ <para><link
linkend="element.xi.include">xi:include</link>.</para>
+ </section>
</section>
+ </section>
- <section>
- <title xreflabel="element_bootstrap">Bootstrap
element</title>
+ <section>
+ <title>Element reference</title>
+ <section id="element.bootstrap">
+ <title>Bootstrap element</title>
+
<para>A bootstrap element specifies that the generated file
should be
put on the bootable CD as a bootstrap file.</para>
@@ -696,7 +203,7 @@
<term>base</term>
<listitem>
- <para> Put file in this directory on the bootable CD.
This
+ <para>Put file in this directory on the bootable CD.
This
attribute is optional.</para>
</listitem>
</varlistentry>
@@ -705,7 +212,7 @@
<term>nameoncd</term>
<listitem>
- <para> Name of file on the bootable CD. This
attribute is
+ <para>Name of file on the bootable CD. This attribute
is
optional.</para>
</listitem>
</varlistentry>
@@ -719,14 +226,14 @@
</section>
<section>
- <title>Elements</title>
+ <title>Children</title>
<para>None.</para>
</section>
</section>
- <section>
- <title xreflabel="element_cdfile">CDFile element</title>
+ <section id="element.cdfile">
+ <title>CDFile element</title>
<para>A cdfile element specifies the name of a file that is to
be put
on the bootable CD.</para>
@@ -745,7 +252,7 @@
<term>base</term>
<listitem>
- <para> Put file in this directory on the bootable CD.
This
+ <para>Put file in this directory on the bootable CD.
This
attribute is optional.</para>
</listitem>
</varlistentry>
@@ -768,14 +275,14 @@
</section>
<section>
- <title>Elements</title>
+ <title>Children</title>
<para>None.</para>
</section>
</section>
- <section>
- <title xreflabel="element_component">Component
element</title>
+ <section id="element.component">
+ <title>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
@@ -811,62 +318,22 @@
</section>
<section>
- <title>Elements</title>
+ <title>Children</title>
- <para><link
linkend="element_symbol">symbol</link>.</para>
+ <para><link
linkend="element.symbol">symbol</link>.</para>
</section>
</section>
- <section>
- <title xreflabel="element_symbol">Symbol element</title>
+ <section id="element.define">
+ <title>Define 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>
+
<para><programlisting><define
name="<replaceable>WINVER</replaceable>"><replaceable>0x501</replacea
ble></define></programlisting
</para>
</section>
<section>
@@ -877,7 +344,7 @@
<term>name</term>
<listitem>
- <para> Name of define.</para>
+ <para>Name of define.</para>
</listitem>
</varlistentry>
</variablelist </para>
@@
-890,14 +357,14 @@
</section>
<section>
- <title>Elements</title>
+ <title>Children</title>
<para>None.</para>
</section>
</section>
- <section>
- <title xreflabel="element_dependency">Dependency
element</title>
+ <section id="element.dependency">
+ <title>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
@@ -906,7 +373,7 @@
<section>
<title>Syntax</title>
-
<para><programlisting><dependency>OtherModule</dependency></
programlisting </para>
+
<para><programlisting><dependency><replaceable>OtherModule</replac
eable></dependency></programlisting
</para>
</section>
<section>
@@ -922,14 +389,14 @@
</section>
<section>
- <title>Elements</title>
+ <title>Children</title>
<para>None.</para>
</section>
</section>
- <section>
- <title xreflabel="element_directory">Directory
element</title>
+ <section id="element.directory">
+ <title>Directory element</title>
<para>A directory element specifies the name of a
subdirectory.</para>
@@ -962,18 +429,19 @@
</section>
<section>
- <title>Elements</title>
+ <title>Children</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>
+ <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.pch">pch</link>, <link
+ linkend="element.property">property</link>.</para>
</section>
</section>
- <section>
- <title xreflabel="element_file">File element</title>
+ <section id="element.file">
+ <title>File element</title>
<para>A file element specifies the name of a file that is to be
processed.</para>
@@ -997,14 +465,14 @@
</section>
<section>
- <title>Elements</title>
+ <title>Children</title>
<para>None.</para>
</section>
</section>
- <section>
- <title xreflabel="element_if">If element</title>
+ <section id="element.if">
+ <title>If element</title>
<para>An if element allows for conditional processing of other
elements.</para>
@@ -1012,7 +480,7 @@
<section>
<title>Syntax</title>
- <para><programlisting><if property="DBG"
value="1">
+ <para><programlisting><if
property="<replaceable>DBG</replaceable>"
value="<replaceable>1</replaceable>">
...
</if></programlisting
</para>
</section>
@@ -1048,20 +516,20 @@
</section>
<section>
- <title>Elements</title>
+ <title>Children</title>
- <para><link
linkend="element_compilerflag">compilerflag</link>,
- <link linkend="element_define">define</link>, <link
- linkend="element_directory">directory</link>, <link
- linkend="element_file">file</link>, <link
- linkend="element_if">if</link>, <link
- linkend="element_include">include</link>, <link
- linkend="element_property">property</link>.</para>
+ <para><link
linkend="element.compilerflag">compilerflag</link>,
+ <link linkend="element.define">define</link>, <link
+ linkend="element.directory">directory</link>, <link
+ linkend="element.file">file</link>, <link
+ linkend="element.if">if</link>, <link
+ linkend="element.include">include</link>, <link
+ linkend="element.property">property</link>.</para>
</section>
</section>
- <section>
- <title xreflabel="element_importlibrary">Importlibrary
element</title>
+ <section id="element.importlibrary">
+ <title>Importlibrary element</title>
<para>An importlibrary element specifies that an import library
should
be generated which other modules can use to link with the
current
@@ -1097,14 +565,14 @@
</section>
<section>
- <title>Elements</title>
+ <title>Children</title>
<para>None.</para>
</section>
</section>
- <section>
- <title xreflabel="element_include">Include element</title>
+ <section id="element.include">
+ <title>Include element</title>
<para>An include element specifies an include directory for the
C/C++
compiler and resource compiler.</para>
@@ -1126,7 +594,7 @@
<para>Module or project which the value of this
element is
relative to. This attribute is optional. If left out,
the
include directory is relative to the position of the
- top-level xml build file.</para>
+ top-level XML build file.</para>
</listitem>
</varlistentry>
</variablelist </para>
@@
-1139,15 +607,102 @@
</section>
<section>
- <title>Elements</title>
+ <title>Children</title>
<para>None.</para>
</section>
</section>
- <section>
- <title xreflabel="element_installfile">Installfile
element</title>
+ <section id="element.input">
+ <title>Input element</title>
+ <para>An input element specifies a group of filenames that is
to be
+ passed as parameters to a build tool. Input filename parameters
are
+ located after output filename parameters on the command
line.</para>
+
+ <section>
+ <title>Syntax</title>
+
+ <para><programlisting><input>
+ ...
+</input></programlisting
</para>
+ </section>
+
+ <section>
+ <title>Attributes</title>
+
+ <para>None.</para>
+ </section>
+
+ <section>
+ <title>Value</title>
+
+ <para>None.</para>
+ </section>
+
+ <section>
+ <title>Parents</title>
+
+ <para><link
linkend="element.invoke">invoke</link>.</para>
+ </section>
+
+ <section>
+ <title>Children</title>
+
+ <para><link
linkend="element.inputfile">inputfile</link>.</para>
+ </section>
+ </section>
+
+ <section id="element.inputfile">
[truncated at 1000 lines; 952 more skipped]