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