📄 xmake_documentation.html
字号:
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<title>xmake Documentation</title>
</head>
<body>
<h1><code>xmake</code> Documentation</h1>
<h1>xmake</h1>
<h2>Introduction</h2>
<p>So why another build tool ? Well that's a great question now isn't it
! Basically I hate make files, and the whole make file syntax. I find it
incredibly difficult to read, it is error prone to edit, and just seems
to me to be incredibly messy. Obviously I am not alone in this feeling,
since there are a number of projects out there to create alternatives to
make (Ant for Java, and Jam, come to mind immediately).</p>
<p>So, since the <a href="http://sourceforge.net/projects/vcf"> VCF</a> is now building on linux/Unix systems (so far the
FoundationKit has been built on linux and Solaris ), it was thought it
sure would be nice to have a single build file that could be used on any
system for GCC, VC++, etc. Since XML syntax is easy to read (compared to
a traditional make file), and the scope of the program would be fairly
limited, i.e. it is designed to compiled and link C++ programs, and not
a whole lot more, I thought it was worth the effort to try and write a
make like program that would accept this new syntax. As it turned out it
wasn't very hard, and maybe a couple of days of programming time (plus
probably a week of testing) has
gone into writing <code> xmake</code> so I think it is worth it . </p>
<p>Another reason to write <code> xmake</code> was the desire to be able to have other
developers quickly be able to build the framework, even on system that
do not have good IDE's. I felt that it is a LOT easier to explain a
simple set of XML tags to developers with a background in VC++ and GUI
IDE's than trying to struggle to explain makefiles. </p>
<p>While there are a couple of features that are not yet finished,
notably the preBuild/postBuild tags, and the project level dependencies,
the core of xmake works quite well and I have been regularly using it to
build the VCF on linux as I work on porting it. This includes the build
the FoundationKit as a shared library and the various test projects used
to test the various parts of the port. </p>
<p>In addition to a command line tool, the <code> xmake</code> engine will become the underlying build tool
for the VCFBuilder, so VCFBuilder workspaces/projects will share the
same XML syntax as <code> xmake</code> does (though the VCFBuilder will include a
number of extra tags that will simply be ignored by the <code> xmake</code> engine). </p>
<p> </p>
<h3>Basic Usage</h3>
<p><code>xmake</code> is designed to work on one or more projects. A project
generally results in the output of a single binary, such as an
executable (.exe) or a library (.lib) or a dynamic library (.dll or .so
depending on your system). Within in a project, you can specify one or
more configurations to build. For example, you could have a project
build a "Debug GCC" and a "Debug VC++" and a
"Debug BCC" (please note you can call the configuration
anything you want), that would build a binary file using different
compilers and linkers depending on the configuration. Configurations
hold most of the key settings for the compiler and linker, as well as
allowing you to specify additional build tools for specials file types
(such as a resource compiler for .RC files on Win32 systems). Thus
when using <code> xmake</code> you tell it to build a specific configuration for a
given project in a make file (usually makefile.xml). <code> xmake</code> is smart
enough to automatically check file dependencies for you, so if you have
recently modified a header that two of the five source files in your
project depend on, it will only build the two affected source files.</p>
<p>Projects also hold a list of one or more source files that are
necessary to build the project. These source files hold information such
as the file name (the exact path is determined dynamically, relative to
the path where is <code> xmake</code> is invoked), the output name, whether or not the
file should be built (this can be useful, to allow you to turn
"off" certain files ), and finally the configuration the
source belongs to. Source files may belong to one or more
configurations, with each configuration name separated by a
"|" character (for example, <code>"Debug GCC|Debug
VC++"</code>) .</p>
<p>The command line usage is :</p>
<p><code>xmake [projectName] -config configurationName [-f makefileName]
|| [-install] || [-clean]</code></p>
<p>You can invoke the <code> xmake</code> program from the command line. You control
the program by the following options :</p>
<ul>
<li><code>projectName</code> - is the name of the project to build in this
makefile. If left blank then the first project found is the one that is
built.
<li><code>-config configurationName</code> - this tells the <code> xmake</code> program which
configuration to build. The <code> -config</code> option <b><i>must</i></b>
be followed by a
configuration name so <code> xmake</code> knows what to build. Specify the wrong
name and you will not build what you expected.
<li><code>-f makefileName</code> - the makefile to use. If this is not specified then
<code>xmake</code> looks for a file named
"makefile.xml" in the current directory. If this is not found then an
error results and <code> xmake</code> exits.
<li><code>-install</code> - currently unimplemented
<li><code>-clean</code> - removes all binary files produced by the
make file for the specified configuration</li>
</ul>
<p>An example of it's usage, for example to build the FoundationKit for
the <a href="http://sourceforge.net/projects/vcf"> VCF</a> in linux using GCC, is this:</p>
<pre>xmake -config "GCC Debug" </pre>
<p> </p>
<h3>XML syntax</h3>
<p>Since the <code> xmake</code> makefile is based on XML it follows all XML syntax
rules. Please note that if you need to have double quotes in a value,
use the single quote, which will then be replaced with a double quote
during the build process. </p>
<h4><code><make></code></h4>
<p>This is the outermost tag. Every <code> xmake</code> makefile must begin and end
with this tag.</p>
<p> </p>
<h4><code><substitutions></code></h4>
<p>This is where you can specify variable names that will be substituted
when the make file is parsed and executed by <code>xmake</code>. For example you can
specify a common include path, or a common output folder. Inside of a <code>substitutions</code>
tag you can have zero or more variable tags that have 2 attributes, a
name and a value. The name attribute is the name of the variable as it
will be referenced throughout the make file, and the value attribute
specifies the string that will be substituted wherever the parser
encounters the variable. System environment variables may also be used,
so if you have defined <code><b>VCF_INCLUDE</b></code> as one of your
system's environment variables, then the parser is smart enough to
attempt to try and check to see if the variable exists.</p>
<p>To reference the variable you do so as follows:</p>
<ul>
<li>$(<variable name>), for example if you have defined a
variable called MyIncludePath, then you would reference it $(MyIncludePath)
<li>%<variable name>%, for example if you have defined a
variable called MyIncludePath, then you would reference it %MyIncludePath%</li>
</ul>
<p>An example of this tag section looks like this:</p>
<pre><substitutions>
<variable name="VCF_INCLUDE" value="e:\code\vcf\include"/>
<variable name="INC" value="../../../include"/>
<variable name="SRC" value="../../../src"/>
</substitutions></pre>
<p><b><i>Please note</i></b>: Variables can be used anywhere you are
specifying a value for a attribute. </p>
<p> </p>
<h4><code><project></code></h4>
<p>The project holds all the important nodes. It also has a series of
attributes, as follows:</p>
<ul>
<li><code>name</code> - the name of the project
<li><code>path</code> - the path of the project. This is optional
right now and doesn't do much...</li>
<li><code>outputAs</code> - the output path of the project. This is
used to determine the binary that represents a successful build of
the project, and is used when your "clean" your project to
specify the binary to get rid of. For example it could be "FooBar.exe",
or "MyLib.dll", or "MySharedCode.so". </li>
</ul>
<p>Note that the <code>outputAs</code> attribute is optional. With most
compilers/linkers you can specify where the binary output will go.
However, as mentioned above, the output name is used so that <code> xmake</code> can
do a complete "clean" of the project.</p>
<p> </p>
<h4><code><dependencies></code></h4>
<p>Not implemented yet. These will allow for specifying what project(s)
must be built before this one can be built. Again this is very similar
to how dependencies work in VC++.</p>
<p> </p>
<h4><code><configurations></code></h4>
<p>Configurations are the heart of <code>xmake</code>. If you have used Microsoft's
Visual C++ then you'll be right at home here. Basically a configuration
is a complete set of settings for compiler and linker in order to build
the project. A single project may have multiple configurations, for
example you might have a "Win32 Debug", "Win32
Release", "Linux Debug", "Linux Release",
"Mac Debug", and "Mac Release". Thus, in order for <code>
xmake</code> to do it's job it needs to know the configuration you want to
build. The <configurations> tag is used to indicate the collection, and then a
series of 1 or more <config> sub tags for each configuration. A configuration has the following attributes:</p>
<ul>
<li><code>name</code> - The configuration name identifies the
configuration, and is used by source files to identify which
configuration they belong to. A configuration name can only have the
characters [a..z, A..Z, 0..9] the "|" is used to separate
multiple configurations.
<li><code>srcBinaryExt</code> - the srcBinaryExt is used to identify
the extension of compiled source files. Many compilers use
".o" while many others use ".obj". For example,
GCC/G++ uses ".o" for it's extension for object files,
while VC++ uses ".obj". This allows you to specify just
the name of your output files (without the "." extension)
and let <code> xmake</code> append the correct extension based on the
configuration currently being built. </li>
</ul>
<p>An example looks something like this:</p>
<pre><config name="VC++ Debug" srcBinaryExt=".obj">
.... more stuff follows</pre>
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -