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