rbuild.dbk

ReactOS是一些高手根据Windows XP的内核编写出的类XP。内核实现机理和API函数调用几乎相同。甚至可以兼容XP的程序。喜欢研究系统内核的人可以看一看。

<?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: rbuild.dbk 25738 2007-02-06 13:34:47Z greatlrd $</releaseinfo>

    <author>
      <firstname>Casper</firstname>

      <surname>Hornstrup</surname>
    </author>

    <othercredit>
      <firstname>Emanuele</firstname>

      <surname>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.rbuild</filename>) is
      processed by <command>rbuild</command>. The following is an example of
      how it could look like:<programlisting>&lt;?xml version="1.0"?&gt;
&lt;!DOCTYPE project SYSTEM "tools/rbuild/project.dtd"&gt;
&lt;project name="ReactOS" makefile="Makefile.auto" xmlns:xi="http://www.w3.org/2001/XInclude"&gt;
  &lt;xi:include href="config.rbuild"&gt;
    &lt;xi:fallback&gt;
      &lt;xi:include href="config.template.rbuild" /&gt;
    &lt;/xi:fallback&gt;
  &lt;/xi:include&gt;

  &lt;define name="_M_IX86" /&gt;
  &lt;if property="DBG" value="1"&gt;
    &lt;define name="DBG" value="1" /&gt;
    &lt;property name="DBG_OR_KDBG" value="true" /&gt;
  &lt;/if&gt;

  &lt;include base="ReactOS"&gt;include&lt;/include&gt;

  &lt;directory name="boot"&gt;
    &lt;xi:include href="boot/boot.rbuild" /&gt;
  &lt;/directory&gt;

  &lt;module name="bootcd" type="iso"&gt;
  &lt;/module&gt;
&lt;/project&gt;</programlisting></para>
    </section>

    <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
      <filename>ReactOS.rbuild</filename> file. The namespace used by XInclude is
      <literal>xi</literal>.</para>

      <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>

        <section>
          <title>Syntax</title>

          <programlisting>&lt;xi:include href="<replaceable>config.rbuild</replaceable>"&gt;
  &lt;xi:fallback&gt;
    &lt;xi:include href="<replaceable>config.template.rbuild</replaceable>" /&gt;
  &lt;/xi:fallback&gt;
&lt;/xi:include&gt;</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>Content</title>

          <para>None.</para>
        </section>

        <section>
          <title>Children</title>

          <para><link linkend="element.xi.fallback">xi:fallback</link>.</para>
        </section>
      </section>

      <section id="element.xi.fallback">
        <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>Syntax</title>

          <programlisting>&lt;xi:fallback&gt;
  &lt;xi:include href="<replaceable>config.template.rbuild</replaceable>" /&gt;
&lt;/xi:fallback&gt;</programlisting>
        </section>

        <section>
          <title>Attributes</title>

          <para>None.</para>
        </section>

        <section>
          <title>Content</title>

          <para>None.</para>
        </section>

        <section>
          <title>Parents</title>

          <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>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>

        <section>
          <title>Syntax</title>

          <para><programlisting>&lt;bootstrap base="reactos" nameoncd="halmp.dll" /&gt;</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>Content</title>

          <para>None.</para>
        </section>

        <section>
          <title>Parents</title>

          <para><link linkend="element.module">module</link>.</para>
        </section>

        <section>
          <title>Children</title>

          <para>None.</para>
        </section>
      </section>

      <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>

        <section>
          <title>Syntax</title>

          <para><programlisting>&lt;cdfile base="reactos" nameoncd="ReadMe.txt"&gt;ReadMe.txt&lt;/cdfile&gt;</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>Content</title>

          <para>Name of file.</para>
        </section>

        <section>
          <title>Children</title>

          <para>None.</para>
        </section>
      </section>

      <section id="element.compilerflag">
        <title>Compilerflag element</title>

        <para>A compilerflag element specifies additional flags to be bassed
        to the compiler.</para>

        <section>
          <title>Syntax</title>

          <para><programlisting>&lt;compilerflags&gt;<replaceable>-Wpointer-arith</replaceable>&lt;/compilerflag&gt;</programlisting></para>
        </section>

        <section>
          <title>Attributes.</title>

          <para>None.</para>
        </section>

        <section>
          <title>Content</title>

          <para>The compiler flags.</para>
        </section>

        <section>
          <title>Parents</title>

          <para><link linkend="element.if">if</link>, <link
          linkend="element.project">project</link>.</para>
        </section>

        <section>
          <title>Children</title>

          <para>None.</para>
        </section>
      </section>

      <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
        in the library. This element can only be used for modules of type
        test.</para>

        <section>
          <title>Syntax</title>

          <para><programlisting>&lt;component name="ntdll.dll"&gt;
  ...
&lt;/component&gt;</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>Content</title>

          <para>None.</para>
        </section>

        <section>
          <title>Children</title>

          <para><link linkend="element.symbol">symbol</link>.</para>
        </section>
      </section>

      <section id="element.define">
        <title>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>&lt;define name="<replaceable>WINVER</replaceable>"&gt;<replaceable>0x501</replaceable>&lt;/define&gt;</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>Content</title>

          <para>Value of define. The value is optional.</para>
        </section>

        <section>
          <title>Parents</title>

          <para><link linkend="element.project">project</link>, <link
          linkend="element.module">module</link>.</para>
        </section>

        <section>
          <title>Children</title>

          <para>None.</para>
        </section>
      </section>

      <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
        module.</para>

        <section>
          <title>Syntax</title>

          <para><programlisting>&lt;dependency&gt;<replaceable>OtherModule</replaceable>&lt;/dependency&gt;</programlisting></para>
        </section>

        <section>
          <title>Attributes</title>

          <para>None.</para>
        </section>

        <section>
          <title>Content</title>

          <para>Name of module.</para>
        </section>

        <section>
          <title>Children</title>

          <para>None.</para>
        </section>
      </section>

      <section id="element.directory">
        <title>Directory element</title>