| <!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, 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> |