Add reference to the 'compilerflag' element.
[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 </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>