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