mirror of
https://github.com/saitohirga/WSJT-X.git
synced 2025-11-04 05:50:31 -05:00
1523 lines
62 KiB
HTML
1523 lines
62 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
|
|
<title>Boost.Build tutorial</title>
|
|
|
|
<link href="website/bootstrap/css/bootstrap.min.css" rel="stylesheet">
|
|
<link href="website/index.css" rel="stylesheet">
|
|
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<div lang="en" class="container">
|
|
|
|
<div class="header">
|
|
<ul>
|
|
<li><a href="index.html">About</a>
|
|
<li><a href="doc/html/index.html">Documentation</a>
|
|
<li><a href="http://github.com/boostorg/build">GitHub</a>
|
|
</ul>
|
|
<span><b>Boost.Build Tutorial</b></span>
|
|
</div>
|
|
|
|
<hr class="hrhead">
|
|
<p>Written by Boris Schäling.</p>
|
|
|
|
<div class="toc">
|
|
<h3>Table of Contents</h3>
|
|
|
|
<ul>
|
|
<li><a href="#introduction">1. Introduction</a></li>
|
|
|
|
<li><a href="#buildprocess">2. Build process</a></li>
|
|
|
|
<li><a href="#basic_tasks">3. Basic tasks</a></li>
|
|
|
|
<li><a href="#project_management">4. Project management</a></li>
|
|
|
|
<li><a href="#best_practices">5. Best practices</a></li>
|
|
|
|
<li><a href="#rule_reference">6. Rule reference</a></li>
|
|
|
|
<li><a href="#feature_reference">7. Feature reference</a></li>
|
|
</ul>
|
|
</div>
|
|
|
|
|
|
<hr>
|
|
|
|
<h2 id="introduction">Introduction<br><small>Compiler- and
|
|
platform-independent build system</small></h2>
|
|
|
|
<div>
|
|
|
|
<p>Boost.Build is a high-level build system which makes it as easy as
|
|
possible to manage C++ projects. The idea is to specify in
|
|
configuration files just as much as necessary to build a program. For
|
|
example it is not required to tell Boost.Build how to use a certain
|
|
compiler. Boost.Build supports many compilers out of the box and knows
|
|
how to use them. If you create a configuration file you just need to
|
|
tell Boost.Build where to find the source files, what the executable
|
|
should be called and which compiler Boost.Build should use. Boost.Build
|
|
will then try to find the compiler and automatically build the
|
|
program.</p>
|
|
|
|
<p>As Boost.Build supports many compilers configuration files never
|
|
contain any compiler-specific options. Configuration files are entirely
|
|
compiler-independent. Of course it is possible to set options like
|
|
whether code should be optimized. However these options are written in
|
|
a language only understood by Boost.Build. Once a compiler is picked to
|
|
build a program Boost.Build translates options in configuration files
|
|
to command line options expected by the selected compiler. This makes
|
|
it possible to write configuration files once and build a program on
|
|
different platforms with different compilers.</p>
|
|
|
|
<p>As nice as it sounds Boost.Build can only be used for C++ and C
|
|
projects. Boost.Build doesn't know how to use other compilers like a
|
|
Java compiler. Although Boost.Build is extensible it makes more sense
|
|
to use a different build system for programs implemented in other
|
|
programming languages.</p>
|
|
|
|
<p>Boost.Build was created to build and install the <a class="link"
|
|
href="http://www.boost.org/" target="_top">Boost C++ libraries</a>
|
|
easily with different compilers on different platforms. Although
|
|
Boost.Build is part of and shipped with the Boost C++ libraries it can
|
|
be used separately for any C++ or C project. It's even possible to
|
|
<a class="link" href="http://sourceforge.net/projects/boost/files/"
|
|
target="_top">download only Boost.Build</a> in case you don't want to
|
|
use the Boost C++ libraries.</p>
|
|
|
|
<p>This article is an introduction to help you using Boost.Build for
|
|
your own C++ or C projects. It gives you a basic understanding of how
|
|
Boost.Build works and how you start using it. After reading the article
|
|
you should not only be able to use Boost.Build for your own projects,
|
|
it will also be easier to understand the <a class="link" href=
|
|
"http://www.boost.org/doc/tools/build/doc/html/index.html" target=
|
|
"_top">Boost.Build documentation</a> as you'll know the big
|
|
picture.</p>
|
|
</div>
|
|
<hr>
|
|
|
|
<h2 id="buildprocess">Build process<br>
|
|
<small>Jamfiles and an interpreter called b2</small>
|
|
</h2>
|
|
|
|
<div>
|
|
|
|
<p>The program you use to build a project managed by Boost.Build is
|
|
called <span class="command"><strong>b2</strong></span>. If you
|
|
downloaded and built the Boost C++ libraries you have used <span class=
|
|
"command"><strong>b2</strong></span> already. <span class=
|
|
"command"><strong>b2</strong></span> looks for configuration files,
|
|
reads them and builds a project accordingly. It also accepts various
|
|
command line options which can be useful for example to show all
|
|
commands executed by <span class="command"><strong>b2</strong></span>
|
|
to build a project.</p>
|
|
|
|
<p>Projects can be large and can consist of many components whose
|
|
source code is distributed over many directories. Instead of creating
|
|
one big configuration file for the entire project components typically
|
|
get their own configuration files. This is no different with
|
|
Boost.Build: In a large project there will be many configuration files
|
|
which have to be found and interpreted by <span class=
|
|
"command"><strong>b2</strong></span>.</p>
|
|
|
|
<p>For Boost.Build every directory with a configuration file is a
|
|
project: If there is a configuration file in a directory something can
|
|
be built. Whether it's a component in a subdirectory or a software
|
|
consisting of many components doesn't make a difference for
|
|
Boost.Build.</p>
|
|
|
|
<p>When <span class="command"><strong>b2</strong></span> is started
|
|
it doesn't run a search for configuration files on the entire file
|
|
system. It searches for a configuration file in the current working
|
|
directory only. If it doesn't find a configuration file it doesn't do
|
|
anything. <span class="command"><strong>b2</strong></span> does not
|
|
search for configuration files in any other directory if there is no
|
|
configuration file in the current working directory.</p>
|
|
|
|
<p>The configuration file <span class=
|
|
"command"><strong>b2</strong></span> is looking for is called
|
|
<code class="filename">Jamfile.jam</code>. Files with the extension
|
|
<code class="filename">jam</code> are called Jamfiles. If <span class=
|
|
"command"><strong>b2</strong></span> finds a Jamfile in the current
|
|
working directory it searches for more Jamfiles in parent directories.
|
|
<span class="command"><strong>b2</strong></span> climbs up parent
|
|
directories until it finds a configuration file called <code class=
|
|
"filename">Jamroot.jam</code>. <code class=
|
|
"filename">Jamroot.jam</code> is no different from <code class=
|
|
"filename">Jamfile.jam</code>. It only indicates that <span class=
|
|
"command"><strong>b2</strong></span> doesn't need to look
|
|
further.</p>
|
|
|
|
<p>The reason why <span class="command"><strong>b2</strong></span>
|
|
looks for Jamfiles in parent directories is that it makes it possible
|
|
to group settings. If there are some components which should be built
|
|
with similar settings they can be stored in a Jamfile in a parent
|
|
directory which will be automatically used if a component in a
|
|
subdirectory is built.</p>
|
|
|
|
<p>Please note that <span class="command"><strong>b2</strong></span>
|
|
must find a file called <code class="filename">Jamroot.jam</code>. It
|
|
is an error if no <code class="filename">Jamroot.jam</code> exists. If
|
|
<code class="filename">Jamroot.jam</code> is in the current working
|
|
directory no other file <code class="filename">Jamfile.jam</code> is
|
|
required. If <code class="filename">Jamroot.jam</code> is in a parent
|
|
directory a file <code class="filename">Jamfile.jam</code> must exist
|
|
in the current working directory - otherwise <span class=
|
|
"command"><strong>b2</strong></span> doesn't do anything.</p>
|
|
|
|
<p>If you copy <span class="command"><strong>b2</strong></span> to a
|
|
directory which contains no Jamfiles and start the program you get an
|
|
error message. However <span class=
|
|
"command"><strong>b2</strong></span> doesn't complain that it can't
|
|
find a Jamfile. It complains about not finding the build system.</p>
|
|
<pre class="screen">
|
|
Unable to load Boost.Build: could not find "boost-build.jam"
|
|
---------------------------------------------------------------
|
|
Attempted search from C:\Users\Boris\Desktop up to the root
|
|
|
|
Please consult the documentation at 'http://www.boost.org'.
|
|
</pre>
|
|
|
|
<p>The first thing <span class="command"><strong>b2</strong></span>
|
|
does is not looking for a Jamfile but loading the build system. But
|
|
what exactly is the build system?</p>
|
|
|
|
<p><span class="command"><strong>b2</strong></span> is an
|
|
interpreter. It doesn't really know how to build anything. What
|
|
<span class="command"><strong>b2</strong></span> does is interpreting
|
|
Jamfiles. Boost.Build is really implemented in Jamfiles. And they
|
|
contain all the logic which makes Boost.Build such a powerful tool. As
|
|
<span class="command"><strong>b2</strong></span> only does what it
|
|
reads in Jamfiles it needs to know where to find the Jamfiles
|
|
Boost.Build is made of.</p>
|
|
|
|
<p>When <span class="command"><strong>b2</strong></span> is started
|
|
it looks for a file <code class="filename">boost-build.jam</code> in
|
|
the current working directory. If it doesn't find the file it searches
|
|
all parent directories. This file needs to contain only one line to
|
|
tell <span class="command"><strong>b2</strong></span> where to find
|
|
the build system.</p>
|
|
<pre class="programlisting">
|
|
boost-build C:/boost_1_57_0/tools/build/src ;
|
|
</pre>
|
|
|
|
<p>The path after <code class="code">boost-build</code> must refer to a
|
|
directory which contains a file called <code class=
|
|
"filename">bootstrap.jam</code>. This is the file <span class=
|
|
"command"><strong>b2</strong></span> needs to load the build system.
|
|
As the Boost C++ libraries ship Boost.Build you can refer to the
|
|
subdirectory <code class="filename">tools/build</code> of the root
|
|
directory of the Boost C++ libraries. And you can always use a slash as
|
|
a path separator - even if you are on Windows.</p>
|
|
|
|
<p>Please note that there must be a space between the path and the
|
|
semicolon at the end of the line. It is an error if the space is
|
|
missing. You'll learn more about the syntax used in Jamfiles later in
|
|
this article.</p>
|
|
|
|
<p>If <span class="command"><strong>b2</strong></span> finds
|
|
<code class="filename">boost-build.jam</code> it uses the path within
|
|
the file to load the build system. When the build system is loaded it
|
|
also prepares itself to use a certain compiler, linker and maybe other
|
|
tools required to build a project. Boost.Build refers to these programs
|
|
as a toolset. If no command line option is used to start <span class=
|
|
"command"><strong>b2</strong></span> the build system tries to find a
|
|
toolset it can use automatically. On Windows for example it searches
|
|
for Visual C++. And if it detects that Visual C++ is installed it uses
|
|
the toolset msvc.</p>
|
|
<pre class="screen">
|
|
warning: No toolsets are configured.
|
|
warning: Configuring default toolset "msvc".
|
|
warning: If the default is wrong, your build may not work correctly.
|
|
warning: Use the "toolset=xxxxx" option to override our guess.
|
|
warning: For more configuration options, please consult
|
|
warning: http://boost.org/boost-build2/doc/html/bbv2/advanced/configuration.html
|
|
</pre>
|
|
|
|
<p>If you start <span class="command"><strong>b2</strong></span>
|
|
without specifying which toolset should be used you see a warning.
|
|
<span class="command"><strong>b2</strong></span> tells you which
|
|
toolset it detected and decided to use. If you want to suppress the
|
|
warning you must specify the toolset yourself. For example you tell the
|
|
build system to use Visual C++ with <span class="command"><strong>b2
|
|
toolset=msvc</strong></span>. If you want GCC to be used you enter
|
|
<span class="command"><strong>b2 toolset=gcc</strong></span>.</p>
|
|
|
|
<p>As of today there are more than 10 toolsets supported. There is a
|
|
good chance that Boost.Build will work with the compiler you use out of
|
|
the box.</p>
|
|
|
|
<p>Once the build system has been found, loaded and knows which toolset
|
|
to use - either because you specified one or the build system detected
|
|
one automatically - <span class="command"><strong>b2</strong></span>
|
|
looks for a file <code class="filename">Jamfile.jam</code> in the
|
|
current working directory. If it doesn't find a Jamfile an error
|
|
message is printed.</p>
|
|
<pre class="screen">
|
|
error: error: no Jamfile in current directory found, and no target references specified.
|
|
</pre>
|
|
|
|
<p>If you create an empty file <code class=
|
|
"filename">Jamfile.jam</code> and start <span class=
|
|
"command"><strong>b2</strong></span> again another error message is
|
|
printed.</p>
|
|
<pre class="screen">
|
|
error: Could not find parent for project at '.'
|
|
error: Did not find Jamfile.jam or Jamroot.jam in any parent directory.
|
|
</pre>
|
|
|
|
<p><span class="command"><strong>b2</strong></span> is ultimately
|
|
looking for a Jamfile called <code class="filename">Jamroot.jam</code>.
|
|
If it doesn't exist in the current working directory <span class=
|
|
"command"><strong>b2</strong></span> expects to find it in a parent
|
|
directory.</p>
|
|
|
|
<p>If you create an empty file <code class=
|
|
"filename">Jamroot.jam</code> and start <span class=
|
|
"command"><strong>b2</strong></span> the error message is gone.
|
|
Obviously there is nothing done by Boost.Build. But now you know how
|
|
<span class="command"><strong>b2</strong></span> proceeds to build a
|
|
program and what the minimum Boost.Build configuration looks like.</p>
|
|
|
|
<p>Please note that if you work on a small project and you need only
|
|
one configuration file you can simply call it <code class=
|
|
"filename">Jamroot.jam</code>. You don't need another file called
|
|
<code class="filename">Jamfile.jam</code>.</p>
|
|
</div>
|
|
<hr>
|
|
|
|
<h2 id="basic_tasks">Basic tasks<br>
|
|
<small>Rules and features</small>
|
|
</h2>
|
|
|
|
<div class="sect1">
|
|
|
|
<p>If you look at Jamfiles the syntax might remind you of configuration
|
|
files used by other build systems. Simple Jamfiles can look like plain
|
|
old configuration files where for example values seem to be assigned to
|
|
keys. What is important to understand though is that Jamfiles are
|
|
really script files. There is a programming language used to write
|
|
Jamfiles. <span class="command"><strong>b2</strong></span> isn't the
|
|
core component of Boost.Build which knows how to build programs. The
|
|
logic of Boost.Build is in the Jamfiles which tell <span class=
|
|
"command"><strong>b2</strong></span> how to build programs.</p>
|
|
|
|
<p>Even though Boost.Build is based on a programming language you don't
|
|
need to think of programming when you create Jamfiles. The syntax of
|
|
the programming language used by Boost.Build tries to remind you more
|
|
of creating plain old configuration files. The idea is to have the best
|
|
of two worlds: A powerful and flexible programming language but a
|
|
simple syntax you might be familiar with from other build systems.</p>
|
|
|
|
<p>This article doesn't introduce you into the programming language
|
|
Boost.Build is based on. The programming language is proprietary and
|
|
not really a joy to use. It is no competitor to popular scripting
|
|
languages like Javascript or Python. The developers of Boost.Build
|
|
recognize it and work on another version of Boost.Build based on
|
|
Python. However all of this shouldn't matter to developers who plan to
|
|
manage their projects with Boost.Build. It helps to understand the
|
|
syntax of Jamfiles better once one realizes that there is a programming
|
|
language inside Boost.Build. But it's not required to learn the details
|
|
of the programming language.</p>
|
|
|
|
<p>Let's look at a simple Jamfile which can be used to build an
|
|
executable <span class="command"><strong>hello</strong></span> from a
|
|
source file <code class="filename">hello.cpp</code>.</p>
|
|
<pre class="programlisting">
|
|
exe hello : hello.cpp ;
|
|
</pre>
|
|
|
|
<p>Boost.Build provides a lot of built-in rules and <code class=
|
|
"code">exe</code> is one of them. While the documentation of
|
|
Boost.Build refers to <code class="code">exe</code> as a rule you know
|
|
already that the above Jamfile is actually built using a programming
|
|
language. As it turns out rules are simply functions. And the Jamfile
|
|
above contains a function call.</p>
|
|
|
|
<p>For the majority of tasks which are typically required to build
|
|
programs Boost.Build provides predefined rules - or functions if you
|
|
like. As with functions in other programming languages it is possible
|
|
to pass parameters. In the Jamfile above the function <code class=
|
|
"code">exe</code> is called with the two parameters hello and
|
|
hello.cpp.</p>
|
|
|
|
<p>The programming language Boost.Build is based on knows only one data
|
|
type: Everything is a list of strings. A list can be empty or contain
|
|
one or more strings. In the Jamfile above the function <code class=
|
|
"code">exe</code> is called with two parameters each one a list
|
|
containing one string.</p>
|
|
<pre class="programlisting">
|
|
exe "hello" : "hello.cpp" ;
|
|
</pre>
|
|
|
|
<p>It is possible to use quotes. It's not necessary though as after all
|
|
every item in a list has the data type string anyway. Quotes are only
|
|
used if parameters contain spaces.</p>
|
|
|
|
<p>While there is no special delimiter between a rule and the first
|
|
parameter a colon must be used to separate other parameters. It is also
|
|
required to end a line with a semicolon just as you are used to from
|
|
C++.</p>
|
|
|
|
<p>Please note that the programming language of Boost.Build requires
|
|
that there is a space around all tokens. For example there must be a
|
|
space on the left and on the right of the colon and there must be a
|
|
space on the left of the semicolon. Without spaces around tokens
|
|
<span class="command"><strong>b2</strong></span> won't be able to
|
|
parse Jamfiles correctly.</p>
|
|
|
|
<p>If <span class="command"><strong>b2</strong></span> is run in a
|
|
directory which contains the Jamfile above and a source file
|
|
<code class="filename">hello.cpp</code>, and if the msvc toolset is
|
|
used on Windows a subdirectory <code class=
|
|
"filename">bin\msvc-9.0\debug</code> is created to build an executable
|
|
<code class="filename">hello.exe</code>.</p>
|
|
<pre class="screen">
|
|
...found 9 targets...
|
|
...updating 5 targets...
|
|
common.mkdir bin
|
|
common.mkdir bin\msvc-9.0
|
|
common.mkdir bin\msvc-9.0\debug
|
|
compile-c-c++ bin\msvc-9.0\debug\hello.obj
|
|
hello.cpp
|
|
msvc.link bin\msvc-9.0\debug\hello.exe
|
|
msvc.manifest bin\msvc-9.0\debug\hello.exe
|
|
...updated 5 targets...
|
|
</pre>
|
|
|
|
<p>As you see it takes only one line in a Jamfile to build an
|
|
executable from a source file. And if the program is built on Windows
|
|
there is even the correct file extension <code class=
|
|
"filename">exe</code> appended.</p>
|
|
|
|
<p>The main advantage of Boost.Build is that you specify just as much
|
|
as necessary for a build system to know how to build a program.
|
|
Anything Boost.Build can do automatically is done automatically. You
|
|
don't need to detect the platform a program is built on to decide if a
|
|
file extension like <code class="filename">exe</code> should be
|
|
appended or not. And you don't need to specify how a compiler like
|
|
Visual C++ has actually to be invoked to compile source code.</p>
|
|
|
|
<p>Boost.Build supports a lot of toolsets out of the box. As a program
|
|
can be built using different toolsets Boost.Build uses toolset-specific
|
|
directories. This way it is possible to build a program with different
|
|
toolsets without a toolset constantly overwriting files produced by
|
|
another toolset.</p>
|
|
|
|
<p>There are not only toolset-specific directories but also
|
|
variant-specific directories. A variant is a debug or release version
|
|
of a program. For each variant another directory is used to build a
|
|
program - again for the reason not to overwrite files produced by
|
|
another variant. By default the debug variant is used. That's why the
|
|
subdirectory <code class="filename">bin\msvc-9.0\debug</code> was
|
|
created. If you want a release version to be created you can specify
|
|
the variant on the command line with <span class="command"><strong>b2
|
|
variant=release</strong></span> or, even simpler, <span class="command">
|
|
<strong>b2 release </strong></span>.</p>
|
|
<pre class="screen">
|
|
...found 9 targets...
|
|
...updating 5 targets...
|
|
common.mkdir bin
|
|
common.mkdir bin\msvc-9.0
|
|
common.mkdir bin\msvc-9.0\release
|
|
compile-c-c++ bin\msvc-9.0\release\hello.obj
|
|
hello.cpp
|
|
msvc.link bin\msvc-9.0\release\hello.exe
|
|
msvc.manifest bin\msvc-9.0\release\hello.exe
|
|
...updated 5 targets...
|
|
</pre>
|
|
|
|
<p>With the variant set to release the subdirectory <code class=
|
|
"filename">bin\msvc-9.0\release</code> is used to create the executable
|
|
<code class="filename">hello.exe</code>.</p>
|
|
|
|
<p>Choosing a variant is something which is done so often that it's
|
|
sufficient to enter <span class="command"><strong>b2
|
|
release</strong></span>. Boost.Build figures out that release is meant
|
|
to choose the variant.</p>
|
|
|
|
<p>If you don't want to specify the variant on the command line but
|
|
want to build release versions of <code class=
|
|
"filename">hello.exe</code> by default the Jamfile has to be
|
|
changed.</p>
|
|
<pre class="programlisting">
|
|
exe hello : hello.cpp : <variant>release ;
|
|
</pre>
|
|
|
|
<p>The <code class="code">exe</code> rule (or, if you prefer, function)
|
|
accepts a few more parameters which are optional. The third parameter
|
|
is a list of requirements. You can think of command line options which
|
|
are always set and passed to commands run to build an executable.</p>
|
|
|
|
<p>In order to force a release version to be built the variant has to
|
|
be set to release just as it was done before on the command line. The
|
|
syntax to set the variant in a Jamfile is different though.</p>
|
|
|
|
<p>Boost.Build defines features which look like XML tags. One of the
|
|
features supported by Boost.Build is <code class=
|
|
"code"><variant></code>. If a feature should be set to a value it
|
|
has to be put next to it - without a space in between. Some features
|
|
are free which means they can be set to any value you want.
|
|
<code class="code"><variant></code> is a non-free feature as it
|
|
can only be set to debug or release. No other value is allowed. If
|
|
another value is set <code class="code">b2</code> will report an
|
|
error.</p>
|
|
|
|
<p>If you run <code class="code">b2 variant=debug</code> and try to
|
|
build a debug version of <code class="filename">hello.exe</code> it
|
|
won't work as the Jamfile contains the requirement that <code class=
|
|
"filename">hello.exe</code> is built as a release version. If you want
|
|
to be able to overwrite the feature on the command line you have to
|
|
pass the feature as the fourth parameter instead of the third.</p>
|
|
<pre class="programlisting">
|
|
exe hello : hello.cpp : : <variant>release ;
|
|
</pre>
|
|
|
|
<p>The fourth parameter contains features which are used by default but
|
|
which can be overwritten.</p>
|
|
|
|
<p>If you want both a debug and a release version of <code class=
|
|
"filename">hello.exe</code> to be built by default the <code class=
|
|
"code"><variant></code> feature needs to be set twice to debug
|
|
and release.</p>
|
|
<pre class="programlisting">
|
|
exe hello : hello.cpp : : <variant>debug <variant>release ;
|
|
</pre>
|
|
|
|
<p>It is important that <code class="code"><variant></code> is
|
|
set twice in the fourth parameter where default values are specified.
|
|
If it was the third parameter where requirements are specified
|
|
<span class="command"><strong>b2</strong></span> would report an
|
|
error. It is possible to set a feature multiple times in the
|
|
requirements but only if values are not mutually exclusive. As a
|
|
program can't be a debug and a release version at the same time
|
|
<code class="code"><variant></code> must be set in the default
|
|
values. Only then Boost.Build understands that two versions of
|
|
<code class="filename">hello.exe</code> should be built.</p>
|
|
<pre class="programlisting">
|
|
exe hello : hello.cpp : <define>WIN32 <define>_WIN32 : <variant>debug <variant>release ;
|
|
</pre>
|
|
|
|
<p>The above Jamfile is an example for setting a feature multiple times
|
|
in the requirements. The feature <code class=
|
|
"code"><define></code> is used to define preprocessor directives.
|
|
It is no problem to define several preprocessor directives. Thus there
|
|
are now two versions of <code class="filename">hello.exe</code> built
|
|
both with the two directives <code class="code">WIN32</code> and
|
|
<code class="code">_WIN32</code> defined.</p>
|
|
<pre class="programlisting">
|
|
exe hello : hello.cpp : : <variant>debug <variant>release <define>WIN32 <define>_WIN32 ;
|
|
</pre>
|
|
|
|
<p>If the definitions are moved to the fourth parameter and you run
|
|
<span class="command"><strong>b2</strong></span> you get the same two
|
|
versions of <code class="filename">hello.exe</code> built with the two
|
|
directives <code class="code">WIN32</code> and <code class=
|
|
"code">_WIN32</code>. As <code class="code"><define></code> does
|
|
not expect mutually exclusive values there is no other set of
|
|
executables generated. The only difference between this Jamfile and the
|
|
previous one is that directives passed in the fourth parameter are
|
|
default values which can be dropped while anything passed as a third
|
|
parameter is an immutable requirement.</p>
|
|
|
|
<p>Here is another example of a feature whose values are mutually
|
|
exclusive.</p>
|
|
<pre class="programlisting">
|
|
exe hello : hello.cpp : : <variant>debug <variant>release <optimization>speed <optimization>off ;
|
|
</pre>
|
|
|
|
<p><span class="command"><strong>b2</strong></span> creates four
|
|
versions of <code class="filename">hello.exe</code>: A debug version
|
|
optimized for speed, a debug version with no optimization, a release
|
|
version optimized for speed and a release version with no optimization.
|
|
All of these versions are built in seperate directories which are
|
|
automatically created.</p>
|
|
|
|
<p>So far the only rule used was <code class="code">exe</code>. But of
|
|
course Boost.Build provides many more built-in rules. Another important
|
|
rule is <code class="code">lib</code>. It is used to build a
|
|
library.</p>
|
|
<pre class="programlisting">
|
|
lib world : world.cpp ;
|
|
</pre>
|
|
|
|
<p>The above Jamfile builds a shared library from the source file
|
|
<code class="filename">world.cpp</code>. On Windows a file <code class=
|
|
"filename">world.dll</code> is created. The usual file extension is
|
|
again automatically appended by Boost.Build.</p>
|
|
|
|
<p>By default a shared library is built. If you want a static library
|
|
to be generated you set the <code class="code"><link></code>
|
|
feature to static.</p>
|
|
<pre class="programlisting">
|
|
lib world : world.cpp : <link>static ;
|
|
</pre>
|
|
|
|
<p>Another useful rule is <code class="code">install</code>. After
|
|
executables and libraries have been built this rule can be used to
|
|
install them.</p>
|
|
<pre class="programlisting">
|
|
exe hello : hello.cpp ;
|
|
install "C:/Program Files/hello" : hello ;
|
|
</pre>
|
|
|
|
<p>The above Jamfile installs the executable <code class=
|
|
"filename">hello.exe</code> to the directory <code class=
|
|
"filename">C:\Program Files\hello</code>. The second parameter hello is
|
|
a reference to the target hello defined in the first line. Please note
|
|
that the path has to be put in quotes as it contains a space.</p>
|
|
|
|
<p>Here concepts known from other build systems shine through: Instead
|
|
of thinking of function calls every line defines a target. Dependencies
|
|
are created by referencing other targets. That's how Boost.Build knows
|
|
in what order it should build targets.</p>
|
|
|
|
<p>Typically the rule <code class="code">install</code> is written
|
|
differently though. Instead of passing the installation directory as
|
|
the first parameter a feature <code class=
|
|
"code"><location></code> is used to set the installation
|
|
directory in the third parameter.</p>
|
|
<pre class="programlisting">
|
|
exe hello : hello.cpp ;
|
|
install install-bin : hello : <location>"C:/Program Files/hello" ;
|
|
</pre>
|
|
|
|
<p>The main reason why it's better to use <code class=
|
|
"code"><location></code> is that the first parameter always
|
|
defines a target. Other rules might refer to a target. That's why it is
|
|
a good idea to use target names which don't have to be changed later.
|
|
Imagine a program should be installed to a different directory. It's
|
|
easier to change the installation directory if the <code class=
|
|
"code"><location></code> feature has been used as no other rules
|
|
which might refer to install-bin have to be updated.</p>
|
|
|
|
<p>There is another reason why it makes sense to use a feature.
|
|
Boost.Build supports conditional properties which make it possible to
|
|
use different installation directories depending on the platform a
|
|
program is built on.</p>
|
|
<pre class="programlisting">
|
|
exe hello : hello.cpp ;
|
|
install install-bin : hello : <target-os>windows:<location>"C:/Program Files/hello" <target-os>linux:<location>/usr/local/bin ;
|
|
</pre>
|
|
|
|
<p>The feature <code class="code"><target-os></code> is another
|
|
feature with mutually exclusive values. It can be set for example to
|
|
windows or linux but not to both.</p>
|
|
|
|
<p>The feature <code class="code"><location></code> follows
|
|
<code class="code"><target-os></code> only delimited by a colon.
|
|
Such a construct is called conditional property: Boost.Build selects
|
|
the installation directory depending on the operating system.</p>
|
|
|
|
<p>Of course conditional properties can also be used with other rules.
|
|
It is for example possible to define different preprocessor directives
|
|
depending on the variant when building a program or a library.</p>
|
|
|
|
<p>Boost.Build provides many more built-in rules. Another useful rule
|
|
is <code class="code">glob</code> which makes it possible to use
|
|
wildcards. In a big project with many source files it's then not
|
|
required to list them all one by one but refer to all of them with
|
|
<code class="code">glob</code>.</p>
|
|
<pre class="programlisting">
|
|
exe hello : [ glob *.cpp ] ;
|
|
</pre>
|
|
|
|
<p>The above Jamfile contains a nested function call: The result of the
|
|
rule <code class="code">glob</code> is passed as the second parameter
|
|
to <code class="code">exe</code>. Due to requirements of the
|
|
programming language Boost.Build is based on brackets must be used for
|
|
nested function calls.</p>
|
|
</div>
|
|
<hr>
|
|
|
|
<h2 id="project_management">Project management<br>
|
|
<small>Multiple Jamfiles</small>
|
|
</h2>
|
|
|
|
<div>
|
|
|
|
<p>In large projects with many Jamfiles it's necessary to connect
|
|
Jamfiles somehow. There is typically a <code class=
|
|
"filename">Jamroot.jam</code> file in the project's root directory and
|
|
many <code class="filename">Jamfile.jam</code> files in subdirectories.
|
|
If <span class="command"><strong>b2</strong></span> is run in the
|
|
root directory developers probably expect that the entire project
|
|
including all components in subdirectories is built. As <span class=
|
|
"command"><strong>b2</strong></span> looks for Jamfiles in parent
|
|
directories but not in subdirectories Jamfiles need to refer to
|
|
Jamfiles in subdirectories explicitly.</p>
|
|
<pre class="programlisting">
|
|
build-project hello ;
|
|
</pre>
|
|
|
|
<p>If a Jamfile looks like the sample above it refers to a Jamfile in a
|
|
subdirectory <code class="filename">hello</code>. <code class=
|
|
"code">build-project</code> is a rule which expects a path as its sole
|
|
parameter. The path is then used to lookup a Jamfile.</p>
|
|
<pre class="programlisting">
|
|
build-project hello ;
|
|
build-project world ;
|
|
</pre>
|
|
|
|
<p>If you want several projects to be built you must use <code class=
|
|
"code">build-project</code> multiple times.</p>
|
|
|
|
<p>Apart from referring to Jamfiles in subdirectories it makes also
|
|
sense to group options which should be used when building components in
|
|
a project.</p>
|
|
<pre class="programlisting">
|
|
project : default-build release ;
|
|
build-project hello ;
|
|
build-project world ;
|
|
</pre>
|
|
|
|
<p>The <code class="code">project</code> rule accepts various
|
|
parameters to set options for the Jamfile in the current working
|
|
directory and in subdirectories.</p>
|
|
|
|
<p>While other rules like <code class="code">exe</code> and
|
|
<code class="code">lib</code> expect parameters to be passed in a
|
|
certain order <code class="code">project</code> uses named arguments.
|
|
In the sample above the argument's name is default-build. That's why it
|
|
is possible to pass the value release in a very different
|
|
parameter.</p>
|
|
<pre class="programlisting">
|
|
project : : : : : : : : : default-build release ;
|
|
build-project hello ;
|
|
build-project world ;
|
|
</pre>
|
|
|
|
<p>It doesn't make sense to pass release as the tenth parameter. But it
|
|
works as <code class="code">project</code> doesn't care about the
|
|
order. As the tenth parameter is called default-build it is
|
|
accepted.</p>
|
|
|
|
<p><code class="code">project</code> supports only a few named
|
|
arguments. Another one is requirements which can be used to set options
|
|
which can't be overwritten.</p>
|
|
<pre class="programlisting">
|
|
project : requirements <variant>release ;
|
|
build-project hello ;
|
|
build-project world ;
|
|
</pre>
|
|
|
|
<p>The Jamfile above builds only release versions. It is not possible
|
|
to build a debug version anymore as requirements can not be
|
|
overwritten. That's the difference to the named argument called
|
|
default-build which was used in the previous sample: It can be
|
|
overwritten.</p>
|
|
|
|
<p>When <code class="code">build-project</code> is used Boost.Build
|
|
assumes that the parameter is a reference to a subdirectory. We had
|
|
seen another type of reference before.</p>
|
|
<pre class="programlisting">
|
|
exe hello : hello.cpp ;
|
|
install install-bin : hello : <location>"C:/Program Files/hello" ;
|
|
</pre>
|
|
|
|
<p>In the above Jamfile the <code class="code">install</code> rule
|
|
refers to the target hello defined in the first line.</p>
|
|
|
|
<p>In a large project it might be necessary to refer to targets which
|
|
are defined in Jamfiles in other directories. It is possible to
|
|
concatenate a path to a Jamfile and a target with a double slash.</p>
|
|
<pre class="programlisting">
|
|
install install-bin : subdir//hello : <location>"C:/Program Files/hello" ;
|
|
</pre>
|
|
|
|
<p>Now the <code class="code">install</code> rule refers to a target
|
|
hello in a Jamfile in the subdirectory <code class=
|
|
"filename">subdir</code>.</p>
|
|
|
|
<p>Let's assume that the executable <span class=
|
|
"command"><strong>hello</strong></span> depends on a library in another
|
|
directory <code class="filename">world</code>. The library is also
|
|
built with Boost.Build using the rule <code class=
|
|
"code">lib</code>.</p>
|
|
<pre class="programlisting">
|
|
lib world : world.cpp ;
|
|
</pre>
|
|
|
|
<p>In the Jamfile to build the executable a reference is required to
|
|
the Jamfile of the library. It's not necessary to refer to the target
|
|
world directly as all targets in a Jamfile are built by default.</p>
|
|
<pre class="programlisting">
|
|
exe hello : hello.cpp world : : <variant>debug <variant>release ;
|
|
</pre>
|
|
|
|
<p>The above Jamfile assumes that the library and its Jamfile are in a
|
|
subdirectory <code class="filename">world</code>.</p>
|
|
|
|
<p>When the executable is built there are two versions generated - a
|
|
debug and a release version. The Jamfile of the library however doesn't
|
|
set the <code class="code"><variant></code> feature. But
|
|
Boost.Build assumes that it should build two versions of the library,
|
|
too. The feature <code class="code"><variant></code> is said to
|
|
be propagated.</p>
|
|
|
|
<p>Propagating features simplify project management as you don't need
|
|
to set the same features in various Jamfiles. However it also makes it
|
|
a bit more complicated to understand how components are built as it all
|
|
depends on what features are propagated. You can assume that
|
|
Boost.Build knows what it should do. But of course it doesn't mean that
|
|
you easily understand what it does.</p>
|
|
|
|
<p>Let's look at another example using the feature <code class=
|
|
"code"><define></code>.</p>
|
|
<pre class="programlisting">
|
|
exe hello : hello.cpp world : <define>WIN32 : <variant>debug <variant>release ;
|
|
</pre>
|
|
|
|
<p>The above Jamfile defines a preprocessor directive <code class=
|
|
"code">WIN32</code> for the program <span class=
|
|
"command"><strong>hello</strong></span>. But will <code class=
|
|
"code">WIN32</code> be defined for the library, too?</p>
|
|
|
|
<p>It won't as <code class="code"><define></code> is not a
|
|
propagating feature. If you wonder how you should know: The only way to
|
|
find out which features are propagated is to lookup the
|
|
documentation.</p>
|
|
|
|
<p>If you installed the Boost C++ libraries you probably want to link
|
|
against some of them. You somehow have to add a dependency to the
|
|
respective Boost C++ library to your project's Jamfile. If you didn't
|
|
delete the directories you had unzipped the source files of the Boost
|
|
C++ libraries to you can refer to a target in a Jamfile in the root
|
|
directory.</p>
|
|
<pre class="programlisting">
|
|
exe hello : hello.cpp world C:/boost_1_39_0//filesystem/ ;
|
|
</pre>
|
|
|
|
<p>Now <span class="command"><strong>hello</strong></span> also depends
|
|
on the Boost.Filesystem library. As the target filesystem is defined in
|
|
a Jamfile in the root directory of the Boost C++ libraries the
|
|
<code class="code">exe</code> rule can refer to it. Not only will the
|
|
appropriate Boost C++ libraries be linked - an include directory is
|
|
also passed to the compiler to find the header files. If <code class=
|
|
"filename">hello.cpp</code> includes <code class=
|
|
"filename">boost/filesystem.hpp</code> the header file will be
|
|
found.</p>
|
|
|
|
<p>In the above Jamfile the path to the root directory of the Boost C++
|
|
libraries is hardcoded. Somehow <span class=
|
|
"command"><strong>b2</strong></span> needs to know where to find the
|
|
Boost C++ libraries. But it would be better if the path was hardcoded
|
|
only once in case several components in a project need to link against
|
|
some Boost C++ libraries.</p>
|
|
<pre class="programlisting">
|
|
project : requirements <variant>release ;
|
|
use-project /boost : C:/boost_1_39_0 ;
|
|
build-project hello ;
|
|
build-project world ;
|
|
</pre>
|
|
|
|
<p>The <code class="code">use-project</code> rule is used to define an
|
|
alias to a Jamfile in another directory. Jamfiles in subdirectories use
|
|
then the alias to refer to a Boost C++ library.</p>
|
|
<pre class="programlisting">
|
|
exe hello : hello.cpp world /boost//filesystem ;
|
|
</pre>
|
|
|
|
<p><span class="command"><strong>b2</strong></span> figures out that
|
|
<code class="filename">hello.cpp</code> is a source file, <code class=
|
|
"filename">world</code> a subdirectory and /boost//filesystem a
|
|
reference to a target filesystem in a Jamfile in <code class=
|
|
"filename">C:\boost_1_39_0</code>.</p>
|
|
|
|
<p>Please note that a reference must start with a slash if it should
|
|
refer to a project.</p>
|
|
|
|
<p>As libraries can be linked differently it is possible to set
|
|
features relevant to the linker.</p>
|
|
<pre class="programlisting">
|
|
exe hello : hello.cpp world /boost//filesystem/<link>static ;
|
|
</pre>
|
|
|
|
<p>By default libraries are linked dynamically. If libraries should be
|
|
linked statically the feature <code class="code"><link></code>
|
|
has to be set to static.</p>
|
|
|
|
<p>Features can be appended with a slash. If more than one feature
|
|
should be set it is appended with another slash to the previous
|
|
feature.</p>
|
|
<pre class="programlisting">
|
|
exe hello : hello.cpp world /boost//filesystem/<link>static/<threading>multi ;
|
|
</pre>
|
|
|
|
<p><code class="code"><threading></code> is another feature which
|
|
can be set to single or multi. If <span class=
|
|
"command"><strong>hello</strong></span> should be linked against the
|
|
thread-safe version of Boost.Filesystem the feature can be set
|
|
accordingly.</p>
|
|
|
|
<p>Linking a Boost C++ library by referencing a Jamfile might not
|
|
always work. If the Boost C++ libraries were installed differently
|
|
because they weren't built from source for example there won't be any
|
|
Jamfile to reference.</p>
|
|
<pre class="programlisting">
|
|
lib filesystem : : <name>libboost_filesystem <search>C:/libs ;
|
|
exe hello : hello.cpp world filesystem : <include>C:/include ;
|
|
</pre>
|
|
|
|
<p>The <code class="code">lib</code> rule can not only be used to build
|
|
a library from source. It also has to be used to refer to an existing
|
|
and pre-built library.</p>
|
|
|
|
<p>If <code class="code">lib</code> shouldn't build a library from
|
|
source the second parameter must be empty. Instead in the third
|
|
parameter the features <code class="code"><name></code> and
|
|
<code class="code"><search></code> are used to specify the
|
|
library's name and a location where Boost.Build will find the
|
|
library.</p>
|
|
|
|
<p>It is important to specify the library's name in a
|
|
platform-independent way. For example for the Jamfile above Boost.Build
|
|
will try to find a file <code class=
|
|
"filename">libboost_filesystem.lib</code> on Windows. The usual file
|
|
extension is again automatically appended.</p>
|
|
|
|
<p>If you want to reference a file by specifying its exact name you can
|
|
use the <code class="code"><file></code> feature.</p>
|
|
|
|
<p>If a system library should be referenced for which you can expect
|
|
Boost.Build to know where to find it the feature <code class=
|
|
"code"><search></code> can be dropped.</p>
|
|
|
|
<p>It is also possible to use the <code class="code">project</code>
|
|
rule to make sure all targets in a project are automatically linked
|
|
against a library.</p>
|
|
<pre class="programlisting">
|
|
lib filesystem : : <name>libboost_filesystem <search>C:/libs ;
|
|
explicit filesystem ;
|
|
project : requirements <include>C:/include <library>filesystem ;
|
|
lib world : world.cpp ;
|
|
</pre>
|
|
|
|
<p>A feature called <code class="code"><library></code> must be
|
|
used to add a library dependency to a <code class="code">project</code>
|
|
rule. <code class="code"><library></code> must refer to a
|
|
<code class="code">lib</code> rule which uses the already known
|
|
features <code class="code"><name></code> and <code class=
|
|
"code"><search></code>.</p>
|
|
|
|
<p>It is now very important to make the <code class="code">lib</code>
|
|
rule explicit. This is done by using the <code class=
|
|
"code">explicit</code> rule. It is important as by default all targets
|
|
in a Jamfile are built. As the <code class="code">project</code> rule
|
|
defines requirements for all targets in the Jamfile they are also
|
|
requirements for the <code class="code">lib</code> rule. Thus the
|
|
<code class="code">lib</code> rule refers to itself. If the
|
|
<code class="code">lib</code> rule is made explicit though it's not
|
|
built and no recursive reference occurs.</p>
|
|
|
|
<p>Please note that the order of rules in a Jamfile matters only if a
|
|
rule refers to a target: Before a target can be referenced it must have
|
|
been defined.</p>
|
|
</div>
|
|
<hr>
|
|
|
|
<h2 id="best_practices">Best practices<br>
|
|
<small>How Boost.Build is used by others</small>
|
|
</h2>
|
|
|
|
<div>
|
|
|
|
<p>As Boost.Build is a high-level build system you benefit most if you
|
|
keep Jamfiles platform- and compiler-independent. After all the idea is
|
|
to build your C++ or C projects on any platform with any compiler
|
|
without being required to modify or maintain several Jamfiles.</p>
|
|
|
|
<p>A typical problem you'll run into is that third-party libraries you
|
|
want to use will be installed in different directories. If you want to
|
|
build your project on Windows and Unix platforms paths also look very
|
|
different. Furthermore you might need to link against some system
|
|
libraries on a platform but not on another.</p>
|
|
|
|
<p>Instead of trying to put paths for various platforms in a project's
|
|
Jamfiles it is better to rely on configuration files on every system
|
|
for system-specific settings. As it turns out <span class=
|
|
"command"><strong>b2</strong></span> does indeed look for two more
|
|
configuration files when it starts.</p>
|
|
|
|
<p>The file <code class="filename">site-config.jam</code> should be
|
|
used to set options for an entire system. As it is machine-dependent
|
|
<span class="command"><strong>b2</strong></span> expects to find it
|
|
in <code class="filename">C:\Windows</code> on Windows platforms and in
|
|
<code class="filename">/etc</code> on Unix systems. As <code class=
|
|
"filename">site-config.jam</code> is machine-dependent paths to local
|
|
libraries are no problem.</p>
|
|
|
|
<p>Users might not be able to create or change <code class=
|
|
"filename">site-config.jam</code> though. They would either need to
|
|
wait for system administrators to update the file or be forced again to
|
|
add system-specific paths to their own Jamfiles. As neither is a good
|
|
solution, <span class="command"><strong>b2</strong></span> also looks
|
|
for a file <code class="filename">user-config.jam</code> in a user's
|
|
home directory. On Windows it is a subdirectory of <code class=
|
|
"filename">C:\Users</code>, on Unix a subdirecory of <code class=
|
|
"filename">/home</code>. As the file <code class=
|
|
"filename">user-config.jam</code> can be maintained by users it is
|
|
probably used more often than <code class=
|
|
"filename">site-config.jam</code>.</p>
|
|
|
|
<p>You use <code class="filename">site-config.jam</code> and
|
|
<code class="filename">user-config.jam</code> just like any other
|
|
Jamfile. As these configuration files do not belong to a project but to
|
|
a machine or a user on a machine they are allowed to contain
|
|
machine-specific options. For example they could contain a <code class=
|
|
"code">using</code> rule.</p>
|
|
<pre class="programlisting">
|
|
using msvc ;
|
|
</pre>
|
|
|
|
<p>The <code class="code">using</code> rule above tells <span class=
|
|
"command"><strong>b2</strong></span> to use the msvc toolset. If you
|
|
know that there is only Visual C++ installed on a system it makes sense
|
|
to put this line into a configuration file. Then <span class=
|
|
"command"><strong>b2</strong></span> doesn't need to guess anymore
|
|
which toolset to use and won't omit a warning.</p>
|
|
|
|
<p>If you define targets in <code class=
|
|
"filename">site-config.jam</code> or <code class=
|
|
"filename">user-config.jam</code> and want to refer to these targets in
|
|
Jamfiles the <code class="code">project</code> rule must be used to set
|
|
a name.</p>
|
|
<pre class="programlisting">
|
|
using msvc ;
|
|
project user-config ;
|
|
lib xml : : <name>libxml <search>C:/lib : : <include>C:/include ;
|
|
</pre>
|
|
|
|
<p>The <code class="code">lib</code> rule is used to refer to a
|
|
pre-built library whose basename is libxml and can be found in
|
|
<code class="filename">C:\lib</code>. A program which uses this XML
|
|
library probably needs to include header files from this library.
|
|
That's why in the usage requirements - this is the fifth parameter -
|
|
the feature <code class="code"><include></code> is set to
|
|
<code class="filename">C:\include</code>: Whoever uses this rule will
|
|
inherit the <code class="code"><include></code> feature.</p>
|
|
|
|
<p>As the <code class="code">project</code> rule has been used to set
|
|
the name user-config a Jamfile can refer to the XML library via
|
|
/user-config//xml.</p>
|
|
<pre class="programlisting">
|
|
exe xmlparser : xmlparser.cpp : <library>/user-config//xml ;
|
|
</pre>
|
|
|
|
<p>In order to build <span class=
|
|
"command"><strong>xmlparser</strong></span> the program must be linked
|
|
against the XML library. Even though the location of the library and
|
|
its header files might vary the Jamfile does not contain any
|
|
system-specific paths. The Jamfile expects to find the target xml in
|
|
the project user-config. If this is a configuration file it's no
|
|
problem to use system-specific paths as after all configuration files
|
|
are bound to a machine or to a user on a machine.</p>
|
|
|
|
<p>As Boost.Build has been created to build and install the Boost C++
|
|
libraries there is built-in support to use pre-built Boost C++
|
|
libraries more easily.</p>
|
|
<pre class="programlisting">
|
|
using msvc ;
|
|
project user-config ;
|
|
using boost : 1.39 : <include>C:/include/boost-1_39 <library>C:/lib ;
|
|
</pre>
|
|
|
|
<p>The <code class="code">using</code> rule must be used to refer to a
|
|
toolset called boost. This toolset is different from toolsets like msvc
|
|
which you've read about so far: It doesn't contain any programs which
|
|
will be run later. As support for pre-built Boost C++ libraries has
|
|
been implemented in a toolset though it's required to use the
|
|
<code class="code">using</code> rule.</p>
|
|
|
|
<p>Just as with other libraries the location of the Boost C++ libraries
|
|
might vary. Thus it makes sense to put the <code class=
|
|
"code">using</code> rule into one of the two configuration files.</p>
|
|
|
|
<p>It is possible to pass parameters to the <code class=
|
|
"code">using</code> rule: The first one is the version number, the
|
|
second a list of options. In the Jamfile above the Boost C++ libraries
|
|
1.39 are used which can be found in the directories passed as
|
|
options.</p>
|
|
|
|
<p>Once the boost toolset is used it is possible to use Boost C++
|
|
libraries without defining targets yourself.</p>
|
|
<pre class="programlisting">
|
|
import boost ;
|
|
boost.use-project 1.39 ;
|
|
exe hello : hello.cpp : <library>/boost//thread ;
|
|
</pre>
|
|
|
|
<p>If a program uses a Boost C++ library it can refer to targets in a
|
|
project called boost. In order to recognize the project boost though
|
|
the boost module must be imported and the rule <code class=
|
|
"code">boost.use-project</code> used: Importing the boost module makes
|
|
the <code class="code">boost.use-project</code> rule available. This
|
|
rule expects a version number as its sole argument. As it is possible
|
|
to use the <code class="code">using</code> rule to refer to various
|
|
versions of the Boost C++ libraries a project can specify which version
|
|
it wants to use. In the Jamfile above the program <span class=
|
|
"command"><strong>hello</strong></span> uses Boost.Thread from version
|
|
1.39.</p>
|
|
</div>
|
|
<hr>
|
|
|
|
<h2 id="rule_reference">Rule reference<br>
|
|
<small>Building blocks for Jamfiles</small>
|
|
</h2>
|
|
|
|
<div>
|
|
|
|
<p>If you manage a project with Boost.Build and create Jamfiles you use
|
|
rules all the time. Thus you should know which rules exist and how they
|
|
are used. The following table gives you an overview about the most
|
|
important rules.</p>
|
|
|
|
<p>There is a star, plus sign or question mark behind some parameters.
|
|
The star means there can be arbitrary many values, the plus sign there
|
|
must be at least one value and the question mark there must be zero or
|
|
exactly one value.</p>
|
|
|
|
<table border="0" cellspacing="0" cellpadding="0" id="id369340">
|
|
<caption>
|
|
Table 1. Rules
|
|
</caption>
|
|
|
|
<tbody>
|
|
<tr>
|
|
<th class="col-md-2">Name</th>
|
|
|
|
<th>Parameters</th>
|
|
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>alias</td>
|
|
|
|
<td>name : sources * : requirements * : default-build * :
|
|
usage-requirements *</td>
|
|
|
|
<td>Refer to sources or any other targets via a new name.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>build-project</td>
|
|
|
|
<td>dir</td>
|
|
|
|
<td>Refer to a Jamfile in another directory to build a
|
|
project.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>conditional</td>
|
|
|
|
<td>condition + : requirements *</td>
|
|
|
|
<td>Create conditional requirements without using conditional
|
|
properties.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>exe</td>
|
|
|
|
<td>name : sources * : requirements * : default-build * :
|
|
usage-requirements *</td>
|
|
|
|
<td>Build an executable.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>explicit</td>
|
|
|
|
<td>target-names *</td>
|
|
|
|
<td>Make targets explicit.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>glob</td>
|
|
|
|
<td>wildcards + : excludes *</td>
|
|
|
|
<td>Reference files in a directory via wildcards.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>glob-tree</td>
|
|
|
|
<td>wildcards + : excludes *</td>
|
|
|
|
<td>Reference files in a directory and all subdirectories via
|
|
wildcards.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>install</td>
|
|
|
|
<td>name-and-dir : sources * : requirements * : default-build
|
|
*</td>
|
|
|
|
<td>Install files to a directory.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>lib</td>
|
|
|
|
<td>names + : sources * : requirements * : default-build * :
|
|
usage-requirements *</td>
|
|
|
|
<td>Build a library.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>project</td>
|
|
|
|
<td>id ? : options * : *</td>
|
|
|
|
<td>Set project options.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>unit-test</td>
|
|
|
|
<td>target : source : properties *</td>
|
|
|
|
<td>Build and run an executable.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>use-project</td>
|
|
|
|
<td>id : where</td>
|
|
|
|
<td>Reference a Jamfile in another directory to use the project
|
|
id as a target.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>using</td>
|
|
|
|
<td>toolset-module : *</td>
|
|
|
|
<td>Select a toolset.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<p>Your Boost.Build version might support more rules than listed above.
|
|
If you want to find out which rules are supported you should check out
|
|
the files in the subdirectory <code class="filename">build</code> of
|
|
your Boost.Build installation.</p>
|
|
</div>
|
|
<hr>
|
|
|
|
<h2 id="feature_reference">Feature reference<br>
|
|
<small>Configuration options for the build process</small>
|
|
</h2>
|
|
|
|
<div>
|
|
|
|
<p>Features allow you to specify exactly how binaries are built. As
|
|
there are many configuration options available the list of features is
|
|
pretty long. The following table introduces you to the most important
|
|
features.</p>
|
|
|
|
<table border="0" cellspacing="0" cellpadding="0" id="id369624">
|
|
<caption>
|
|
Table 2. Features
|
|
</caption>
|
|
|
|
<tbody>
|
|
<tr>
|
|
<th class="col-md-2">Name</th>
|
|
|
|
<th>Values</th>
|
|
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><address-model></td>
|
|
|
|
<td>16, 32, 64, 32_64</td>
|
|
|
|
<td>Generate 16-, 32- or 64-bit code.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><architecture></td>
|
|
|
|
<td>x86, ia64, sparc, power, mips1, mips2, mips3, mips4, mips32,
|
|
mips32r2, mips64, parisc, arm, combined, combined-x86-power</td>
|
|
|
|
<td>Set processor family to generate code for.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><c++-template-depth></td>
|
|
|
|
<td>1, 2, 3, ...</td>
|
|
|
|
<td>Set maximum template depth.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><cflags></td>
|
|
|
|
<td>...</td>
|
|
|
|
<td>Pass flags to C compiler.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><cxxflags></td>
|
|
|
|
<td>...</td>
|
|
|
|
<td>Pass flags to C++ compiler</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><debug-symbols></td>
|
|
|
|
<td>on, off</td>
|
|
|
|
<td>Create debug symbols.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><def-file></td>
|
|
|
|
<td>...</td>
|
|
|
|
<td>Set path to <code class="filename">def</code> file (specific
|
|
to Windows DLLs).</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><define></td>
|
|
|
|
<td>...</td>
|
|
|
|
<td>Define preprocessor directives.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><embed-manifest></td>
|
|
|
|
<td>on, off</td>
|
|
|
|
<td>Embed manifest (specific to msvc toolset).</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><host-os></td>
|
|
|
|
<td>aix, bsd, cygwin, darwin, freebsd, hpux, iphone, linux,
|
|
netbsd, openbsd, osf, qnx, qnxnto, sgi, solaris, unix, unixware,
|
|
windows</td>
|
|
|
|
<td>Use in conditional properties if features depend on host
|
|
operating systems.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><include></td>
|
|
|
|
<td>...</td>
|
|
|
|
<td>Set include directories.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><inlining></td>
|
|
|
|
<td>off, on, full</td>
|
|
|
|
<td>Inline functions.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><library></td>
|
|
|
|
<td>...</td>
|
|
|
|
<td>Link to a library (use in <code class="code">project</code>
|
|
rule).</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><link></td>
|
|
|
|
<td>shared, static</td>
|
|
|
|
<td>Link to shared or static version of a library.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><linkflags></td>
|
|
|
|
<td>...</td>
|
|
|
|
<td>Pass flags to linker.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><location></td>
|
|
|
|
<td>...</td>
|
|
|
|
<td>Set directory (use in <code class="code">install</code>
|
|
rule).</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><name></td>
|
|
|
|
<td>...</td>
|
|
|
|
<td>Set basename of a library (use in <code class=
|
|
"code">lib</code> rule).</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><optimization></td>
|
|
|
|
<td>off, speed, space</td>
|
|
|
|
<td>Generate optimized code.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><profiling></td>
|
|
|
|
<td>off, on</td>
|
|
|
|
<td>Generate profiled code.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><runtime-link></td>
|
|
|
|
<td>shared, static</td>
|
|
|
|
<td>Link to single-threaded or thread-safe runtime library.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><search></td>
|
|
|
|
<td>...</td>
|
|
|
|
<td>Set directory to search for libraries (use in <code class=
|
|
"code">lib</code> rule together with <code class=
|
|
"code"><name></code>).</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><source></td>
|
|
|
|
<td>...</td>
|
|
|
|
<td>Set source in requirements parameter of <code class=
|
|
"code">project</code> rule or in conditional properties.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><target-os></td>
|
|
|
|
<td>aix, appletv, bsd, cygwin, darwin, freebsd, hpux, iphone, linux,
|
|
netbsd, openbsd, osf, qnx, qnxnto, sgi, solaris, unix, unixware,
|
|
windows</td>
|
|
|
|
<td>Use in conditional properties if features depend on target
|
|
operating systems.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><threading></td>
|
|
|
|
<td>single, multi</td>
|
|
|
|
<td>Build singlethreaded or thread-safe version.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><toolset></td>
|
|
|
|
<td>gcc, msvc, intel-linux, intel-win, acc, borland, como-linux,
|
|
cw, dmc, hp_cxx, sun</td>
|
|
|
|
<td>Use in conditional properties if features depend on
|
|
toolsets.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><undef></td>
|
|
|
|
<td>...</td>
|
|
|
|
<td>Undefine preprocessor directives.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><use></td>
|
|
|
|
<td>...</td>
|
|
|
|
<td>Take over only usage requirements of a referenced target but
|
|
don't do anything else.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><variant></td>
|
|
|
|
<td>debug, release, profile</td>
|
|
|
|
<td>Build debug, release or profile version.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><warnings></td>
|
|
|
|
<td>on, all, off</td>
|
|
|
|
<td>Switch off warnings.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><warnings-as-errors></td>
|
|
|
|
<td>off, on</td>
|
|
|
|
<td>Treat warnings as errors.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<p>For a complete and up-to-date reference of Boost.Build features look
|
|
up the file <code class="filename">builtin.jam</code> in the
|
|
subdirectory <code class="filename">tools</code> of your Boost.Build
|
|
installation. Search for lines starting with <code class=
|
|
"code">feature.feature</code> - this is the internal rule used to
|
|
define features.</p>
|
|
</div>
|
|
|
|
<hr id="hrfoot">
|
|
<p>Copyright Boris Schäling 2009. Distributed under the Boost Software
|
|
License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
|
|
<a href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)
|
|
|
|
</div>
|
|
|
|
|
|
</body>
|
|
</html>
|