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%22%3E; - ... -</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]
-
ea＠svn.reactos.com