[ros-diffs] [chorns] 13225: Add documentation

Add documentation
Added: branches/xmlbuildsystem/reactos/tools/rbuild/rbuild.txt
  _____  

Added: branches/xmlbuildsystem/reactos/tools/rbuild/rbuild.txt
--- branches/xmlbuildsystem/reactos/tools/rbuild/rbuild.txt
2005-01-23 11:01:51 UTC (rev 13224)
+++ branches/xmlbuildsystem/reactos/tools/rbuild/rbuild.txt
2005-01-23 12:47:42 UTC (rev 13225)
@@ -0,0 +1,387 @@

+ReactOS Build System Documentation
+==================================
+
+Building ReactOS
+----------------
+To generate GNU make makefiles for building ReactOS do the following:
+
+	1) Go to the top-level reactos directory
+	2) Run the command: mingw32-make -C tools\reactos
+	3) Run the command: tools\rbuild\rbuild mingw
+
+This will generate Makefile.auto in the current directory. Now run the
following command:
+
+	mingw32-make -f Makefile.auto
+
+This will start building ReactOS.
+
+To build a bootable CD run the following command:
+
+	mingw32-make -f Makefile.auto bootcd
+
+This will create ReactOS.iso in the top-level reactos directory.
+
+
+Top-level XML Build File
+------------------------
+The top-level xml build file (ReactOS.xml) is processed by rbuild. The
following is an example of how it could look like:
+
+<?xml version="1.0"?>
+<!DOCTYPE project SYSTEM "tools/rbuild/project.dtd">
+<project name="ReactOS" makefile="Makefile.auto"
xmlns:xi="http://www.w3.org/2001/XInclude">
+	<xi:include href="config.xml">
+		<xi:fallback>
+			<xi:include href="config.template.xml" />
+		</xi:fallback>
+	</xi:include>
+
+	<define name="_M_IX86" />
+	<if property="DBG" value="1">
+		<define name="DBG" value="1" />
+		<property name="DBG_OR_KDBG" value="true" />
+	</if>
+
+	<include base="ReactOS">include</include>
+
+	<directory name="boot">
+		<xi:include href="boot/boot.xml" />
+	</directory>
+
+	<module name="bootcd" type="iso">
+	</module>
+</project>
+
+
+xi:include
+----------
+It is possible to split an xml build file over several files. The
include element in the xi namespace is used to accomplish this.
+
+Syntax:
+	<xi:include href="config.xml">
+		<xi:fallback>
+			<xi:include href="config.template.xml" />
+		</xi:fallback>
+	</xi:include>
+
+Attributes:
+	href - Name of xml build file to include. The filename is
relative to the location of the current xml build file.
+
+Value:
+	None.
+
+Elements:
+	xi:fallback
+
+
+xi:fallback
+-----------
+This element is used to provide the name of an alternate file that is
to be included if the first include file did not exists.
+
+Attributes:
+	None.
+
+Value:
+	None.
+
+Elements:
+	xi:include.
+
+
+Project element
+---------------
+There can be one project per top-level XML build file. A project can
only be defined in a top-level xml build file.
+
+Syntax:
+	<project name="ReactOS" makefile="Makefile.auto"
xmlns:xi="http://www.w3.org/2001/XInclude">
+		...
+	</project>
+
+Attributes:
+	name - Name of the project.
+	makefile - Filename of the GNU makefile that is to be created.
+
+Value:
+	None.
+
+Elements:
+	define, directory, if, include, module, property
+
+
+Module element
+--------------
+There can be zero or more modules per xml build file.
+
+Syntax:
+	<module name="msvcrt" type="win32dll" extension=".dll"
entrypoint="_DllMain@12" mangledsymbols="true">
+		...
+	</module>
+
+Attributes:
+	name - Name of the module. Also the base name of the generated
file if such file is generated for the particular module type.
+	type - Type of module. See below for an explanation of module
types.
+	extension - Extension of the generated file if such file is
generated for the particular module type.
+	entrypoint - Entrypoint for the generated file if such file is
generated for the particular module type.
+	mangledsymbols - Controls wether or not to pass --kill-at to
dlltool. If this attribute has the value false then --kill-at is passed
to dlltool. If the value is true, then --kill-at is not passed to
dlltool. If the generated file exports C++ classes then this need to be
true.
+
+Value:
+	None.
+
+Elements:
+	define, dependency, directory, file, if, importlibrary, include,
invoke, library, property.
+
+
+Module types
+------------
+The module type determines the actions that is to be carried out to
process the module. The defined module types are seen below:
+	buildtool - Builds a tool that can be run (invoked) when
building ReactOS. Default extension is .exe when building on Windows and
nothing when building on Linux. The entrypoint module attribute is not
applicable for this module type.
+	staticlibrary - Builds a static library containing object files
that can be linked together with other modules. Default extension is .a.
The entrypoint module attribute is not applicable for this module type.
+	objectlibrary - Builds object files that can be linked together
with other modules. Default extension is .o. The entrypoint module
attribute is not applicable for this module type.
+	kernel - Builds ntoskrnl.exe. Default extension is .exe. Default
entrypoint is _NtProcessStartup. 
+	kernelmodedll - Builds a kernel-mode DLL. Default extension is
.dll. Default entrypoint is _DriverEntry@8.
+	kernelmodedriver - Builds a kernel-mode driver. Default
extension is .sys. Default entrypoint is _DriverEntry@8.
+	nativedll - Builds a native DLL. Default extension is .dll.
Default entrypoint is _DllMainCRTStartup@12.
+	win32dll - Builds a Win32 DLL. Default extension is .dll.
Default entrypoint is _DllMain@12.
+	win32gui - Builds a Win32 GUI executable. Default extension is
.exe. Default entrypoint is _WinMainCRTStartup.
+	bootloader - Builds a bootloader. The extension and entrypoint
module attributes are not applicable for this module type.
+	bootsector - Builds one or more bootsector binaries. The
extension and entrypoint module attributes are not applicable for this
module type.
+	iso - Builds a bootable CD. The extension and entrypoint module
attributes are not applicable for this module type
+
+
+Define element
+--------------
+A define element specifies the name and (optionally) value of a define
for the C/C++ compiler and resource compiler.
+
+Syntax:
+	<define name="WINVER">0x501</define>
+
+Attributes:
+	name - Name of define.
+
+Value:
+	Value of define. The value is optional.
+
+Elements:
+	None.
+
+
+Dependency element
+------------------
+A dependency element specifies the name of a module (usually of type
buildtool) that is to be processed before the current module.
+
+Syntax:
+	<dependency>OtherModule</dependency>
+
+Attributes:
+	None.
+
+Value:
+	Name of module.
+
+Elements:
+	None.
+
+
+Directory element
+-----------------
+A directory element specifies the name of a subdirectory.
+
+Syntax:
+	<directory name="MyDirectory">
+		...
+	</directory>
+
+Attributes:
+	name - Name of directory.
+
+Value:
+	None.
+
+Elements:
+	directory, file, if, property.
+
+
+File element
+------------
+A file element specifies the name of a file that is to be processed.
+
+Syntax:
+	<file>MyFile.c</file>
+
+Attributes:
+	None.
+
+Value:
+	Name of file.
+
+Elements:
+	None.
+
+
+If element
+----------
+An if element allows for conditional processing of other elements.
+
+Syntax:
+	<if property="DBG" value="1">
+		...
+	</if>
+
+Attributes:
+	property - Name of the property that is to be evaluated.
+	value - Value to compare to the value of the property. If the
property has the specified value, then the subelements are processed.
+
+Value:
+	None.
+
+Elements:
+	define, directory, file, if, include, property.
+
+
+Importlibrary element
+---------------------
+An importlibrary element specifies that an import library should be
generated which other modules can use to link with the current module.
+
+Syntax:
+	<importlibrary definition="MyModule.def" />
+
+Attributes:
+	definition - Filename of definition file (.def) used to generate
the import library. The filename is relative to the current module.
+
+Value:
+	None.
+
+Elements:
+	None.
+
+
+Include element
+---------------
+An include element specifies an include directory for the C/C++
compiler and resource compiler.
+
+Syntax:
+	<include base="MyLibraryModule">include</include>
+
+Attributes:
+	base - Module or project which the value of this element is
relative to. This attribute is optional. If left out, the include
directory is relative to the position of the top-level xml build file.
+
+Value:
+	Relative include directory.
+
+Elements:
+	None.
+
+
+Invoke element
+--------------
+An invoke element specifies the name of a module which is to be
executed before the current module is processed.
+
+Syntax:
+	<invoke module="wmc">
+		<input>
+			<inputfile>ntoskrnl.mc</inputfile>
+		</input>
+		<output>
+			<outputfile
switches="-H">../include/reactos/bugcodes.h</outputfile>
+			<outputfile
switches="-o">bugcodes.rc</outputfile>
+		</output>
+	</invoke>
+
+Attributes:
+	None.
+
+Value:
+	Name of the module to execute.
+
+Elements:
+	input, output.
+
+
+Input element
+-------------
+An input element specifies a group of filenames that is to be passed as
parameters to a build tool. Input filename parameters are located after
output filename parameters on the command line. 
+
+Attributes:
+	None.
+
+Value:
+	None.
+
+Elements:
+	inputfile.
+
+
+Inputfile element
+-----------------
+An inputfile element specifies a filename that is to be passed as a
parameter to a build tool.
+
+Attributes:
+	switches - Switches that is passed as parameters just before the
filename. This attribute is optional.
+
+Value:
+	Name of file that is to be passed as a parameter to the build
tool.
+
+Elements:
+	None.
+
+
+Output element
+--------------
+An output element specifies a group of filenames that is to be passed
as parameters to a build tool. Output filename parameters are located
before input filename parameters on the command line. 
+
+Attributes:
+	None.
+
+Value:
+	None.
+
+Elements:
+	outputfile.
+
+
+Outputfile element
+------------------
+An outputfile element specifies a filename that is to be passed as a
parameter to a build tool.
+
+Attributes:
+	switches - Switches that is passed as parameters just before the
filename. This attribute is optional.
+
+Value:
+	Name of file that is to be passed as a parameter to the build
tool.
+
+Elements:
+	None.
+
+
+Library
+-------
+An importlibrary element specifies the name of another module which is
to be linked with the current module.
+
+Syntax:
+	<library>MyLibraryModule</library>
+
+Attributes:
+	None.
+
+Value:
+	Name of the module to link with.
+
+Elements:
+	None.
+
+
+Property
+--------
+A property element specifies the name and value of a property that can
be used for conditional processing of the xml build file.
+
+Syntax:
+	<property name="mypropertyname" value="mypropertyvalue" />
+
+Attributes:
+	name - Name of property.
+	value - Value of property.
+
+Value:
+	None.
+
+Elements:
+	None.