reactos/tools/rbuild/doc/rbuild.dbk

   1 <?xml version="1.0" encoding="US-ASCII"?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
   3 "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
   4 <book>
   5   <title>ReactOS Build System Documentation</title>
   6
   7   <bookinfo>
   8     <releaseinfo>$Id$</releaseinfo>
   9
  10     <author>
  11       <firstname>Casper</firstname>
  12
  13       <surname>Hornstrup</surname>
  14     </author>
  15
  16     <othercredit>
  17       <surname>Emanuele Aliberti</surname>
  18     </othercredit>
  19
  20     <copyright>
  21       <year>2005</year>
  22     </copyright>
  23   </bookinfo>
  24
  25   <chapter>
  26     <title>Building ReactOS</title>
  27
  28     <section>
  29       <title>Building ReactOS</title>
  30
  31       <para>To generate GNU make makefiles and building ReactOS, do the
  32       following:<orderedlist>
  33           <listitem>
  34             <para>Go to the top-level <filename>reactos</filename>
  35             directory;</para>
  36           </listitem>
  37
  38           <listitem>
  39             <para>Run the command:<screen>mingw32-make</screen></para>
  40
  41             <para>This will start building ReactOS.</para>
  42           </listitem>
  43         </orderedlist></para>
  44
  45       <para>To build a bootable CD, run the following command:<screen>mingw32-make bootcd</screen>This
  46       will create <filename>ReactOS.iso</filename> in the top-level
  47       <filename>reactos</filename> directory.</para>
  48     </section>
  49   </chapter>
  50
  51   <chapter>
  52     <title>How build directions are stored</title>
  53
  54     <para>XML files are used throughout the ReactOS source tree to drive the
  55     build system.</para>
  56
  57     <section>
  58       <title>Top-level XML Build File</title>
  59
  60       <para>The top-level XML build file (<filename>ReactOS.xml</filename>) is
  61       processed by <command>rbuild</command>. The following is an example of
  62       how it could look like:<programlisting>&lt;?xml version="1.0"?&gt;
  63 &lt;!DOCTYPE project SYSTEM "tools/rbuild/project.dtd"&gt;
  64 &lt;project name="ReactOS" makefile="Makefile.auto" xmlns:xi="http://www.w3.org/2001/XInclude"&gt;
  65   &lt;xi:include href="config.xml"&gt;
  66     &lt;xi:fallback&gt;
  67       &lt;xi:include href="config.template.xml" /&gt;
  68     &lt;/xi:fallback&gt;
  69   &lt;/xi:include&gt;
  70
  71   &lt;define name="_M_IX86" /&gt;
  72   &lt;if property="DBG" value="1"&gt;
  73     &lt;define name="DBG" value="1" /&gt;
  74     &lt;property name="DBG_OR_KDBG" value="true" /&gt;
  75   &lt;/if&gt;
  76
  77   &lt;include base="ReactOS"&gt;include&lt;/include&gt;
  78
  79   &lt;directory name="boot"&gt;
  80     &lt;xi:include href="boot/boot.xml" /&gt;
  81   &lt;/directory&gt;
  82
  83   &lt;module name="bootcd" type="iso"&gt;
  84   &lt;/module&gt;
  85 &lt;/project&gt;</programlisting></para>
  86     </section>
  87
  88     <section>
  89       <title>XInclude</title>
  90
  91       <para>XML files used by <command>rbuild</command> are modular and use
  92       XInclude to include other chunks of XML in the top-level
  93       <filename>ReactOS.xml</filename> file. The namespace used by XInclude is
  94       <literal>xi</literal>.</para>
  95
  96       <section id="element.xi.include">
  97         <title>xi:include</title>
  98
  99         <para>It is possible to split an XML build file over several files.
 100         The include element in the <literal>xi</literal> namespace is used to
 101         accomplish this.</para>
 102
 103         <section>
 104           <title>Syntax</title>
 105
 106           <programlisting>&lt;xi:include href="<replaceable>config.xml</replaceable>"&gt;
 107   &lt;xi:fallback&gt;
 108     &lt;xi:include href="<replaceable>config.template.xml</replaceable>" /&gt;
 109   &lt;/xi:fallback&gt;
 110 &lt;/xi:include&gt;</programlisting>
 111         </section>
 112
 113         <section>
 114           <title>Attributes</title>
 115
 116           <para><variablelist>
 117               <varlistentry>
 118                 <term>href</term>
 119
 120                 <listitem>
 121                   <para>Name of XML build file to include. The filename is
 122                   relative to the location of the current XML build
 123                   file.</para>
 124                 </listitem>
 125               </varlistentry>
 126             </variablelist></para>
 127         </section>
 128
 129         <section>
 130           <title>Value</title>
 131
 132           <para>None.</para>
 133         </section>
 134
 135         <section>
 136           <title>Children</title>
 137
 138           <para><link linkend="???">xi:fallback</link>.</para>
 139         </section>
 140       </section>
 141
 142       <section id="element.xi.fallback">
 143         <title>xi:fallback</title>
 144
 145         <para>This element is used to provide the name of an alternate file
 146         that is to be included if the first include file did not
 147         exists.</para>
 148
 149         <section>
 150           <title>Syntax</title>
 151
 152           <programlisting>&lt;xi:fallback&gt;
 153   &lt;xi:include href="<replaceable>config.template.xml</replaceable>" /&gt;
 154 &lt;/xi:fallback&gt;</programlisting>
 155         </section>
 156
 157         <section>
 158           <title>Attributes</title>
 159
 160           <para>None.</para>
 161         </section>
 162
 163         <section>
 164           <title>Value</title>
 165
 166           <para>None.</para>
 167         </section>
 168
 169         <section>
 170           <title>Parents</title>
 171
 172           <para><link linkend="element.xi.include">xi:include</link>.</para>
 173         </section>
 174
 175         <section>
 176           <title>Children</title>
 177
 178           <para><link linkend="element.xi.include">xi:include</link>.</para>
 179         </section>
 180       </section>
 181     </section>
 182
 183     <section>
 184       <title>Element reference</title>
 185
 186       <section id="element.bootstrap">
 187         <title>Bootstrap element</title>
 188
 189         <para>A bootstrap element specifies that the generated file should be
 190         put on the bootable CD as a bootstrap file.</para>
 191
 192         <section>
 193           <title>Syntax</title>
 194
 195           <para><programlisting>&lt;bootstrap base="reactos" nameoncd="halmp.dll" /&gt;</programlisting></para>
 196         </section>
 197
 198         <section>
 199           <title>Attributes</title>
 200
 201           <para><variablelist>
 202               <varlistentry>
 203                 <term>base</term>
 204
 205                 <listitem>
 206                   <para>Put file in this directory on the bootable CD. This
 207                   attribute is optional.</para>
 208                 </listitem>
 209               </varlistentry>
 210
 211               <varlistentry>
 212                 <term>nameoncd</term>
 213
 214                 <listitem>
 215                   <para>Name of file on the bootable CD. This attribute is
 216                   optional.</para>
 217                 </listitem>
 218               </varlistentry>
 219             </variablelist></para>
 220         </section>
 221
 222         <section>
 223           <title>Value</title>
 224
 225           <para>None.</para>
 226         </section>
 227
 228         <section>
 229           <title>Children</title>
 230
 231           <para>None.</para>
 232         </section>
 233       </section>
 234
 235       <section id="element.cdfile">
 236         <title>CDFile element</title>
 237
 238         <para>A cdfile element specifies the name of a file that is to be put
 239         on the bootable CD.</para>
 240
 241         <section>
 242           <title>Syntax</title>
 243
 244           <para><programlisting>&lt;cdfile base="reactos" nameoncd="ReadMe.txt"&gt;ReadMe.txt&lt;/cdfile&gt;</programlisting></para>
 245         </section>
 246
 247         <section>
 248           <title>Attributes</title>
 249
 250           <para><variablelist>
 251               <varlistentry>
 252                 <term>base</term>
 253
 254                 <listitem>
 255                   <para>Put file in this directory on the bootable CD. This
 256                   attribute is optional.</para>
 257                 </listitem>
 258               </varlistentry>
 259
 260               <varlistentry>
 261                 <term>nameoncd</term>
 262
 263                 <listitem>
 264                   <para>Name of file on the bootable CD. This attribute is
 265                   optional.</para>
 266                 </listitem>
 267               </varlistentry>
 268             </variablelist></para>
 269         </section>
 270
 271         <section>
 272           <title>Value</title>
 273
 274           <para>Name of file.</para>
 275         </section>
 276
 277         <section>
 278           <title>Children</title>
 279
 280           <para>None.</para>
 281         </section>
 282       </section>
 283
 284       <section id="element.component">
 285         <title>Component element</title>
 286
 287         <para>A component element specifies that imports from a library are to
 288         be stubbed so tests can be run without actually calling the functions
 289         in the library. This element can only be used for modules of type
 290         test.</para>
 291
 292         <section>
 293           <title>Syntax</title>
 294
 295           <para><programlisting>&lt;component name="ntdll.dll"&gt;
 296   ...
 297 &lt;/component&gt;</programlisting></para>
 298         </section>
 299
 300         <section>
 301           <title>Attributes</title>
 302
 303           <para><variablelist>
 304               <varlistentry>
 305                 <term>name</term>
 306
 307                 <listitem>
 308                   <para>Name of library.</para>
 309                 </listitem>
 310               </varlistentry>
 311             </variablelist></para>
 312         </section>
 313
 314         <section>
 315           <title>Value</title>
 316
 317           <para>None.</para>
 318         </section>
 319
 320         <section>
 321           <title>Children</title>
 322
 323           <para><link linkend="element.symbol">symbol</link>.</para>
 324         </section>
 325       </section>
 326
 327       <section id="element.define">
 328         <title>Define element</title>
 329
 330         <para>A define element specifies the name and (optionally) value of a
 331         define for the C/C++ compiler and resource compiler.</para>
 332
 333         <section>
 334           <title>Syntax</title>
 335
 336           <para><programlisting>&lt;define name="<replaceable>WINVER</replaceable>"&gt;<replaceable>0x501</replaceable>&lt;/define&gt;</programlisting></para>
 337         </section>
 338
 339         <section>
 340           <title>Attributes</title>
 341
 342           <para><variablelist>
 343               <varlistentry>
 344                 <term>name</term>
 345
 346                 <listitem>
 347                   <para>Name of define.</para>
 348                 </listitem>
 349               </varlistentry>
 350             </variablelist></para>
 351         </section>
 352
 353         <section>
 354           <title>Value</title>
 355
 356           <para>Value of define. The value is optional.</para>
 357         </section>
 358
 359         <section>
 360           <title>Children</title>
 361
 362           <para>None.</para>
 363         </section>
 364       </section>
 365
 366       <section id="element.dependency">
 367         <title>Dependency element</title>
 368
 369         <para>A dependency element specifies the name of a module (usually of
 370         type buildtool) that is to be processed before the current
 371         module.</para>
 372
 373         <section>
 374           <title>Syntax</title>
 375
 376           <para><programlisting>&lt;dependency&gt;<replaceable>OtherModule</replaceable>&lt;/dependency&gt;</programlisting></para>
 377         </section>
 378
 379         <section>
 380           <title>Attributes</title>
 381
 382           <para>None.</para>
 383         </section>
 384
 385         <section>
 386           <title>Value</title>
 387
 388           <para>Name of module.</para>
 389         </section>
 390
 391         <section>
 392           <title>Children</title>
 393
 394           <para>None.</para>
 395         </section>
 396       </section>
 397
 398       <section id="element.directory">
 399         <title>Directory element</title>
 400
 401         <para>A directory element specifies the name of a subdirectory.</para>
 402
 403         <section>
 404           <title>Syntax</title>
 405
 406           <para><programlisting>&lt;directory name="<replaceable>MyDirectory</replaceable>"&gt;
 407   ...
 408 &lt;/directory&gt;</programlisting></para>
 409         </section>
 410
 411         <section>
 412           <title>Attributes</title>
 413
 414           <para><variablelist>
 415               <varlistentry>
 416                 <term>name</term>
 417
 418                 <listitem>
 419                   <para>Name of directory.</para>
 420                 </listitem>
 421               </varlistentry>
 422             </variablelist></para>
 423         </section>
 424
 425         <section>
 426           <title>Value</title>
 427
 428           <para>None.</para>
 429         </section>
 430
 431         <section>
 432           <title>Children</title>
 433
 434           <para><link linkend="element.cdfile">cdfile</link>, <link
 435           linkend="element.directory">directory</link>, <link
 436           linkend="element.file">file</link>, <link
 437           linkend="element.if">if</link>, <link
 438           linkend="element.pch">pch</link>, <link
 439           linkend="element.property">property</link>.</para>
 440         </section>
 441       </section>
 442
 443       <section id="element.file">
 444         <title>File element</title>
 445
 446         <para>A file element specifies the name of a file that is to be
 447         processed.</para>
 448
 449         <section>
 450           <title>Syntax</title>
 451
 452           <para><programlisting>&lt;file&gt;<replaceable>MyFile.c</replaceable>&lt;/file&gt;</programlisting></para>
 453         </section>
 454
 455         <section>
 456           <title>Attributes</title>
 457
 458           <para>None.</para>
 459         </section>
 460
 461         <section>
 462           <title>Value</title>
 463
 464           <para>Name of file.</para>
 465         </section>
 466
 467         <section>
 468           <title>Children</title>
 469
 470           <para>None.</para>
 471         </section>
 472       </section>
 473
 474       <section id="element.if">
 475         <title>If element</title>
 476
 477         <para>An if element allows for conditional processing of other
 478         elements.</para>
 479
 480         <section>
 481           <title>Syntax</title>
 482
 483           <para><programlisting>&lt;if property="<replaceable>DBG</replaceable>" value="<replaceable>1</replaceable>"&gt;
 484   ...
 485 &lt;/if&gt;</programlisting></para>
 486         </section>
 487
 488         <section>
 489           <title>Attributes</title>
 490
 491           <para><variablelist>
 492               <varlistentry>
 493                 <term>property</term>
 494
 495                 <listitem>
 496                   <para>Name of the property that is to be evaluated.</para>
 497                 </listitem>
 498               </varlistentry>
 499
 500               <varlistentry>
 501                 <term>value</term>
 502
 503                 <listitem>
 504                   <para>Value to compare to the value of the property. If the
 505                   property has the specified value, then the subelements are
 506                   processed.</para>
 507                 </listitem>
 508               </varlistentry>
 509             </variablelist></para>
 510         </section>
 511
 512         <section>
 513           <title>Value</title>
 514
 515           <para>None.</para>
 516         </section>
 517
 518         <section>
 519           <title>Children</title>
 520
 521           <para><link linkend="element.compilerflag">compilerflag</link>,
 522           <link linkend="element.define">define</link>, <link
 523           linkend="element.directory">directory</link>, <link
 524           linkend="element.file">file</link>, <link
 525           linkend="element.if">if</link>, <link
 526           linkend="element.include">include</link>, <link
 527           linkend="element.property">property</link>.</para>
 528         </section>
 529       </section>
 530
 531       <section id="element.importlibrary">
 532         <title>Importlibrary element</title>
 533
 534         <para>An importlibrary element specifies that an import library should
 535         be generated which other modules can use to link with the current
 536         module.</para>
 537
 538         <section>
 539           <title>Syntax</title>
 540
 541           <para><programlisting>&lt;importlibrary definition="<replaceable>MyModule.def</replaceable>" /&gt;</programlisting></para>
 542         </section>
 543
 544         <section>
 545           <title>Attributes</title>
 546
 547           <para><variablelist>
 548               <varlistentry>
 549                 <term>definition</term>
 550
 551                 <listitem>
 552                   <para>Filename of definition file
 553                   (<filename>.def</filename>) used to generate the import
 554                   library. The filename is relative to the current
 555                   module.</para>
 556                 </listitem>
 557               </varlistentry>
 558             </variablelist></para>
 559         </section>
 560
 561         <section>
 562           <title>Value</title>
 563
 564           <para>None.</para>
 565         </section>
 566
 567         <section>
 568           <title>Children</title>
 569
 570           <para>None.</para>
 571         </section>
 572       </section>
 573
 574       <section id="element.include">
 575         <title>Include element</title>
 576
 577         <para>An include element specifies an include directory for the C/C++
 578         compiler and resource compiler.</para>
 579
 580         <section>
 581           <title>Syntax</title>
 582
 583           <para><programlisting>&lt;include base="<replaceable>MyLibraryModule</replaceable>"&gt;<replaceable>include</replaceable>&lt;/include&gt;</programlisting></para>
 584         </section>
 585
 586         <section>
 587           <title>Attributes</title>
 588
 589           <para><variablelist>
 590               <varlistentry>
 591                 <term>base</term>
 592
 593                 <listitem>
 594                   <para>Module or project which the value of this element is
 595                   relative to. This attribute is optional. If left out, the
 596                   include directory is relative to the position of the
 597                   top-level XML build file.</para>
 598                 </listitem>
 599               </varlistentry>
 600             </variablelist></para>
 601         </section>
 602
 603         <section>
 604           <title>Value</title>
 605
 606           <para>Relative include directory.</para>
 607         </section>
 608
 609         <section>
 610           <title>Children</title>
 611
 612           <para>None.</para>
 613         </section>
 614       </section>
 615
 616       <section id="element.input">
 617         <title>Input element</title>
 618
 619         <para>An input element specifies a group of filenames that is to be
 620         passed as parameters to a build tool. Input filename parameters are
 621         located after output filename parameters on the command line.</para>
 622
 623         <section>
 624           <title>Syntax</title>
 625
 626           <para><programlisting>&lt;input&gt;
 627   ...
 628 &lt;/input&gt;</programlisting></para>
 629         </section>
 630
 631         <section>
 632           <title>Attributes</title>
 633
 634           <para>None.</para>
 635         </section>
 636
 637         <section>
 638           <title>Value</title>
 639
 640           <para>None.</para>
 641         </section>
 642
 643         <section>
 644           <title>Parents</title>
 645
 646           <para><link linkend="element.invoke">invoke</link>.</para>
 647         </section>
 648
 649         <section>
 650           <title>Children</title>
 651
 652           <para><link linkend="element.inputfile">inputfile</link>.</para>
 653         </section>
 654       </section>
 655
 656       <section id="element.inputfile">
 657         <title>Inputfile element</title>
 658
 659         <para>An inputfile element specifies a filename that is to be passed
 660         as a parameter to a build tool.</para>
 661
 662         <section>
 663           <title>Syntax</title>
 664
 665           <para><programlisting>&lt;inputfile&gt;<replaceable>ntoskrnl.mc</replaceable>&lt;/inputfile&gt;</programlisting></para>
 666         </section>
 667
 668         <section>
 669           <title>Attributes</title>
 670
 671           <para><variablelist>
 672               <varlistentry>
 673                 <term>switches</term>
 674
 675                 <listitem>
 676                   <para>Switches that is passed as parameters just before the
 677                   filename. This attribute is optional.</para>
 678                 </listitem>
 679               </varlistentry>
 680             </variablelist></para>
 681         </section>
 682
 683         <section>
 684           <title>Value</title>
 685
 686           <para>Name of file that is to be passed as a parameter to the build
 687           tool.</para>
 688         </section>
 689
 690         <section>
 691           <title>Parents</title>
 692
 693           <para><link linkend="element.input">input</link>.</para>
 694         </section>
 695
 696         <section>
 697           <title>Children</title>
 698
 699           <para>None.</para>
 700         </section>
 701       </section>
 702
 703       <section id="element.installfile">
 704         <title>Installfile element</title>
 705
 706         <para>An installfile element specifies the name of a file that is to
 707         be installed when using '<command>make install</command>'.</para>
 708
 709         <section>
 710           <title>Syntax</title>
 711
 712           <para><programlisting>&lt;installfile base="<replaceable>reactos</replaceable>" newname="<replaceable>ReadMe.txt</replaceable>"&gt;<replaceable>ReadMe.txt</replaceable>&lt;/installfile&gt;</programlisting></para>
 713         </section>
 714
 715         <section>
 716           <title>Attributes</title>
 717
 718           <para><variablelist>
 719               <varlistentry>
 720                 <term>base</term>
 721
 722                 <listitem>
 723                   <para>Put file in this directory within the install
 724                   directory. This attribute is optional.</para>
 725                 </listitem>
 726               </varlistentry>
 727
 728               <varlistentry>
 729                 <term>newname</term>
 730
 731                 <listitem>
 732                   <para>Name of file within the install directory. This
 733                   attribute is optional.</para>
 734                 </listitem>
 735               </varlistentry>
 736             </variablelist></para>
 737         </section>
 738
 739         <section>
 740           <title>Value</title>
 741
 742           <para>Name of file.</para>
 743         </section>
 744
 745         <section>
 746           <title>Children</title>
 747
 748           <para>None.</para>
 749         </section>
 750       </section>
 751
 752       <section id="element.invoke">
 753         <title>Invoke element</title>
 754
 755         <para>An invoke element specifies the name of a module which is to be
 756         executed before the current module is processed.</para>
 757
 758         <section>
 759           <title>Syntax</title>
 760
 761           <para><programlisting>&lt;invoke module="<replaceable>wmc</replaceable>"&gt;
 762   &lt;input&gt;
 763     &lt;inputfile&gt;<replaceable>ntoskrnl.mc</replaceable>&lt;/inputfile&gt;
 764   &lt;/input&gt;
 765   &lt;output&gt;
 766     &lt;outputfile switches="<replaceable>-H</replaceable>"&gt;<replaceable>../include/reactos/bugcodes.h</replaceable>&lt;/outputfile&gt;
 767     &lt;outputfile switches="<replaceable>-o</replaceable>"&gt;<replaceable>bugcodes.rc</replaceable>&lt;/outputfile&gt;
 768   &lt;/output&gt;
 769 &lt;/invoke&gt;</programlisting></para>
 770         </section>
 771
 772         <section>
 773           <title>Attributes</title>
 774
 775           <para><variablelist>
 776               <varlistentry>
 777                 <term>module</term>
 778
 779                 <listitem>
 780                   <para>Name of the module to execute.</para>
 781                 </listitem>
 782               </varlistentry>
 783             </variablelist></para>
 784         </section>
 785
 786         <section>
 787           <title>Value</title>
 788
 789           <para>None.</para>
 790         </section>
 791
 792         <section>
 793           <title>Children</title>
 794
 795           <para><link linkend="element.input">input</link>, <link
 796           linkend="element.output">output</link>.</para>
 797         </section>
 798       </section>
 799
 800       <section id="element.library">
 801         <title>Library element</title>
 802
 803         <para>A library element specifies the name of another module which is
 804         to be linked with the current module.</para>
 805
 806         <section>
 807           <title>Syntax</title>
 808
 809           <para><programlisting>&lt;library&gt;<replaceable>MyLibraryModule</replaceable>&lt;/library&gt;</programlisting></para>
 810         </section>
 811
 812         <section>
 813           <title>Attributes</title>
 814
 815           <para>None.section</para>
 816         </section>
 817
 818         <section>
 819           <title>Parents</title>
 820
 821           <para><link linkend="element.module">module</link>.</para>
 822         </section>
 823
 824         <section>
 825           <title>Children</title>
 826
 827           <para>None.</para>
 828         </section>
 829       </section>
 830
 831       <section id="element.linkerflag">
 832         <title>Linkerflag element</title>
 833
 834         <para>A likerflag element specifies flags to be passed to the linker
 835         tool.</para>
 836
 837         <section>
 838           <title>Syntax</title>
 839
 840           <para><programlisting>&lt;linkerflag&gt;<replaceable>-lgcc</replaceable>&lt;/linkerflag&gt;</programlisting></para>
 841         </section>
 842
 843         <section>
 844           <title>Attributes</title>
 845
 846           <para>None.</para>
 847         </section>
 848
 849         <section>
 850           <title>Value</title>
 851
 852           <para>The switches to pass to the linker.</para>
 853         </section>
 854
 855         <section>
 856           <title>Children</title>
 857
 858           <para>None.</para>
 859         </section>
 860       </section>
 861
 862       <section id="element.module">
 863         <title>Module element</title>
 864
 865         <para>There can be zero or more <sgmltag
 866         class="element">module</sgmltag>s per XML build file.</para>
 867
 868         <section>
 869           <title>Syntax</title>
 870
 871           <para><programlisting>&lt;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"&gt;
 872   ...
 873 &lt;/module&gt;</programlisting></para>
 874         </section>
 875
 876         <section>
 877           <title>Attributes</title>
 878
 879           <para><variablelist>
 880               <varlistentry>
 881                 <term>if</term>
 882
 883                 <listitem>
 884                   <para>If the value is 1, then the module is enabled,
 885                   otherwise it is disabled. A disabled module is not
 886                   processed.</para>
 887                 </listitem>
 888               </varlistentry>
 889
 890               <varlistentry>
 891                 <term>ifnot</term>
 892
 893                 <listitem>
 894                   <para>If the value is 1, then the module is disabled,
 895                   otherwise it is enabled. A disabled module is not
 896                   processed.</para>
 897                 </listitem>
 898               </varlistentry>
 899
 900               <varlistentry>
 901                 <term>name</term>
 902
 903                 <listitem>
 904                   <para>Name of the module. Also the base name of the
 905                   generated file if such file is generated for the particular
 906                   module type.</para>
 907                 </listitem>
 908               </varlistentry>
 909
 910               <varlistentry>
 911                 <term>type</term>
 912
 913                 <listitem>
 914                   <para>Type of module. See below for an explanation of module
 915                   types. <emphasis><emphasis>The module type determines the
 916                   actions that is to be carried out to process the module. The
 917                   defined module types are seen
 918                   below:</emphasis></emphasis></para>
 919
 920                   <table>
 921                     <title>Module Types</title>
 922
 923                     <tgroup cols="6">
 924                       <thead>
 925                         <row>
 926                           <entry>Value</entry>
 927
 928                           <entry>Output name suffix</entry>
 929
 930                           <entry>Entrypoint</entry>
 931
 932                           <entry>Baseaddress</entry>
 933
 934                           <entry>Mangledsymbols</entry>
 935
 936                           <entry>Description</entry>
 937                         </row>
 938                       </thead>
 939
 940                       <tbody>
 941                         <row>
 942                           <entry>buildtool</entry>
 943
 944                           <entrytbl cols="2">
 945                             <tbody>
 946                               <row>
 947                                 <entry><filename>.exe</filename> (Windows)</entry>
 948
 949                                 <entry>none (Linux)</entry>
 950                               </row>
 951                             </tbody>
 952                           </entrytbl>
 953
 954                           <entry>-</entry>
 955
 956                           <entry>-</entry>
 957
 958                           <entry>-</entry>
 959
 960                           <entry>Builds a tool that can be run (invoked) when
 961                           building ReactOS.</entry>
 962                         </row>
 963
 964                         <row>
 965                           <entry>staticlibrary</entry>
 966
 967                           <entry><filename>.a</filename></entry>
 968
 969                           <entry>-</entry>
 970
 971                           <entry>-</entry>
 972
 973                           <entry>-</entry>
 974
 975                           <entry>Builds a static library containing object
 976                           files that can be linked together with other
 977                           modules.</entry>
 978                         </row>
 979
 980                         <row>
 981                           <entry>objectlibrary</entry>
 982
 983                           <entry><filename>.o</filename></entry>
 984
 985                           <entry>-</entry>
 986
 987                           <entry>-</entry>
 988
 989                           <entry>-</entry>
 990
 991                           <entry>Builds object files that can be linked
 992                           together with other modules.</entry>
 993                         </row>
 994
 995                         <row>
 996                           <entry>kernel</entry>
 997
 998                           <entry><filename>.exe</filename></entry>
 999
1000                           <entry><function>_NtProcessStartup</function></entry>
1001
1002                           <entry>-</entry>
1003
1004                           <entry>-</entry>
1005
1006                           <entry>Builds
1007                           <filename>ntoskrnl.exe</filename>.</entry>
1008                         </row>
1009
1010                         <row>
1011                           <entry>kernelmodedll</entry>
1012
1013                           <entry><filename>.dll</filename></entry>
1014
1015                           <entry><function>_DriverEntry@8</function></entry>
1016
1017                           <entry>-</entry>
1018
1019                           <entry>-</entry>
1020
1021                           <entry>Builds a kernel-mode DLL.</entry>
1022                         </row>
1023
1024                         <row>
1025                           <entry>kernelmodedriver</entry>
1026
1027                           <entry><filename>.sys</filename></entry>
1028
1029                           <entry><function>_DriverEntry@8</function></entry>
1030
1031                           <entry>-</entry>
1032
1033                           <entry>-</entry>
1034
1035                           <entry>Builds a kernel-mode driver.</entry>
1036                         </row>
1037
1038                         <row>
1039                           <entry>nativedll</entry>
1040
1041                           <entry><filename>.dll</filename></entry>
1042
1043                           <entry><function>_DllMainCRTStartup@12</function></entry>
1044
1045                           <entry>-</entry>
1046
1047                           <entry>-</entry>
1048
1049                           <entry>Builds a native DLL.</entry>
1050                         </row>
1051
1052                         <row>
1053                           <entry>win32dll</entry>
1054
1055                           <entry><filename>.dll</filename></entry>
1056
1057                           <entry><function>_DllMain@12</function></entry>
1058
1059                           <entry>-</entry>
1060
1061                           <entry>-</entry>
1062
1063                           <entry>Builds a Win32 DLL.</entry>
1064                         </row>
1065
1066                         <row>
1067                           <entry>win32cui</entry>
1068
1069                           <entry><filename>.exe</filename></entry>
1070
1071                           <entry><function>_mainCRTStartup</function></entry>
1072
1073                           <entry>-</entry>
1074
1075                           <entry>-</entry>
1076
1077                           <entry>Builds a Win32 console executable.</entry>
1078                         </row>
1079
1080                         <row>
1081                           <entry>win32gui</entry>
1082
1083                           <entry><filename>.exe</filename></entry>
1084
1085                           <entry><function>_WinMainCRTStartup</function></entry>
1086
1087                           <entry>-</entry>
1088
1089                           <entry>-</entry>
1090
1091                           <entry>Builds a Win32 GUI executable.</entry>
1092                         </row>
1093
1094                         <row>
1095                           <entry>bootloader</entry>
1096
1097                           <entry>-</entry>
1098
1099                           <entry>-</entry>
1100
1101                           <entry>-</entry>
1102
1103                           <entry>-</entry>
1104
1105                           <entry>Builds a bootloader.</entry>
1106                         </row>
1107
1108                         <row>
1109                           <entry>bootsector</entry>
1110
1111                           <entry>-</entry>
1112
1113                           <entry>-</entry>
1114
1115                           <entry>-</entry>
1116
1117                           <entry>-</entry>
1118
1119                           <entry>Builds one or more bootsector
1120                           binaries.</entry>
1121                         </row>
1122
1123                         <row>
1124                           <entry>iso</entry>
1125
1126                           <entry>-</entry>
1127
1128                           <entry>-</entry>
1129
1130                           <entry>-</entry>
1131
1132                           <entry>-.</entry>
1133
1134                           <entry>Builds a bootable CD.</entry>
1135                         </row>
1136
1137                         <row>
1138                           <entry>test</entry>
1139
1140                           <entry>.exe</entry>
1141
1142                           <entry>_mainCRTStartup</entry>
1143
1144                           <entry>-</entry>
1145
1146                           <entry>-</entry>
1147
1148                           <entry>Builds a testsuite.</entry>
1149                         </row>
1150
1151                         <row>
1152                           <entry>rpcserver</entry>
1153
1154                           <entry><filename>.o</filename></entry>
1155
1156                           <entry>-</entry>
1157
1158                           <entry>-</entry>
1159
1160                           <entry>-</entry>
1161
1162                           <entry>Generates and builds server code for an RPC
1163                           interface.</entry>
1164                         </row>
1165
1166                         <row>
1167                           <entry>rpcclient</entry>
1168
1169                           <entry><filename>.o</filename></entry>
1170
1171                           <entry>-</entry>
1172
1173                           <entry>-</entry>
1174
1175                           <entry>-</entry>
1176
1177                           <entry>Generates and builds client code for an RPC
1178                           interface.</entry>
1179                         </row>
1180
1181                         <row>
1182                           <entry>alias</entry>
1183
1184                           <entry>-</entry>
1185
1186                           <entry>-</entry>
1187
1188                           <entry>-</entry>
1189
1190                           <entry>-</entry>
1191
1192                           <entry>Module is an alias for another module. This
1193                           module type is the only module type for which the
1194                           aliasof attribute is applicable. Only the module
1195                           install functionality is aliased.</entry>
1196                         </row>
1197                       </tbody>
1198                     </tgroup>
1199                   </table>
1200                 </listitem>
1201               </varlistentry>
1202
1203               <varlistentry>
1204                 <term>extension</term>
1205
1206                 <listitem>
1207                   <para>Extension of the generated file if such file is
1208                   generated for the particular module type.</para>
1209                 </listitem>
1210               </varlistentry>
1211
1212               <varlistentry>
1213                 <term>entrypoint</term>
1214
1215                 <listitem>
1216                   <para>Entrypoint symbol of the generated file if such file
1217                   is generated for the particular module type.</para>
1218                 </listitem>
1219               </varlistentry>
1220
1221               <varlistentry>
1222                 <term>baseaddress</term>
1223
1224                 <listitem>
1225                   <para>Base address of the generated file if such file is
1226                   generated for the particular module type.</para>
1227                 </listitem>
1228               </varlistentry>
1229
1230               <varlistentry>
1231                 <term>mangledsymbols</term>
1232
1233                 <listitem>
1234                   <para>Controls wether or not to pass --kill-at to dlltool.
1235                   If this attribute has the value false then --kill-at is
1236                   passed to dlltool. If the value is true, then --kill-at is
1237                   not passed to dlltool. If the generated file exports C++
1238                   classes then this need to be true.</para>
1239                 </listitem>
1240               </varlistentry>
1241
1242               <varlistentry>
1243                 <term>installbase</term>
1244
1245                 <listitem>
1246                   <para>Base directory of the generated file in the
1247                   installation directory. This attribute is optional.</para>
1248                 </listitem>
1249               </varlistentry>
1250
1251               <varlistentry>
1252                 <term>installname</term>
1253
1254                 <listitem>
1255                   <para>Name of generated file in the installation directory.
1256                   This attribute is optional, but if not specified, the
1257                   generated file is not copied to the installation
1258                   directory.</para>
1259                 </listitem>
1260               </varlistentry>
1261
1262               <varlistentry>
1263                 <term>usewrc</term>
1264
1265                 <listitem>
1266                   <para>Use WRC to compile resources if true. If false,
1267                   windres is used. This attribute is optional. If not
1268                   specified, WRC will be used.</para>
1269                 </listitem>
1270               </varlistentry>
1271
1272               <varlistentry>
1273                 <term>warnings</term>
1274
1275                 <listitem>
1276                   <para>Error out if false and at least one warning is emitted
1277                   during building of this module. This attribute is optional.
1278                   If not specified, it is assumed to be false.</para>
1279                 </listitem>
1280               </varlistentry>
1281
1282               <varlistentry>
1283                 <term>aliasof</term>
1284
1285                 <listitem>
1286                   <para>Name of module that is aliased.</para>
1287                 </listitem>
1288               </varlistentry>
1289             </variablelist></para>
1290         </section>
1291
1292         <section>
1293           <title>Value</title>
1294
1295           <para>None.</para>
1296         </section>
1297
1298         <section>
1299           <title>Parents</title>
1300
1301           <para><link linkend="element.project">project</link>.</para>
1302         </section>
1303
1304         <section>
1305           <title>Children</title>
1306
1307           <para><link linkend="element.bootstrap">bootstrap</link>, <link
1308           linkend="element.component">component</link>, <link
1309           linkend="element.define">define</link>, <link
1310           linkend="element.dependency">dependency</link>, <link
1311           linkend="element.directory">directory</link>, <link
1312           linkend="element.file">file</link>, <link
1313           linkend="element.if">if</link>, <link
1314           linkend="element.importlibrary">importlibrary</link>, <link
1315           linkend="element.include">include</link>, <link
1316           linkend="element.invoke">invoke</link>, <link
1317           linkend="element.library">library</link>, <link
1318           linkend="element.property">property</link>.</para>
1319         </section>
1320       </section>
1321
1322       <section id="element.output">
1323         <title>Output element</title>
1324
1325         <para>An output element specifies a group of filenames that is to be
1326         passed as parameters to a build tool. Output filename parameters are
1327         located before input filename parameters on the command line.</para>
1328
1329         <section>
1330           <title>Syntax</title>
1331
1332           <para><programlisting>&lt;output&gt;
1333   ...
1334 &lt;/output&gt;</programlisting></para>
1335         </section>
1336
1337         <section>
1338           <title>Attributes</title>
1339
1340           <para>None.</para>
1341         </section>
1342
1343         <section>
1344           <title>Value</title>
1345
1346           <para>None.</para>
1347         </section>
1348
1349         <section>
1350           <title>Parents</title>
1351
1352           <para><link linkend="element.invoke">invoke</link></para>
1353         </section>
1354
1355         <section>
1356           <title>Children</title>
1357
1358           <para><link linkend="element.outputfile">outputfile</link>.</para>
1359         </section>
1360       </section>
1361
1362       <section id="element.outputfile">
1363         <title>Outputfile element</title>
1364
1365         <para>An outputfile element specifies a filename that is to be passed
1366         as a parameter to a build tool.</para>
1367
1368         <section>
1369           <title>Syntax</title>
1370
1371           <para><programlisting>&lt;outputfile switches="<replaceable>-H</replaceable>"&gt;<replaceable>../include/reactos/bugcodes.h</replaceable>&lt;/outputfile&gt;</programlisting></para>
1372         </section>
1373
1374         <section>
1375           <title>Attributes</title>
1376
1377           <para><variablelist>
1378               <varlistentry>
1379                 <term>switches</term>
1380
1381                 <listitem>
1382                   <para>Switches that are passed as parameters just before the
1383                   filename. This attribute is optional.</para>
1384                 </listitem>
1385               </varlistentry>
1386             </variablelist></para>
1387         </section>
1388
1389         <section>
1390           <title>Value</title>
1391
1392           <para>Name of file that is to be passed as a parameter to the build
1393           tool.</para>
1394         </section>
1395
1396         <section>
1397           <title>Parents</title>
1398
1399           <para><link linkend="element.output">output</link>.</para>
1400         </section>
1401
1402         <section>
1403           <title>Children</title>
1404
1405           <para>None.</para>
1406         </section>
1407       </section>
1408
1409       <section id="element.pch">
1410         <title>Pch element</title>
1411
1412         <para>A pch element specifies a GCC precompiled header file.</para>
1413
1414         <section>
1415           <title>Syntax</title>
1416
1417           <para><programlisting>&lt;pch&gt;<replaceable>ntdll.h</replaceable>&lt;/pch&gt;</programlisting></para>
1418         </section>
1419
1420         <section>
1421           <title>Attributes</title>
1422
1423           <para>None.</para>
1424         </section>
1425
1426         <section>
1427           <title>Value</title>
1428
1429           <para>Name of the include file to be precompiled.</para>
1430         </section>
1431
1432         <section>
1433           <title>Children</title>
1434
1435           <para>None.</para>
1436         </section>
1437       </section>
1438
1439       <section id="element.project">
1440         <title>Project element</title>
1441
1442         <para>There can be one <sgmltag class="element">project</sgmltag> per
1443         top-level XML build file. A project can only be defined in a top-level
1444         XML build file.</para>
1445
1446         <section>
1447           <title>Syntax</title>
1448
1449           <para><programlisting>&lt;project name="ReactOS" makefile="Makefile.auto" xmlns:xi="http://www.w3.org/2001/XInclude"&gt;
1450   ...
1451 &lt;/project&gt;</programlisting></para>
1452         </section>
1453
1454         <section>
1455           <title>Attributes</title>
1456
1457           <para><variablelist>
1458               <varlistentry>
1459                 <term>name</term>
1460
1461                 <listitem>
1462                   <para>Name of the project.</para>
1463                 </listitem>
1464               </varlistentry>
1465
1466               <varlistentry>
1467                 <term>makefile</term>
1468
1469                 <listitem>
1470                   <para>Filename of the GNU makefile that is to be
1471                   created.</para>
1472                 </listitem>
1473               </varlistentry>
1474             </variablelist></para>
1475         </section>
1476
1477         <section>
1478           <title>Value</title>
1479
1480           <para>None.</para>
1481         </section>
1482
1483         <section>
1484           <title>Parents</title>
1485
1486           <para>None. This is the top-level (root) element of
1487           <filename>ReactOS.xml</filename> file.</para>
1488         </section>
1489
1490         <section>
1491           <title>Children</title>
1492
1493           <para><link linkend="element.define">define</link>, <link
1494           linkend="element.directory">directory</link>, <link
1495           linkend="element.if">if</link>, <link
1496           linkend="element.include">include</link>, <link
1497           linkend="element.module">module</link>, <link
1498           linkend="element.property">property</link>.</para>
1499         </section>
1500       </section>
1501
1502       <section id="element.property">
1503         <title>Property element</title>
1504
1505         <para>A property element specifies the name and value of a property
1506         that can be used for conditional processing of the XML build
1507         file.</para>
1508
1509         <section>
1510           <title>Syntax</title>
1511
1512           <para><programlisting>&lt;property name="<replaceable>mypropertyname</replaceable>" value="<replaceable>mypropertyvalue</replaceable>" /&gt;</programlisting></para>
1513         </section>
1514
1515         <section>
1516           <title>Attributes</title>
1517
1518           <para><variablelist>
1519               <varlistentry>
1520                 <term>name</term>
1521
1522                 <listitem>
1523                   <para>Name of property.</para>
1524                 </listitem>
1525               </varlistentry>
1526
1527               <varlistentry>
1528                 <term>value</term>
1529
1530                 <listitem>
1531                   <para>Value of property.</para>
1532                 </listitem>
1533               </varlistentry>
1534             </variablelist></para>
1535         </section>
1536
1537         <section>
1538           <title>Value</title>
1539
1540           <para>None.</para>
1541         </section>
1542
1543         <section>
1544           <title>Parents</title>
1545
1546           <para></para>
1547         </section>
1548
1549         <section>
1550           <title>Children</title>
1551
1552           <para>None.</para>
1553         </section>
1554       </section>
1555
1556       <section id="element.symbol">
1557         <title>Symbol element</title>
1558
1559         <para>A symbol element specifies an imported function from a library
1560         that is to be stubbed so tests can be run without actually calling the
1561         function in the library.</para>
1562
1563         <section>
1564           <title>Syntax</title>
1565
1566           <para><programlisting>&lt;symbol newname="<replaceable>RtlAllocateHeap</replaceable>"&gt;<replaceable>HeapAlloc@12</replaceable>&lt;/symbol&gt;</programlisting></para>
1567         </section>
1568
1569         <section>
1570           <title>Attributes</title>
1571
1572           <para><variablelist>
1573               <varlistentry>
1574                 <term>newname</term>
1575
1576                 <listitem>
1577                   <para>New name of symbol. This attribute is optional.</para>
1578                 </listitem>
1579               </varlistentry>
1580             </variablelist></para>
1581         </section>
1582
1583         <section>
1584           <title>Value</title>
1585
1586           <para>Name of symbol.</para>
1587         </section>
1588
1589         <section>
1590           <title>Children</title>
1591
1592           <para>None.</para>
1593         </section>
1594       </section>
1595     </section>
1596   </chapter>
1597
1598   <bibliography>
1599     <title>Bibliography</title>
1600
1601     <bibliomixed><title><ulink
1602     url="http://www.w3.org/TR/2004/REC-xml-20040204/">Extensible Markup
1603     Language (XML) 1.0 (Third Edition)</ulink></title><releaseinfo>W3C
1604     Recommendation</releaseinfo><author>
1605         <firstname>Fran&ccedil;ois</firstname>
1606
1607         <surname>Yergeau</surname>
1608       </author><author>
1609         <firstname>Tim</firstname>
1610
1611         <surname>Bray</surname>
1612       </author><author>
1613         <firstname>Jean</firstname>
1614
1615         <surname>Paoli</surname>
1616       </author><author>
1617         <firstname>C. M.</firstname>
1618
1619         <surname>Sperberg-McQueen</surname>
1620       </author><author>
1621         <firstname>Eve</firstname>
1622
1623         <surname>Maler</surname>
1624       </author><date>4th February 2004</date></bibliomixed>
1625
1626     <bibliomixed><title><ulink
1627     url="http://www.w3.org/TR/2004/REC-xinclude-20041220/">XML Inclusions
1628     (XInclude) Version 1.0 </ulink></title><releaseinfo>W3C
1629     Recommendation</releaseinfo><editor>
1630         <firstname>Jonathan</firstname>
1631
1632         <surname>Marsh</surname>
1633
1634         <affiliation>
1635           <orgname>Microsoft</orgname>
1636         </affiliation>
1637
1638         <email>jmarsh@microsoft.com</email>
1639       </editor><editor>
1640         <firstname>David</firstname>
1641
1642         <surname>Orchard</surname>
1643
1644         <affiliation>
1645           <orgname>BEA Systems</orgname>
1646         </affiliation>
1647
1648         <email>dorchard@bea.com</email>
1649       </editor>20 December 2004</bibliomixed>
1650   </bibliography>
1651 </book>