| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> |
| <title>Overview</title> |
| <link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css"> |
| <meta name="generator" content="DocBook XSL Stylesheets V1.75.2"> |
| <link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset"> |
| <link rel="up" href="../bbv2.html" title="Chapter 33. Boost.Build V2 User Manual"> |
| <link rel="prev" href="tutorial.html" title="Tutorial"> |
| <link rel="next" href="tasks.html" title="Common tasks"> |
| </head> |
| <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> |
| <table cellpadding="2" width="100%"><tr> |
| <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td> |
| <td align="center"><a href="../../../index.html">Home</a></td> |
| <td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td> |
| <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> |
| <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> |
| <td align="center"><a href="../../../more/index.htm">More</a></td> |
| </tr></table> |
| <hr> |
| <div class="spirit-nav"> |
| <a accesskey="p" href="tutorial.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../bbv2.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="tasks.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h2 class="title" style="clear: both"> |
| <a name="bbv2.overview"></a>Overview</h2></div></div></div> |
| <div class="toc"><dl> |
| <dt><span class="section"><a href="overview.html#bbv2.overview.concepts">Concepts</a></span></dt> |
| <dt><span class="section"><a href="overview.html#bbv2.overview.jam_language">Boost.Jam Language</a></span></dt> |
| <dt><span class="section"><a href="overview.html#bbv2.overview.configuration">Configuration</a></span></dt> |
| <dt><span class="section"><a href="overview.html#bbv2.overview.invocation">Invocation</a></span></dt> |
| <dt><span class="section"><a href="overview.html#bbv2.overview.targets">Declaring Targets</a></span></dt> |
| <dt><span class="section"><a href="overview.html#bbv2.overview.projects">Projects</a></span></dt> |
| <dt><span class="section"><a href="overview.html#bbv2.overview.build_process">The Build Process</a></span></dt> |
| </dl></div> |
| <p> |
| This section will provide the information necessary to create your own |
| projects using Boost.Build. The information provided here is relatively |
| high-level, and <a class="xref" href="reference.html" title="Reference">the section called “Reference”</a> as well as the on-line |
| help system must be used to obtain low-level documentation (see <a class="xref" href="overview.html#bbv2.reference.init.options.help"><code class="option">--help</code></a>). |
| </p> |
| <p> |
| Boost.Build actually consists of two parts - Boost.Jam, a build engine |
| with its own interpreted language, and Boost.Build itself, implemented in |
| Boost.Jam's language. The chain of events when you type |
| <span class="command"><strong>bjam</strong></span> on the command line is as follows: |
| </p> |
| <div class="orderedlist"><ol class="orderedlist" type="1"> |
| <li class="listitem"><p> |
| Boost.Jam tries to find Boost.Build and loads the top-level module. |
| The exact process is described in <a class="xref" href="reference.html#bbv2.reference.init" title="Initialization">the section called “Initialization”</a> |
| </p></li> |
| <li class="listitem"><p> |
| The top-level module loads user-defined configuration files, |
| <code class="filename">user-config.jam</code> and <code class="filename">site-config.jam |
| </code>, which define available toolsets. |
| </p></li> |
| <li class="listitem"><p> |
| The Jamfile in the current directory is read. That in turn might |
| cause reading of further Jamfiles. As a result, a tree of projects |
| is created, with targets inside projects. |
| </p></li> |
| <li class="listitem"><p> |
| Finally, using the build request specified on the command line, |
| Boost.Build decides which targets should be built and how. That |
| information is passed back to Boost.Jam, which takes care of |
| actually running the scheduled build action commands. |
| </p></li> |
| </ol></div> |
| <p> |
| </p> |
| <p> |
| So, to be able to successfully use Boost.Build, you need to know only four |
| things: |
| </p> |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"> |
| <li class="listitem"><p> |
| <a class="link" href="overview.html#bbv2.overview.configuration" title="Configuration">How to configure |
| Boost.Build</a> |
| </p></li> |
| <li class="listitem"><p> |
| <a class="link" href="overview.html#bbv2.overview.targets" title="Declaring Targets">How to declare targets in |
| Jamfiles</a> |
| </p></li> |
| <li class="listitem"><p> |
| <a class="link" href="overview.html#bbv2.overview.build_process" title="The Build Process">How the build process |
| works</a> |
| </p></li> |
| <li class="listitem"><p> |
| Some Basics about the Boost.Jam language. See <a class="xref" href="overview.html#bbv2.overview.jam_language" title="Boost.Jam Language">the section called “Boost.Jam Language”</a>. |
| </p></li> |
| </ul></div> |
| <p> |
| </p> |
| <div class="section"> |
| <div class="titlepage"><div><div><h3 class="title"> |
| <a name="bbv2.overview.concepts"></a>Concepts</h3></div></div></div> |
| <p>Boost.Build has a few unique concepts that are introduced in this section. The best |
| way to explain the concepts is by comparison with more classical build tools.</p> |
| <p> |
| When using any flavour of make, you directly specify <em class="firstterm">targets</em> |
| and commands that are used to create them from other target. The below example |
| creates <code class="filename">a.o</code> from <code class="filename">a.c</code> using a hardcoded |
| compiler invocation command. |
| </p> |
| <pre class="programlisting"> |
| a.o: a.c |
| g++ -o a.o -g a.c |
| </pre> |
| <p> |
| This is rather low-level description mechanism and it's hard to adjust commands, options, |
| and sets of created targets depending on the used compiler and operating system. |
| </p> |
| <p> |
| To improve portability, most modern build system provide a set of higher-level |
| functions that can be used in build description files. Consider this example: |
| </p> |
| <pre class="programlisting"> |
| add_program ("a", "a.c") |
| </pre> |
| <p> |
| This is a function call that creates targets necessary to create executable file |
| from source file <code class="filename">a.c</code>. Depending on configured properties, |
| different commands line may be used. However, <code class="computeroutput">add_program</code> is higher-level, |
| but rather thin level. All targets are created immediately when build description |
| is parsed, which makes it impossible to perform multi-variant builds. Often, change |
| in any build property requires complete reconfiguration of the build tree. |
| </p> |
| <p> |
| In order to support true multivariant builds, Boost.Build introduces the concept of |
| <a class="indexterm" name="id3266477"></a> |
| <a class="indexterm" name="id3266488"></a> |
| <em class="firstterm">metatarget</em>—object that is created when build description |
| is parsed and can be later called with specific build properties to generate |
| actual targets. |
| </p> |
| <p> |
| Consider an example: |
| </p> |
| <pre class="programlisting"> |
| exe a : a.cpp ; |
| </pre> |
| <p> |
| When this declaration is parsed, Boost.Build creates a metatarget, but does not |
| yet decides what files must be created, or what commands must be used. After |
| all build files are parsed, Boost.Build considers properties requested on the |
| command line. Supposed you have invoked Boost.Build with: |
| </p> |
| <pre class="screen"> |
| bjam toolset=gcc toolset=msvc |
| </pre> |
| <p> |
| In that case, the metatarget will be called twice, once with <code class="computeroutput">toolset=gcc</code> |
| and once with <code class="computeroutput">toolset=msvc</code>. Both invocations will produce concrete |
| targets, that will have different extensions and use different command lines. |
| </p> |
| <p> |
| Another key concept is |
| <a class="indexterm" name="id3266547"></a> |
| <em class="firstterm">build property</em>. Build property is a variable |
| that affects the build process. It can be specified on the command line, and is |
| passed when calling a metatarget. While all build tools have a similar mechanism, |
| Boost.Build differs by requiring that all build properties are declared in advance, |
| and providing a large set of properties with portable semantics. |
| </p> |
| <p> |
| The final concept is <a class="indexterm" name="id3266570"></a> |
| <em class="firstterm">property propagation</em>. Boost.Build does not require that every |
| metatarget is called with the same properties. Instead, the |
| "top-level" metatargets are called with the properties specified on the command line. |
| Each metatarget can elect to augment or override some properties (in particular, |
| using the requirements mechanism, see <a class="xref" href="overview.html#bbv2.overview.targets.requirements" title="Requirements">the section called “Requirements”</a>). |
| Then, the dependency metatargets are called with modified properties and produce |
| concrete targets that are then used in build process. Of course, dependency metatargets |
| maybe in turn modify build properties and have dependencies of their own. |
| </p> |
| <p>For more in-depth treatment of the requirements and concepts, you may refer |
| to <a href="http://syrcose.ispras.ru/2009/files/04_paper.pdf" target="_top">SYRCoSE 2009 Boost.Build article</a>. |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h3 class="title"> |
| <a name="bbv2.overview.jam_language"></a>Boost.Jam Language</h3></div></div></div> |
| <p> |
| This section will describe the basics of the Boost.Jam language— |
| just enough for writing Jamfiles. For more information, please see the |
| <a class="link" href="../">Boost.Jam</a> documentation. |
| </p> |
| <p> |
| <a class="link" href="../">Boost.Jam</a> has an interpreted, procedural |
| language. On the lowest level, a <a class="link" href="../">Boost.Jam |
| </a> program consists of variables and <a class="indexterm" name="id3266661"></a> <em class="firstterm">rules</em> (Jam term for |
| function). They are grouped into modules—there is one global |
| module and a number of named modules. Besides that, a <a class="link" href="../">Boost.Jam</a> program contains classes and class |
| instances. |
| </p> |
| <p> |
| Syntantically, a <a class="link" href="../">Boost.Jam</a> program |
| consists of two kind of elements—keywords (which have a special |
| meaning to <a class="link" href="../">Boost.Jam</a>) and literals. |
| Consider this code: |
| </p> |
| <pre class="programlisting"> |
| a = b ; |
| </pre> |
| <p> |
| which assigns the value <code class="literal">b</code> to the variable <code class="literal">a |
| </code>. Here, <code class="literal">=</code> and <code class="literal">;</code> are |
| keywords, while <code class="literal">a</code> and <code class="literal">b</code> are |
| literals. |
| </p> |
| <div class="warning"><table border="0" summary="Warning"> |
| <tr> |
| <td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../doc/src/images/warning.png"></td> |
| <th align="left">Warning</th> |
| </tr> |
| <tr><td align="left" valign="top"><p> |
| All syntax elements, even keywords, must be separated by spaces. For |
| example, omitting the space character before <code class="literal">;</code> |
| will lead to a syntax error. |
| </p></td></tr> |
| </table></div> |
| <p> |
| If you want to use a literal value that is the same as some keyword, the |
| value can be quoted: |
| </p> |
| <pre class="programlisting"> |
| a = "=" ; |
| </pre> |
| <p> |
| </p> |
| <p> |
| All variables in <a class="link" href="../">Boost.Jam</a> have the same |
| type—list of strings. To define a variable one assigns a value to |
| it, like in the previous example. An undefined variable is the same as a |
| variable with an empty value. Variables can be accessed using the |
| <code class="computeroutput">$(<em class="replaceable"><code>variable</code></em>)</code> syntax. For example: |
| </p> |
| <pre class="programlisting"> |
| a = $(b) $(c) ; |
| </pre> |
| <p> |
| </p> |
| <p> |
| Rules are defined by specifying the rule name, the parameter names, and |
| the allowed value list size for each parameter. |
| </p> |
| <pre class="programlisting"> |
| rule <em class="replaceable"><code>example</code></em> |
| ( |
| <em class="replaceable"><code>parameter1</code></em> : |
| <em class="replaceable"><code>parameter2 ?</code></em> : |
| <em class="replaceable"><code>parameter3 +</code></em> : |
| <em class="replaceable"><code>parameter4 *</code></em> |
| ) |
| { |
| # rule body |
| } |
| </pre> |
| <p> |
| When this rule is called, the list passed as the first argument must |
| have exactly one value. The list passed as the second argument can |
| either have one value of be empty. The two remaining arguments can be |
| arbitrarily long, but the third argument may not be empty. |
| </p> |
| <p> |
| The overview of <a class="link" href="../">Boost.Jam</a> language |
| statements is given below: |
| </p> |
| <pre class="programlisting"> |
| helper 1 : 2 : 3 ; |
| x = [ helper 1 : 2 : 3 ] ; |
| </pre> |
| <p> |
| This code calls the named rule with the specified arguments. When the |
| result of the call must be used inside some expression, you need to add |
| brackets around the call, like shown on the second line. |
| </p> |
| <pre class="programlisting"> |
| if cond { statements } [ else { statements } ] |
| </pre> |
| <p> |
| This is a regular if-statement. The condition is composed of: |
| </p> |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"> |
| <li class="listitem"><p> |
| Literals (true if at least one string is not empty) |
| </p></li> |
| <li class="listitem"><p> |
| Comparisons: <code class="computeroutput">a <em class="replaceable"><code>operator</code></em> b</code> |
| where <em class="replaceable"><code>operator</code></em> is one of |
| <code class="computeroutput">=</code>, <code class="computeroutput">!=</code>, <code class="computeroutput"><</code>, |
| <code class="computeroutput">></code>, <code class="computeroutput"><=</code> or <code class="computeroutput">>=</code>. The |
| comparison is done pairwise between each string in the left and |
| the right arguments. |
| </p></li> |
| <li class="listitem"><p> |
| Logical operations: <code class="computeroutput">! a</code>, <code class="computeroutput">a && b</code>, |
| <code class="computeroutput">a || b</code> |
| </p></li> |
| <li class="listitem"><p> |
| Grouping: <code class="computeroutput">( cond )</code> |
| </p></li> |
| </ul></div> |
| <p> |
| </p> |
| <pre class="programlisting"> |
| for var in list { statements } |
| </pre> |
| <p> |
| Executes statements for each element in list, setting the variable |
| <code class="varname">var</code> to the element value. |
| </p> |
| <pre class="programlisting"> |
| while cond { statements } |
| </pre> |
| <p> |
| Repeatedly execute statements while cond remains true upon entry. |
| </p> |
| <pre class="programlisting"> |
| return values ; |
| </pre> |
| <p> |
| This statement should be used only inside a rule and assigns |
| <code class="computeroutput">values</code> to the return value of the rule. |
| </p> |
| <div class="warning"><table border="0" summary="Warning"> |
| <tr> |
| <td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../doc/src/images/warning.png"></td> |
| <th align="left">Warning</th> |
| </tr> |
| <tr><td align="left" valign="top"> |
| <p> |
| The <code class="computeroutput">return</code> statement does not exit the rule. For |
| example: |
| </p> |
| <pre class="programlisting"> |
| rule test ( ) |
| { |
| if 1 = 1 |
| { |
| return "reasonable" ; |
| } |
| return "strange" ; |
| } |
| </pre> |
| <p> |
| will return <code class="literal">strange</code>, not |
| <code class="literal">reasonable</code>. |
| </p> |
| </td></tr> |
| </table></div> |
| <p> |
| </p> |
| <pre class="programlisting"> |
| import <em class="replaceable"><code>module</code></em> ; |
| import <em class="replaceable"><code>module</code></em> : <em class="replaceable"><code>rule</code></em> ; |
| </pre> |
| <p> |
| The first form imports the specified bjam module. All rules from that |
| module are made available using the qualified name: <code class="computeroutput"><em class="replaceable"><code> |
| module</code></em>.<em class="replaceable"><code>rule</code></em></code>. The second |
| form imports the specified rules only, and they can be called using |
| unqualified names. |
| </p> |
| <p><a name="bbv2.overview.jam_language.actions"></a> |
| Sometimes, you'd need to specify the actual command lines to be used |
| when creating targets. In jam language, you use named actions to do |
| this. For example: |
| </p> |
| <pre class="programlisting"> |
| actions create-file-from-another |
| { |
| create-file-from-another $(<) $(>) |
| } |
| </pre> |
| <p> |
| This specifies a named action called <code class="literal"> |
| create-file-from-another</code>. The text inside braces is the |
| command to invoke. The <code class="literal">$(<)</code> variable will be |
| expanded to a list of generated files, and the <code class="literal">$(>) |
| </code> variable will be expanded to a list of source files. |
| </p> |
| <p> |
| To flexibly adjust the command line, you can define a rule with the same |
| name as the action and taking three parameters -- targets, sources and |
| properties. For example: |
| </p> |
| <pre class="programlisting"> |
| rule create-file-from-another ( targets * : sources * : properties * ) |
| { |
| if <variant>debug in $(properties) |
| { |
| OPTIONS on $(targets) = --debug ; |
| } |
| } |
| actions create-file-from-another |
| { |
| create-file-from-another $(OPTIONS) $(<) $(>) |
| } |
| </pre> |
| <p> |
| In this example, the rule checks if certain build property is specified. |
| If so, it sets variable <code class="varname">OPIONS</code> that is then used |
| inside the action. Note that the variables set "on a target" will be |
| visible only inside actions building that target, not globally. Were |
| they set globally, using variable named <code class="varname">OPTIONS</code> in |
| two unrelated actions would be impossible. |
| </p> |
| <p> |
| More details can be found in Jam reference, <a class="xref" href="../jam/language.html#jam.language.rules" title="Rules">the section called “Rules”</a>. |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h3 class="title"> |
| <a name="bbv2.overview.configuration"></a>Configuration</h3></div></div></div> |
| <p> |
| On startup, Boost.Build searches and reads two configuration files: |
| <code class="filename">site-config.jam</code> and <code class="filename">user-config.jam</code>. |
| The first one is usually installed and maintained by system administrator, and |
| the second is for user to modify. You can edit the one in the top-level |
| directory of Boost.Build installation or create a copy in your home |
| directory and edit the copy. The following table explains where both files |
| are searched. |
| </p> |
| <div class="table"> |
| <a name="bbv2.reference.init.config"></a><p class="title"><b>Table 33.1. Search paths for configuration files</b></p> |
| <div class="table-contents"><table class="table" summary="Search paths for configuration files"> |
| <colgroup> |
| <col> |
| <col> |
| <col> |
| </colgroup> |
| <thead><tr> |
| <th> </th> |
| <th>site-config.jam</th> |
| <th>user-config.jam</th> |
| </tr></thead> |
| <tbody> |
| <tr> |
| <td>Linux</td> |
| <td> |
| <p><code class="computeroutput">/etc</code></p> |
| <p><code class="computeroutput">$HOME</code></p> |
| <p><code class="computeroutput">$BOOST_BUILD_PATH</code></p> |
| </td> |
| <td> |
| <p><code class="computeroutput">$HOME</code></p> |
| <p><code class="computeroutput">$BOOST_BUILD_PATH</code></p> |
| </td> |
| </tr> |
| <tr> |
| <td>Windows</td> |
| <td> |
| <p><code class="computeroutput">%SystemRoot%</code></p> |
| <p><code class="computeroutput">%HOMEDRIVE%%HOMEPATH%</code></p> |
| <p><code class="computeroutput">%HOME%</code></p> |
| <p><code class="computeroutput">%BOOST_BUILD_PATH%</code></p> |
| </td> |
| <td> |
| <p><code class="computeroutput">%HOMEDRIVE%%HOMEPATH%</code></p> |
| <p><code class="computeroutput">%HOME%</code></p> |
| <p><code class="computeroutput">%BOOST_BUILD_PATH%</code></p> |
| </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <br class="table-break"><div class="tip"><table border="0" summary="Tip"> |
| <tr> |
| <td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../doc/src/images/tip.png"></td> |
| <th align="left">Tip</th> |
| </tr> |
| <tr><td align="left" valign="top"><p> |
| You can use the <span class="command"><strong>--debug-configuration</strong></span> option to |
| find which configuration files are actually loaded. |
| </p></td></tr> |
| </table></div> |
| <p> |
| Usually, <code class="filename">user-config.jam</code> just defines available compilers |
| and other tools (see <a class="xref" href="faq.html#bbv2.recipies.site-config" title="Targets in site-config.jam">the section called “Targets in site-config.jam”</a> for more advanced |
| usage). A tool is configured using the following syntax: |
| </p> |
| <pre class="programlisting"> |
| using <em class="replaceable"><code>tool-name</code></em> : ... ; |
| </pre> |
| <p> |
| The <code class="computeroutput">using</code> rule is given a name of tool, and |
| will make that tool available to Boost.Build. For example, |
| </p> |
| <pre class="programlisting"> |
| using gcc ; |
| </pre> |
| <p> will make the <a href="http://gcc.gnu.org" target="_top">GCC</a> compiler available. |
| </p> |
| <p> |
| All the supported tools are documented in <a class="xref" href="reference.html#bbv2.reference.tools" title="Builtin tools">the section called “Builtin tools”</a>, |
| including the specific options they take. Some general notes that apply to most |
| C++ compilers are below. |
| </p> |
| <p> |
| For all the C++ compiler toolsets Boost.Build supports |
| out-of-the-box, the list of parameters to |
| <code class="computeroutput">using</code> is the same: <em class="parameter"><code>toolset-name</code></em>, <em class="parameter"><code>version</code></em>, <em class="parameter"><code>invocation-command</code></em>, and <em class="parameter"><code>options</code></em>. |
| </p> |
| <p>If you have a single compiler, and the compiler executable |
| </p> |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"> |
| <li class="listitem"><p>has its “usual name” and is in the |
| <code class="envar">PATH</code>, or</p></li> |
| <li class="listitem"><p>was installed in a standard “installation |
| directory”, or</p></li> |
| <li class="listitem"><p>can be found using a global system like the Windows |
| registry.</p></li> |
| </ul></div> |
| <p> |
| it can be configured by simply:</p> |
| <pre class="programlisting"> |
| using <em class="replaceable"><code>tool-name</code></em> ; |
| </pre> |
| <p>If the compiler is installed in a custom directory, you should provide the |
| command that invokes the compiler, for example:</p> |
| <pre class="programlisting"> |
| using gcc : : g++-3.2 ; |
| using msvc : : "Z:/Programs/Microsoft Visual Studio/vc98/bin/cl" ; |
| </pre> |
| <p> |
| Some Boost.Build toolsets will use that path to take additional actions |
| required before invoking the compiler, such as calling vendor-supplied |
| scripts to set up its required environment variables. When compiler |
| executables for C and C++ are different, path to the C++ compiler |
| executable must be specified. The command can |
| be any command allowed by the operating system. For example: |
| </p> |
| <pre class="programlisting"> |
| using msvc : : echo Compiling && foo/bar/baz/cl ; |
| </pre> |
| <p> |
| will work. |
| </p> |
| <p> |
| To configure several versions of a toolset, simply invoke the |
| <code class="computeroutput">using</code> rule multiple times: |
| </p> |
| <pre class="programlisting"> |
| using gcc : 3.3 ; |
| using gcc : 3.4 : g++-3.4 ; |
| using gcc : 3.2 : g++-3.2 ; |
| </pre> |
| <p> |
| Note that in the first call to <code class="computeroutput">using</code>, the |
| compiler found in the <code class="envar">PATH</code> will be used, and there is no |
| need to explicitly specify the command. |
| </p> |
| <p> |
| Many of toolsets have an <em class="parameter"><code>options</code></em> |
| parameter to fine-tune the configuration. All of |
| Boost.Build's standard compiler toolsets accept four options |
| <code class="varname">cflags</code>, <code class="varname">cxxflags</code>, |
| <code class="varname">compileflags</code> and <code class="varname">linkflags</code> as <em class="parameter"><code>options</code></em> specifying flags that will be |
| always passed to the corresponding tools. Values of the |
| <code class="varname">cflags</code> feature are passed directly to the C |
| compiler, values of the <code class="varname">cxxflags</code> feature are |
| passed directly to the C++ compiler, and values of the |
| <code class="varname">compileflags</code> feature are passed to both. For |
| example, to configure a <span class="command"><strong>gcc</strong></span> toolset so that it |
| always generates 64-bit code you could write: |
| </p> |
| <pre class="programlisting"> |
| using gcc : 3.4 : : <compileflags>-m64 <linkflags>-m64 ; |
| </pre> |
| <p> |
| </p> |
| <div class="warning"><table border="0" summary="Warning"> |
| <tr> |
| <td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../doc/src/images/warning.png"></td> |
| <th align="left">Warning</th> |
| </tr> |
| <tr><td align="left" valign="top"><p> |
| Although the syntax used to specify toolset options is very similar |
| to syntax used to specify requirements in Jamfiles, the toolset options |
| are not the same as features. Don't try to specify a feature value |
| in toolset initialization. |
| </p></td></tr> |
| </table></div> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h3 class="title"> |
| <a name="bbv2.overview.invocation"></a>Invocation</h3></div></div></div> |
| <div class="toc"><dl> |
| <dt><span class="section"><a href="overview.html#bbv2.overview.invocation.examples">Examples</a></span></dt> |
| <dt><span class="section"><a href="overview.html#bbv2.overview.invocation.options">Options</a></span></dt> |
| <dt><span class="section"><a href="overview.html#bbv2.overview.invocation.properties">Properties</a></span></dt> |
| <dt><span class="section"><a href="overview.html#bbv2.overview.invocation.targets">Targets</a></span></dt> |
| </dl></div> |
| <p>To invoke Boost.Build, type <span class="command"><strong>bjam</strong></span> on the command line. Three kinds |
| of command-line tokens are accepted, in any order:</p> |
| <div class="variablelist"><dl> |
| <dt><span class="term">options</span></dt> |
| <dd><p>Options start with either dash, or two dashes. The standard options |
| are listed below, and each project may add additional options</p></dd> |
| <dt><span class="term">properties</span></dt> |
| <dd><p>Properties specify details of what you want to build (e.g. debug |
| or release variant). Syntactically, all command line tokens with equal sign in them |
| are considered to specify properties. In the simplest form, property looks like |
| <span class="command"><strong><em class="replaceable"><code>feature</code></em>=<em class="replaceable"><code>value</code></em></strong></span> |
| </p></dd> |
| <dt><span class="term">target</span></dt> |
| <dd><p>All tokens that are neither options nor properties specify |
| what targets to build. The available targets entirely depend on the project |
| you are building.</p></dd> |
| </dl></div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="bbv2.overview.invocation.examples"></a>Examples</h4></div></div></div> |
| <p>To build all targets defined in Jamfile in the current directory with default properties, run: |
| </p> |
| <pre class="screen"> |
| bjam |
| </pre> |
| <p> |
| </p> |
| <p>To build specific targets, specify them on the command line: |
| </p> |
| <pre class="screen"> |
| bjam lib1 subproject//lib2 |
| </pre> |
| <p> |
| </p> |
| <p>To request a certain value for some property, add <code class="literal"> |
| <em class="replaceable"><code>property</code></em>=<em class="replaceable"><code>value</code></em></code> to the command line: |
| </p> |
| <pre class="screen"> |
| bjam toolset=gcc variant=debug optimization=space |
| </pre> |
| <p> |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="bbv2.overview.invocation.options"></a>Options</h4></div></div></div> |
| <p>Boost.Build recognizes the following command line options.</p> |
| <div class="variablelist"><dl> |
| <dt> |
| <a name="bbv2.reference.init.options.help"></a><span class="term"><code class="option">--help</code></span> |
| </dt> |
| <dd><p>Invokes the online help system. This prints general |
| information on how to use the help system with additional |
| --help* options. |
| </p></dd> |
| <dt><span class="term"><code class="option">--clean</code></span></dt> |
| <dd><p>Cleans all targets in the current directory and |
| in any subprojects. Note that unlike the <code class="literal">clean</code> |
| target in make, you can use <code class="literal">--clean</code> |
| together with target names to clean specific targets.</p></dd> |
| <dt><span class="term"><code class="option">--clean-all</code></span></dt> |
| <dd><p>Cleans all targets, |
| no matter where they are defined. In particular, it will clean targets |
| in parent Jamfiles, and targets defined under other project roots. |
| </p></dd> |
| <dt><span class="term"><code class="option">--build-dir</code></span></dt> |
| <dd> |
| <p>Changes build directories for all project roots being built. When |
| this option is specified, all Jamroot files should declare project name. |
| The build directory for the project root will be computed by concatanating |
| the value of the <code class="option">--build-dir</code> option, the project name |
| specified in Jamroot, and the build dir specified in Jamroot |
| (or <code class="literal">bin</code>, if none is specified). |
| </p> |
| <p>The option is primarily useful when building from read-only |
| media, when you can't modify Jamroot. |
| </p> |
| </dd> |
| <dt><span class="term"><code class="option">--version</code></span></dt> |
| <dd><p>Prints information on Boost.Build and Boost.Jam |
| versions. |
| </p></dd> |
| <dt><span class="term"><code class="option">-a</code></span></dt> |
| <dd><p>Causes all files to be rebuilt.</p></dd> |
| <dt><span class="term"><code class="option">-n</code></span></dt> |
| <dd><p>Do no execute the commands, only print them.</p></dd> |
| <dt><span class="term"><code class="option">-d+2</code></span></dt> |
| <dd><p>Show commands as they are executed.</p></dd> |
| <dt><span class="term"><code class="option">-d0</code></span></dt> |
| <dd><p>Supress all informational messages.</p></dd> |
| <dt><span class="term"><code class="option">-q</code></span></dt> |
| <dd><p>Stop at first error, as opposed to continuing to build targets |
| that don't depend on the failed ones.</p></dd> |
| <dt><span class="term"><code class="option">-j <em class="replaceable"><code>N</code></em></code></span></dt> |
| <dd><p>Run up to <em class="replaceable"><code>N</code></em> commands in parallel.</p></dd> |
| <dt><span class="term"><code class="option">--debug-configuration</code></span></dt> |
| <dd><p>Produces debug information about loading of Boost.Build |
| and toolset files.</p></dd> |
| <dt><span class="term"><code class="option">--debug-building</code></span></dt> |
| <dd><p>Prints what targets are being built and with what properties. |
| </p></dd> |
| <dt><span class="term"><code class="option">--debug-generators</code></span></dt> |
| <dd><p>Produces debug output from generator search process. |
| Useful for debugging custom generators. |
| </p></dd> |
| <dt><span class="term"><code class="option">--ignore-config</code></span></dt> |
| <dd><p>Do not load <code class="literal">site-config.jam</code> and |
| <code class="literal">user-config.jam</code> configuration files. |
| </p></dd> |
| </dl></div> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="bbv2.overview.invocation.properties"></a>Properties</h4></div></div></div> |
| <p>In the simplest case, the build is performed with a single set of properties, |
| that you specify on the command line with elements in the form |
| <span class="command"><strong><em class="replaceable"><code>feature</code></em>=<em class="replaceable"><code>value</code></em></strong></span>. |
| The complete list of features can be found in <a class="xref" href="reference.html#bbv2.overview.builtins.features" title="Builtin features">the section called “Builtin features”</a>. |
| The most common features are summarized below.</p> |
| <div class="table"> |
| <a name="id3268364"></a><p class="title"><b>Table 33.2. </b></p> |
| <div class="table-contents"><table class="table"> |
| <colgroup> |
| <col> |
| <col> |
| <col> |
| </colgroup> |
| <thead><tr> |
| <th>Feature</th> |
| <th>Allowed values</th> |
| <th>Notes</th> |
| </tr></thead> |
| <tbody> |
| <tr> |
| <td>variant</td> |
| <td>debug,release</td> |
| <td> </td> |
| </tr> |
| <tr> |
| <td>link</td> |
| <td>shared,static</td> |
| <td>Determines if Boost.Build creates shared or static libraries</td> |
| </tr> |
| <tr> |
| <td>threading</td> |
| <td>single,multi</td> |
| <td>Cause the produced binaries to be thread-safe. This requires proper support in the source code itself.</td> |
| </tr> |
| <tr> |
| <td>address-model</td> |
| <td>32,64</td> |
| <td>Explicitly request either 32-bit or 64-bit code generation. This typically |
| requires that your compiler is appropriately configured. Please refer to |
| <a class="xref" href="reference.html#bbv2.reference.tools.compilers" title="C++ Compilers">the section called “C++ Compilers”</a> and your compiler documentation |
| in case of problems.</td> |
| </tr> |
| <tr> |
| <td>toolset</td> |
| <td>(Depends on configuration)</td> |
| <td>The C++ compiler to use. See <a class="xref" href="reference.html#bbv2.reference.tools.compilers" title="C++ Compilers">the section called “C++ Compilers”</a> for a detailed list.</td> |
| </tr> |
| <tr> |
| <td>include</td> |
| <td>(Arbitrary string)</td> |
| <td>Additional include paths for C and C++ compilers.</td> |
| </tr> |
| <tr> |
| <td>define</td> |
| <td>(Arbitrary string)</td> |
| <td>Additional macro definitions for C and C++ compilers. The string should be either |
| <code class="computeroutput">SYMBOL</code> or <code class="computeroutput">SYMBOL=VALUE</code> |
| </td> |
| </tr> |
| <tr> |
| <td>cxxflags</td> |
| <td>(Arbitrary string)</td> |
| <td>Custom options to pass to the C++ compiler.</td> |
| </tr> |
| <tr> |
| <td>cflags</td> |
| <td>(Arbitrary string)</td> |
| <td>Custom options to pass to the C compiler.</td> |
| </tr> |
| <tr> |
| <td>linkflags</td> |
| <td>(Arbitrary string)</td> |
| <td>Custom options to pass to the C++ linker.</td> |
| </tr> |
| <tr> |
| <td>runtime-link</td> |
| <td>shared,static</td> |
| <td>Determines if shared or static version of C and C++ runtimes should be used.</td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <br class="table-break"> |
| |
| If you have more than one version of a given C++ toolset (e.g. configured in |
| <code class="filename">user-config.jam</code>, or autodetected, as happens with msvc), you can |
| request the specific version by passing |
| <code class="computeroutput"><em class="replaceable"><code>toolset</code></em>-<em class="replaceable"><code>version</code></em></code> as |
| the value of the <code class="computeroutput">toolset</code> feature, for example <code class="computeroutput">toolset=msvc-8.0</code>. |
| |
| |
| <p> |
| If a feature has a fixed set of values it can be specified more than |
| once on the command line. |
| In which case, everything will be built several times -- |
| once for each specified value of a feature. For example, if you use |
| </p> |
| <pre class="screen"> |
| bjam link=static link=shared threading=single threading=multi |
| </pre> |
| <p> |
| Then a total of 4 builds will be performed. For convenience, |
| instead of specifying all requested values of a feature in separate command line elements, |
| you can separate the values with commands, for example: |
| </p> |
| <pre class="screen"> |
| bjam link=static,shared threading=single,multi |
| </pre> |
| <p> |
| The comma has special meaning only if the feature has a fixed set of values, so |
| </p> |
| <pre class="screen"> |
| bjam include=static,shared |
| </pre> |
| <p>is not treated specially.</p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="bbv2.overview.invocation.targets"></a>Targets</h4></div></div></div> |
| <p>All command line elements that are neither options nor properties are the names of the |
| targets to build. See <a class="xref" href="reference.html#bbv2.reference.ids" title="Target identifiers and references">the section called “Target identifiers and references”</a>. If no target is specified, |
| the project in the current directory is built.</p> |
| </div> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h3 class="title"> |
| <a name="bbv2.overview.targets"></a>Declaring Targets</h3></div></div></div> |
| <div class="toc"><dl> |
| <dt><span class="section"><a href="overview.html#id3268775">Name</a></span></dt> |
| <dt><span class="section"><a href="overview.html#id3268930">Sources</a></span></dt> |
| <dt><span class="section"><a href="overview.html#bbv2.overview.targets.requirements">Requirements</a></span></dt> |
| <dt><span class="section"><a href="overview.html#id3269245">Default Build</a></span></dt> |
| <dt><span class="section"><a href="overview.html#id3269272">Additional Information</a></span></dt> |
| </dl></div> |
| <p><a name="bbv2.overview.targets.main"></a> |
| A <em class="firstterm">Main target</em> is a user-defined named |
| entity that can be built, for example an executable file. |
| Declaring a main target is usually done using one of the main |
| target rules described in <a class="xref" href="reference.html#bbv2.reference.rules" title="Builtin rules">the section called “Builtin rules”</a>. The user can also declare |
| custom main target rules as shown in <a class="xref" href="extender.html#bbv2.extending.rules" title="Main target rules">the section called “Main target rules”</a>. |
| </p> |
| <a class="indexterm" name="id3268722"></a><p>Most main target rules in Boost.Build have the same common |
| signature:</p> |
| <a class="indexterm" name="id3268736"></a><a name="bbv2.main-target-rule-syntax"></a><pre class="programlisting"> |
| rule <em class="replaceable"><code>rule-name</code></em> ( |
| main-target-name : |
| sources + : |
| requirements * : |
| default-build * : |
| usage-requirements * ) |
| </pre> |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"> |
| <li class="listitem"> |
| <em class="parameter"><code>main-target-name</code></em> is the name used |
| to request the target on command line and to use it from |
| other main targets. A main target name may contain |
| alphanumeric characters, dashes |
| (‘<code class="computeroutput">-</code>’), and underscores |
| (‘<code class="computeroutput">_</code>’). |
| </li> |
| <li class="listitem"> |
| <em class="parameter"><code>sources</code></em> is the list of source files and other main |
| targets that must be combined. |
| </li> |
| <li class="listitem"> |
| <em class="parameter"><code>requirements</code></em> is the list of properties that must always |
| be present when this main target is built. |
| </li> |
| <li class="listitem"> |
| <em class="parameter"><code>default-build</code></em> is the list of properties that will be used |
| unless some other value of the same feature is already |
| specified, e.g. on the command line or by propagation from a dependent target. |
| </li> |
| <li class="listitem"> |
| <em class="parameter"><code>usage-requirements</code></em> is the list of properties that will be |
| propagated to all main targets that use this one, i.e. to all its |
| dependents. |
| </li> |
| </ul></div> |
| <p> |
| Some main target rules have a different list of parameters as explicitly |
| stated in their documentation. |
| </p> |
| <p>The actual requirements for a target are obtained by refining |
| requirements of the project where a target is declared with the |
| explicitly specified requirements. The same is true for |
| usage-requirements. More details can be found in |
| <a class="xref" href="reference.html#bbv2.reference.variants.proprefine" title="Property refinement">the section called “Property refinement”</a> |
| </p> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="id3268775"></a>Name</h4></div></div></div> |
| <p>The name of main target has two purposes. First, it's used to refer to this target from |
| other targets and from command line. Second, it's used to compute the names of the generated files. |
| Typically, filenames are obtained from main target name by appending system-dependent suffixes and |
| prefixes. |
| </p> |
| <p>The name of a main target can contain alphanumeric characters, |
| dashes, undescores and dots. The entire |
| name is significant when resolving references from other targets. For determining filenames, only the |
| part before the first dot is taken. For example:</p> |
| <pre class="programlisting"> |
| obj test.release : test.cpp : <variant>release ; |
| obj test.debug : test.cpp : <variant>debug ; |
| </pre> |
| <p>will generate two files named <code class="filename">test.obj</code> (in two different directories), not |
| two files named <code class="filename">test.release.obj</code> and <code class="filename">test.debug.obj</code>. |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="id3268930"></a>Sources</h4></div></div></div> |
| <p>The list of sources specifies what should be processed to |
| get the resulting targets. Most of the time, it's just a list of |
| files. Sometimes, you'll want to automatically construct the |
| list of source files rather than having to spell it out |
| manually, in which case you can use the |
| <code class="computeroutput">glob</code> rule. Here are two examples:</p> |
| <pre class="programlisting"> |
| exe a : a.cpp ; # a.cpp is the only source file |
| exe b : [ glob *.cpp ] ; # all .cpp files in this directory are sources |
| </pre> |
| <p> |
| Unless you specify a file with an absolute path, the name is |
| considered relative to the source directory — which is typically |
| the directory where the Jamfile is located, but can be changed as |
| described in <a class="xref" href="overview.html#bbv2.overview.projects.attributes.projectrule">the section called “Projects”</a>. |
| </p> |
| <p> |
| |
| The list of sources can also refer to other main targets. Targets in |
| the same project can be referred to by name, while targets in other |
| projects must be qualified with a directory or a symbolic project |
| name. The directory/project name is separated from the target name by |
| a double forward slash. There is no special syntax to distinguish the |
| directory name from the project name—the part before the double |
| slash is first looked up as project name, and then as directory name. |
| For example: |
| </p> |
| <pre class="programlisting"> |
| lib helper : helper.cpp ; |
| exe a : a.cpp helper ; |
| # Since all project ids start with slash, ".." is a directory name. |
| exe b : b.cpp ..//utils ; |
| exe c : c.cpp /boost/program_options//program_options ; |
| </pre> |
| <p> |
| The first exe uses the library defined in the same project. The second |
| one uses some target (most likely a library) defined by a Jamfile one |
| level higher. Finally, the third target uses a <a href="http://boost.org" target="_top">C++ Boost</a> library, referring to it using |
| its absolute symbolic name. More information about target references |
| can be found in <a class="xref" href="tutorial.html#bbv2.tutorial.libs" title="Dependent Targets">the section called “Dependent Targets”</a> and <a class="xref" href="reference.html#bbv2.reference.ids" title="Target identifiers and references">the section called “Target identifiers and references”</a>. |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="bbv2.overview.targets.requirements"></a>Requirements</h4></div></div></div> |
| <a class="indexterm" name="id3269028"></a><p>Requirements are the properties that should always be present when |
| building a target. Typically, they are includes and defines: |
| </p> |
| <pre class="programlisting"> |
| exe hello : hello.cpp : <include>/opt/boost <define>MY_DEBUG ; |
| </pre> |
| <p> |
| There is a number of other features, listed in |
| <a class="xref" href="reference.html#bbv2.overview.builtins.features" title="Builtin features">the section called “Builtin features”</a>. For example if |
| a library can only be built statically, or a file can't be compiled |
| with optimization due to a compiler bug, one can use |
| </p> |
| <pre class="programlisting"> |
| lib util : util.cpp : <link>static ; |
| obj main : main.cpp : <optimization>off ; |
| </pre> |
| <p> |
| </p> |
| <p><a name="bbv2.overview.targets.requirements.conditional"></a>Sometimes, particular relationships need to be maintained |
| among a target's build properties. This can be achieved with |
| <em class="firstterm">conditional |
| requirements</em>. For example, you might want to set |
| specific <code class="computeroutput">#defines</code> when a library is built as shared, |
| or when a target's <code class="computeroutput">release</code> variant is built in |
| release mode. |
| </p> |
| <pre class="programlisting"> |
| lib network : network.cpp |
| : <span class="bold"><strong><link>shared:<define>NEWORK_LIB_SHARED</strong></span> |
| <variant>release:<define>EXTRA_FAST |
| ; |
| </pre> |
| <p> |
| |
| In the example above, whenever <code class="filename">network</code> is |
| built with <code class="computeroutput"><link>shared</code>, |
| <code class="computeroutput"><define>NEWORK_LIB_SHARED</code> will be in its |
| properties, too. |
| </p> |
| <p>You can use several properties in the condition, for example: |
| </p> |
| <pre class="programlisting"> |
| lib network : network.cpp |
| : <toolset>gcc,<optimization>speed:<define>USE_INLINE_ASSEMBLER |
| ; |
| </pre> |
| <p> |
| </p> |
| <p><a name="bbv2.overview.targets.requirements.indirect"></a> |
| A more powerful variant of conditional requirements |
| is <em class="firstterm">indirect conditional requirements</em>. |
| You can provide a rule that will be called with the current build properties and can compute additional properties |
| to be added. For example: |
| </p> |
| <pre class="programlisting"> |
| lib network : network.cpp |
| : <conditional>@my-rule |
| ; |
| rule my-rule ( properties * ) |
| { |
| local result ; |
| if <toolset>gcc <optimization>speed in $(properties) |
| { |
| result += <define>USE_INLINE_ASSEMBLER ; |
| } |
| return $(result) ; |
| } |
| </pre> |
| <p> |
| This example is equivalent to the previous one, but for complex cases, indirect conditional |
| requirements can be easier to write and understand. |
| </p> |
| <p>Requirements explicitly specified for a target are usually |
| combined with the requirements specified for the containing project. You |
| can cause a target to completely ignore specific project's requirement |
| using the syntax by adding a minus sign before a property, for example: |
| </p> |
| <pre class="programlisting"> |
| exe main : main.cpp : <span class="bold"><strong>-<define>UNNECESSARY_DEFINE</strong></span> ; |
| </pre> |
| <p> |
| This syntax is the only way to ignore free properties from a parent, |
| such as defines. It can be also useful for ordinary properties. Consider |
| this example: |
| </p> |
| <pre class="programlisting"> |
| project test : requirements <threading>multi ; |
| exe test1 : test1.cpp ; |
| exe test2 : test2.cpp : <threading>single ; |
| exe test3 : test3.cpp : -<threading>multi ; |
| </pre> |
| <p> |
| Here, <code class="computeroutput">test1</code> inherits project requirements and will always |
| be built in multi-threaded mode. The <code class="computeroutput">test2</code> target |
| <span class="emphasis"><em>overrides</em></span> project's requirements and will |
| always be built in single-threaded mode. In contrast, the |
| <code class="computeroutput">test3</code> target <span class="emphasis"><em>removes</em></span> a property |
| from project requirements and will be built either in single-threaded or |
| multi-threaded mode depending on which variant is requested by the |
| user.</p> |
| <p>Note that the removal of requirements is completely textual: |
| you need to specify exactly the same property to remove it.</p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="id3269245"></a>Default Build</h4></div></div></div> |
| <p>The <code class="varname">default-build</code> parameter |
| is a set of properties to be used if the build request does |
| not otherwise specify a value for features in the set. For example: |
| </p> |
| <pre class="programlisting"> |
| exe hello : hello.cpp : : <threading>multi ; |
| </pre> |
| <p> |
| would build a multi-threaded target unless the user |
| explicitly requests a single-threaded version. The difference between |
| requirements and default-build is that requirements cannot be |
| overridden in any way. |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="id3269272"></a>Additional Information</h4></div></div></div> |
| <p> |
| The ways a target is built can be so different that |
| describing them using conditional requirements would be |
| hard. For example, imagine that a library actually uses |
| different source files depending on the toolset used to build |
| it. We can express this situation using <em class="firstterm">target |
| alternatives</em>: |
| </p> |
| <pre class="programlisting"> |
| lib demangler : dummy_demangler.cpp ; # alternative 1 |
| lib demangler : demangler_gcc.cpp : <toolset>gcc ; # alternative 2 |
| lib demangler : demangler_msvc.cpp : <toolset>msvc ; # alternative 3 |
| </pre> |
| <p> |
| In the example above, when built with <code class="literal">gcc</code> |
| or <code class="literal">msvc</code>, <code class="filename">demangler</code> |
| will use a source file specific to the toolset. Otherwise, it |
| will use a generic source file, |
| <code class="filename">dummy_demangler.cpp</code>. |
| </p> |
| <p>It is possible to declare a target inline, i.e. the "sources" |
| parameter may include calls to other main rules. For example:</p> |
| <pre class="programlisting"> |
| exe hello : hello.cpp |
| [ obj helpers : helpers.cpp : <optimization>off ] ;</pre> |
| <p> |
| Will cause "helpers.cpp" to be always compiled without |
| optimization. When referring to an inline main target, its declared |
| name must be prefixed by its parent target's name and two dots. In |
| the example above, to build only helpers, one should run |
| <code class="computeroutput">bjam hello..helpers</code>. |
| </p> |
| <p>When no target is requested on the command line, all targets in the |
| current project will be built. If a target should be built only by |
| explicit request, this can be expressed by the |
| <code class="computeroutput">explicit</code> rule: |
| </p> |
| <pre class="programlisting"> |
| explicit install_programs ;</pre> |
| <p> |
| </p> |
| </div> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h3 class="title"> |
| <a name="bbv2.overview.projects"></a>Projects</h3></div></div></div> |
| <p>As mentioned before, targets are grouped into projects, |
| and each Jamfile is a separate project. Projects are useful |
| because they allow us to group related targets together, define |
| properties common to all those targets, and assign a symbolic |
| name to the project that can be used in referring to its |
| targets. |
| </p> |
| <p>Projects are named using the |
| <code class="computeroutput">project</code> rule, which has the |
| following syntax: |
| </p> |
| <pre class="programlisting"> |
| project <em class="replaceable"><code>id</code></em> : <em class="replaceable"><code>attributes</code></em> ; |
| </pre> |
| <p> |
| Here, <em class="replaceable"><code>attributes</code></em> is a sequence of |
| rule arguments, each of which begins with an attribute-name |
| and is followed by any number of build properties. The list |
| of attribute names along with its handling is also shown in |
| the table below. For example, it is possible to write: |
| </p> |
| <pre class="programlisting"> |
| project tennis |
| : requirements <threading>multi |
| : default-build release |
| ; |
| </pre> |
| <p> |
| </p> |
| <p>The possible attributes are listed below.</p> |
| <p><span class="emphasis"><em>Project id</em></span> is a short way to denote a project, as |
| opposed to the Jamfile's pathname. It is a hierarchical path, |
| unrelated to filesystem, such as "boost/thread". <a class="link" href="reference.html#bbv2.reference.ids" title="Target identifiers and references">Target references</a> make use of project ids to |
| specify a target.</p> |
| <p><span class="emphasis"><em>Source location</em></span> specifies the directory where sources |
| for the project are located.</p> |
| <p><span class="emphasis"><em>Project requirements</em></span> are requirements that apply to |
| all the targets in the projects as well as all subprojects.</p> |
| <p><span class="emphasis"><em>Default build</em></span> is the build request that should be |
| used when no build request is specified explicitly.</p> |
| <p><a name="bbv2.overview.projects.attributes.projectrule"></a> |
| The default values for those attributes are |
| given in the table below. |
| |
| </p> |
| <div class="table"> |
| <a name="id3269486"></a><p class="title"><b>Table 33.3. </b></p> |
| <div class="table-contents"><table class="table" summary=""> |
| <colgroup> |
| <col> |
| <col> |
| <col> |
| <col> |
| </colgroup> |
| <thead><tr> |
| <th>Attribute</th> |
| <th>Name</th> |
| <th>Default value</th> |
| <th>Handling by the <code class="computeroutput">project</code> |
| rule</th> |
| </tr></thead> |
| <tbody> |
| <tr> |
| <td>Project id</td> |
| <td>none</td> |
| <td>none</td> |
| <td>Assigned from the first parameter of the 'project' rule. |
| It is assumed to denote absolute project id.</td> |
| </tr> |
| <tr> |
| <td>Source location</td> |
| <td><code class="literal">source-location</code></td> |
| <td>The location of jamfile for the project</td> |
| <td>Sets to the passed value</td> |
| </tr> |
| <tr> |
| <td>Requirements</td> |
| <td><code class="literal">requirements</code></td> |
| <td>The parent's requirements</td> |
| <td>The parent's requirements are refined with the passed |
| requirement and the result is used as the project |
| requirements.</td> |
| </tr> |
| <tr> |
| <td>Default build</td> |
| <td><code class="literal">default-build</code></td> |
| <td>none</td> |
| <td>Sets to the passed value</td> |
| </tr> |
| <tr> |
| <td>Build directory</td> |
| <td><code class="literal">build-dir</code></td> |
| <td>Empty if the parent has no build directory set. |
| Otherwise, the parent's build directory with the |
| relative path from parent to the current project |
| appended to it. |
| </td> |
| <td>Sets to the passed value, interpreted as relative to the |
| project's location.</td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <p><br class="table-break"> |
| </p> |
| <p>Besides defining projects and main targets, Jamfiles |
| often invoke various utility rules. For the full list of rules |
| that can be directly used in Jamfile see |
| <a class="xref" href="reference.html#bbv2.reference.rules" title="Builtin rules">the section called “Builtin rules”</a>. |
| </p> |
| <p>Each subproject inherits attributes, constants and rules |
| from its parent project, which is defined by the nearest |
| Jamfile in an ancestor directory above |
| the subproject. The top-level project is declared in a file |
| called <code class="filename">Jamroot</code> rather than |
| <code class="filename">Jamfile</code>. When loading a project, |
| Boost.Build looks for either <code class="filename">Jamroot</code> or |
| <code class="computeroutput">Jamfile</code>. They are handled identically, except |
| that if the file is called <code class="filename">Jamroot</code>, the |
| search for a parent project is not performed. |
| </p> |
| <p>Even when building in a subproject directory, parent |
| project files are always loaded before those of their |
| subprojects, so that every definition made in a parent project |
| is always available to its children. The loading order of any |
| other projects is unspecified. Even if one project refers to |
| another via the <code class="computeroutput">use-project</code> or a target reference, |
| no specific order should be assumed. |
| </p> |
| <div class="note"><table border="0" summary="Note"> |
| <tr> |
| <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td> |
| <th align="left">Note</th> |
| </tr> |
| <tr><td align="left" valign="top"><p>Giving the root project the special name |
| “<code class="filename">Jamroot</code>” ensures that |
| Boost.Build won't misinterpret a directory above it as the |
| project root just because the directory contains a Jamfile. |
| |
| </p></td></tr> |
| </table></div> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h3 class="title"> |
| <a name="bbv2.overview.build_process"></a>The Build Process</h3></div></div></div> |
| <div class="toc"><dl> |
| <dt><span class="section"><a href="overview.html#bbv2.overview.build_request">Build Request</a></span></dt> |
| <dt><span class="section"><a href="overview.html#id3269803">Building a main target</a></span></dt> |
| <dt><span class="section"><a href="overview.html#id3269919">Building a Project</a></span></dt> |
| </dl></div> |
| <p>When you've described your targets, you want Boost.Build to run the |
| right tools and create the needed targets. |
| |
| This section will describe |
| two things: how you specify what to build, and how the main targets are |
| actually constructed. |
| </p> |
| <p>The most important thing to note is that in Boost.Build, unlike |
| other build tools, the targets you declare do not correspond to specific |
| files. What you declare in a Jamfile is more like a “metatarget.” |
| |
| Depending on the properties you specify on the command line, |
| each metatarget will produce a set of real targets corresponding |
| to the requested properties. It is quite possible that the same |
| metatarget is built several times with different properties, |
| producing different files. |
| </p> |
| <div class="tip"><table border="0" summary="Tip"> |
| <tr> |
| <td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../doc/src/images/tip.png"></td> |
| <th align="left">Tip</th> |
| </tr> |
| <tr><td align="left" valign="top"><p> |
| This means that for Boost.Build, you cannot directly obtain a build |
| variant from a Jamfile. There could be several variants requested by the |
| user, and each target can be built with different properties. |
| </p></td></tr> |
| </table></div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="bbv2.overview.build_request"></a>Build Request</h4></div></div></div> |
| <p> |
| The command line specifies which targets to build and with which |
| properties. For example: |
| </p> |
| <pre class="programlisting"> |
| bjam app1 lib1//lib1 toolset=gcc variant=debug optimization=full |
| </pre> |
| <p> |
| would build two targets, "app1" and "lib1//lib1" with the specified |
| properties. You can refer to any targets, using |
| <a class="link" href="reference.html#bbv2.reference.ids" title="Target identifiers and references">target id</a> and specify arbitrary |
| properties. Some of the properties are very common, and for them the name |
| of the property can be omitted. For example, the above can be written as: |
| </p> |
| <pre class="programlisting"> |
| bjam app1 lib1//lib1 gcc debug optimization=full |
| </pre> |
| <p> |
| The complete syntax, which has some additional shortcuts, is |
| described in <a class="xref" href="overview.html#bbv2.overview.invocation" title="Invocation">the section called “Invocation”</a>. |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="id3269803"></a>Building a main target</h4></div></div></div> |
| <p>When you request, directly or indirectly, a build of a main target |
| with specific requirements, the following steps are done. Some brief |
| explanation is provided, and more details are given in <a class="xref" href="reference.html#bbv2.reference.buildprocess" title="Build process">the section called “Build process”</a>. |
| </p> |
| <div class="orderedlist"><ol class="orderedlist" type="1"> |
| <li class="listitem"><p>Applying default build. If the default-build |
| property of a target specifies a value of a feature that is not |
| present in the build request, that value is added.</p></li> |
| <li class="listitem"><p>Selecting the main target alternative to use. For |
| each alternative we look how many properties are present both in |
| alternative's requirements, and in build request. The |
| alternative with large number of matching properties is selected. |
| </p></li> |
| <li class="listitem"><p>Determining "common" properties. |
| |
| The build request |
| is <a class="link" href="reference.html#bbv2.reference.variants.proprefine" title="Property refinement">refined</a> |
| with target's requirements. |
| |
| The conditional properties in |
| requirements are handled as well. Finally, default values of |
| features are added. |
| </p></li> |
| <li class="listitem"><p>Building targets referred by the sources list and |
| dependency properties. The list of sources and the properties |
| can refer to other target using <a class="link" href="reference.html#bbv2.reference.ids" title="Target identifiers and references">target references</a>. For each |
| reference, we take all <a class="link" href="reference.html#bbv2.reference.features.attributes.propagated">propagated</a> |
| properties, refine them by explicit properties specified in the |
| target reference, and pass the resulting properties as build |
| request to the other target. |
| </p></li> |
| <li class="listitem"><p>Adding the usage requirements produced when building |
| dependencies to the "common" properties. When dependencies are |
| built in the previous step, they return |
| |
| both the set of created |
| "real" targets, and usage requirements. The usage requirements |
| are added to the common properties and the resulting property |
| set will be used for building the current target. |
| </p></li> |
| <li class="listitem"><p>Building the target using generators. To convert the |
| sources to the desired type, Boost.Build uses "generators" --- |
| objects that correspond to tools like compilers and linkers. Each |
| generator declares what type of targets it can produce and what |
| type of sources it requires. Using this information, Boost.Build |
| determines which generators must be run to produce a specific |
| target from specific sources. When generators are run, they return |
| the "real" targets. |
| </p></li> |
| <li class="listitem"><p>Computing the usage requirements to be returned. The |
| conditional properties in usage requirements are expanded |
| |
| and the result is returned.</p></li> |
| </ol></div> |
| <p> |
| </p> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h4 class="title"> |
| <a name="id3269919"></a>Building a Project</h4></div></div></div> |
| <p>Often, a user builds a complete project, not just one main |
| target. In fact, invoking <span class="command"><strong>bjam</strong></span> without |
| arguments |
| |
| builds the project defined in the current |
| directory.</p> |
| <p>When a project is built, the build request is passed without |
| modification to all main targets in that project. |
| |
| It's is possible to |
| prevent implicit building of a target in a project with the |
| <code class="computeroutput">explicit</code> rule: |
| </p> |
| <pre class="programlisting"> |
| explicit hello_test ; |
| </pre> |
| <p> |
| would cause the <code class="computeroutput">hello_test</code> target to be built only if |
| explicitly requested by the user or by some other target. |
| </p> |
| <p>The Jamfile for a project can include a number of |
| <code class="computeroutput">build-project</code> rule calls that specify additional projects to |
| be built. |
| </p> |
| </div> |
| </div> |
| </div> |
| <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> |
| <td align="left"></td> |
| <td align="right"><div class="copyright-footer">Copyright © 2006-2009 Vladimir Prus<p>Distributed under the Boost Software License, Version 1.0. |
| (See accompanying file <code class="filename">LICENSE_1_0.txt</code> or copy at |
| <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) |
| </p> |
| </div></td> |
| </tr></table> |
| <hr> |
| <div class="spirit-nav"> |
| <a accesskey="p" href="tutorial.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../bbv2.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="tasks.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> |
| </div> |
| </body> |
| </html> |