| <html> | |
| <head> | |
| <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> | |
| <title>Reference</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="tasks.html" title="Common tasks"> | |
| <link rel="next" href="extender.html" title="Extender Manual"> | |
| </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="tasks.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="extender.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.reference"></a>Reference</h2></div></div></div> | |
| <div class="toc"><dl> | |
| <dt><span class="section"><a href="reference.html#bbv2.reference.general">General information</a></span></dt> | |
| <dt><span class="section"><a href="reference.html#bbv2.reference.rules">Builtin rules</a></span></dt> | |
| <dt><span class="section"><a href="reference.html#bbv2.overview.builtins.features">Builtin features</a></span></dt> | |
| <dt><span class="section"><a href="reference.html#bbv2.reference.tools">Builtin tools</a></span></dt> | |
| <dt><span class="section"><a href="reference.html#bbv2.reference.buildprocess">Build process</a></span></dt> | |
| <dt><span class="section"><a href="reference.html#bbv2.reference.definitions">Definitions</a></span></dt> | |
| </dl></div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h3 class="title"> | |
| <a name="bbv2.reference.general"></a>General information</h3></div></div></div> | |
| <div class="toc"><dl><dt><span class="section"><a href="reference.html#bbv2.reference.init">Initialization</a></span></dt></dl></div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h4 class="title"> | |
| <a name="bbv2.reference.init"></a>Initialization</h4></div></div></div> | |
| <p>bjam's first job upon startup is to load the Jam code that | |
| implements the build system. To do this, it searches for a file | |
| called <code class="filename">boost-build.jam</code>, first in the invocation directory, then | |
| in its parent and so forth up to the filesystem root, and finally | |
| in the directories specified by the environment variable | |
| BOOST_BUILD_PATH. When found, the file is interpreted, and should | |
| specify the build system location by calling the boost-build | |
| rule:</p> | |
| <pre class="programlisting"> | |
| rule boost-build ( location ? ) | |
| </pre> | |
| <p> | |
| If location is a relative path, it is treated as relative to | |
| the directory of <code class="filename">boost-build.jam</code>. The directory specified by | |
| that location and the directories in BOOST_BUILD_PATH are then searched for | |
| a file called <code class="filename">bootstrap.jam</code>, which is expected to | |
| bootstrap the build system. This arrangement allows the build | |
| system to work without any command-line or environment variable | |
| settings. For example, if the build system files were located in a | |
| directory "build-system/" at your project root, you might place a | |
| <code class="filename">boost-build.jam</code> at the project root containing: | |
| </p> | |
| <pre class="programlisting"> | |
| boost-build build-system ; | |
| </pre> | |
| <p> | |
| In this case, running bjam anywhere in the project tree will | |
| automatically find the build system.</p> | |
| <p>The default <code class="filename">bootstrap.jam</code>, after loading some standard | |
| definitions, loads two <code class="filename">site-config.jam</code> and <code class="filename">user-config.jam</code>.</p> | |
| </div> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h3 class="title"> | |
| <a name="bbv2.reference.rules"></a>Builtin rules</h3></div></div></div> | |
| <p>This section contains the list of all rules that | |
| can be used in Jamfile—both rules that define new | |
| targets and auxiliary rules.</p> | |
| <div class="variablelist"><dl> | |
| <dt><span class="term"><code class="literal">exe</code></span></dt> | |
| <dd><p>Creates an executable file. See | |
| <a class="xref" href="tasks.html#bbv2.tasks.programs" title="Programs">the section called “Programs”</a>.</p></dd> | |
| <dt><span class="term"><code class="literal">lib</code></span></dt> | |
| <dd><p>Creates an library file. See | |
| <a class="xref" href="tasks.html#bbv2.tasks.libraries" title="Libraries">the section called “Libraries”</a>.</p></dd> | |
| <dt><span class="term"><code class="literal">install</code></span></dt> | |
| <dd><p>Installs built targets and other files. See | |
| <a class="xref" href="tasks.html#bbv2.tasks.installing" title="Installing">the section called “Installing”</a>.</p></dd> | |
| <dt><span class="term"><code class="literal">alias</code></span></dt> | |
| <dd><p>Creates an alias for other targets. See | |
| <a class="xref" href="tasks.html#bbv2.tasks.alias" title="Alias">the section called “Alias”</a>.</p></dd> | |
| <dt><span class="term"><code class="literal">unit-test</code></span></dt> | |
| <dd><p>Creates an executable that will be automatically run. See | |
| <a class="xref" href="tutorial.html#bbv2.tutorial.testing" title="Testing">the section called “Testing”</a>.</p></dd> | |
| <dt> | |
| <span class="term"><code class="literal">compile</code>, </span><span class="term"><code class="literal">compile-fail</code>, </span><span class="term"><code class="literal">link</code>, </span><span class="term"><code class="literal">link-fail</code>, </span><span class="term"><code class="literal">run</code>, </span><span class="term"><code class="literal">run-fail</code></span> | |
| </dt> | |
| <dd><p>Specialized rules for testing. See | |
| <a class="xref" href="tutorial.html#bbv2.tutorial.testing" title="Testing">the section called “Testing”</a>.</p></dd> | |
| <dt><span class="term"><code class="literal">obj</code></span></dt> | |
| <dd><p>Creates an object file. Useful when a single source | |
| file must be compiled with special properties.</p></dd> | |
| <dt><span class="term"><code class="literal">glob</code></span></dt> | |
| <dd> | |
| <p>The <code class="computeroutput">glob</code> rule takes a list shell pattern | |
| and returns the list of files in the project's source directory that | |
| match the pattern. For example: | |
| </p> | |
| <pre class="programlisting"> | |
| lib tools : [ glob *.cpp ] ; | |
| </pre> | |
| <p> | |
| It is possible to also pass a second argument—the list of | |
| exclude patterns. The result will then include the list of | |
| files patching any of include patterns, and not matching any | |
| of the exclude patterns. For example: | |
| </p> | |
| <pre class="programlisting"> | |
| lib tools : [ glob *.cpp : file_to_exclude.cpp bad*.cpp ] ; | |
| </pre> | |
| <p> | |
| </p> | |
| </dd> | |
| <dt> | |
| <a name="bbv2.reference.glob-tree"></a><span class="term"><code class="literal">glob-tree</code></span> | |
| </dt> | |
| <dd> | |
| <p>The <code class="computeroutput">glob-tree</code> is similar to the | |
| <code class="computeroutput">glob</code> except that it operates recursively from | |
| the directory of the containing Jamfile. For example: | |
| </p> | |
| <pre class="programlisting"> | |
| ECHO [ glob-tree *.cpp : .svn ] ; | |
| </pre> | |
| <p> | |
| will print the names of all C++ files in your project. The | |
| <code class="literal">.svn</code> exclude pattern prevents the | |
| <code class="computeroutput">glob-tree</code> rule from entering administrative | |
| directories of the Subversion version control system. | |
| </p> | |
| </dd> | |
| <dt><span class="term"><code class="literal">project</code></span></dt> | |
| <dd><p>Declares project id and attributes, including | |
| project requirements. See <a class="xref" href="overview.html#bbv2.overview.projects" title="Projects">the section called “Projects”</a>. | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">use-project</code></span></dt> | |
| <dd><p>Assigns a symbolic project ID to a project at | |
| a given path. This rule must be better documented! | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">explicit</code></span></dt> | |
| <dd><p>The <code class="literal">explicit</code> rule takes a single | |
| parameter—a list of target names. The named targets will | |
| be marked explicit, and will be built only if they are explicitly | |
| requested on the command line, or if their dependents are built. | |
| Compare this to ordinary targets, that are built implicitly when | |
| their containing project is built.</p></dd> | |
| <dt><span class="term"><code class="literal">always</code></span></dt> | |
| <dd> | |
| <p>The <code class="literal">always</code> funciton takes a single | |
| parameter—a list of metatarget names. The top-level targets produced | |
| by the named metatargets will be always considered out of date. Consider this example: | |
| </p> | |
| <pre class="programlisting"> | |
| exe hello : hello.cpp ; | |
| exe bye : bye.cpp ; | |
| always hello ; | |
| </pre> | |
| <p>If a build of <code class="filename">hello</code> is requested, then the binary will | |
| always be relinked. The object files will not be recompiled, though. Note that if | |
| a build of <code class="filename">hello</code> is not requested, for example you specify just | |
| <code class="filename">bye</code> on the command line, <code class="filename">hello</code> will not | |
| be relinked.</p> | |
| </dd> | |
| <dt><span class="term"><code class="literal">constant</code></span></dt> | |
| <dd> | |
| <p>Sets project-wide constant. Takes two | |
| parameters: variable name and a value and makes the specified | |
| variable name accessible in this Jamfile and any child Jamfiles. | |
| For example: | |
| </p> | |
| <pre class="programlisting"> | |
| constant VERSION : 1.34.0 ; | |
| </pre> | |
| <p> | |
| </p> | |
| </dd> | |
| <dt><span class="term"><code class="literal">path-constant</code></span></dt> | |
| <dd> | |
| <p>Same as <code class="literal">constant</code> except that | |
| the value is treated as path relative to Jamfile location. For example, | |
| if <span class="command"><strong>bjam</strong></span> is invoked in the current directory, | |
| and Jamfile in <code class="filename">helper</code> subdirectory has: | |
| </p> | |
| <pre class="programlisting"> | |
| path-constant DATA : data/a.txt ; | |
| </pre> | |
| <p> | |
| then the variable <code class="varname">DATA</code> will be set to | |
| <code class="literal">helper/data/a.txt</code>, and if <span class="command"><strong>bjam</strong></span> | |
| is invoked from the <code class="filename">helper</code> directory, then | |
| the variable <code class="varname">DATA</code> will be set to | |
| <code class="literal">data/a.txt</code>. | |
| </p> | |
| </dd> | |
| <dt><span class="term"><code class="literal">build-project</code></span></dt> | |
| <dd><p>Cause some other project to be built. This rule | |
| takes a single parameter—a directory name relative to | |
| the containing Jamfile. When the containing Jamfile is built, | |
| the project located at that directory will be built as well. | |
| At the moment, the parameter to this rule should be a directory | |
| name. Project ID or general target references are not allowed. | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">test-suite</code></span></dt> | |
| <dd><p>This rule is deprecated and equivalent to | |
| <code class="computeroutput">alias</code>.</p></dd> | |
| </dl></div> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h3 class="title"> | |
| <a name="bbv2.overview.builtins.features"></a>Builtin features</h3></div></div></div> | |
| <p>This section documents the features that are built-in into | |
| Boost.Build. For features with a fixed set of values, that set is | |
| provided, with the default value listed first.</p> | |
| <a class="indexterm" name="id3272553"></a><div class="variablelist"><dl> | |
| <dt><span class="term"><code class="literal">variant</code></span></dt> | |
| <dd> | |
| <p> | |
| A feature combining several low-level features, making it easy to | |
| request common build configurations. | |
| </p> | |
| <p> | |
| <span class="bold"><strong>Allowed values:</strong></span> | |
| <code class="literal">debug</code>, <code class="literal">release</code>, | |
| <code class="literal">profile</code>. | |
| </p> | |
| <p> | |
| The value <code class="literal">debug</code> expands to | |
| </p> | |
| <pre class="programlisting"> | |
| <optimization>off <debug-symbols>on <inlining>off <runtime-debugging>on | |
| </pre> | |
| <p> | |
| The value <code class="literal">release</code> expands to | |
| </p> | |
| <pre class="programlisting"> | |
| <optimization>speed <debug-symbols>off <inlining>full <runtime-debugging>off | |
| </pre> | |
| <p> | |
| The value <code class="literal">profile</code> expands to the same as | |
| <code class="literal">release</code>, plus: | |
| </p> | |
| <pre class="programlisting"> | |
| <profiling>on <debug-symbols>on | |
| </pre> | |
| <p> | |
| Users can define their own build variants using the | |
| <code class="computeroutput">variant</code> rule from the <code class="computeroutput">common</code> module. | |
| </p> | |
| <p> | |
| <span class="bold"><strong>Note:</strong></span> Runtime debugging is on in | |
| debug builds to suit the expectations of people used to various | |
| IDEs. | |
| </p> | |
| </dd> | |
| <dt> | |
| <a name="bbv2.overview.builtins.features.link"></a><span class="term"><code class="literal">link</code></span> | |
| </dt> | |
| <dd> | |
| <p><span class="bold"><strong>Allowed values:</strong></span> <code class="literal">shared</code>, | |
| <code class="literal">static</code></p> | |
| <p class="simpara"> | |
| A feature controling how libraries are built. | |
| </p> | |
| </dd> | |
| <dt> | |
| <a name="bbv2.overview.builtins.features.runtime-link"></a><span class="term"><code class="literal">runtime-link</code></span> | |
| </dt> | |
| <dd> | |
| <p><span class="bold"><strong>Allowed values:</strong></span> <code class="literal">shared</code>, | |
| <code class="literal">static</code></p> | |
| <p class="simpara"> | |
| Controls if a static or shared C/C++ runtime should be used. There | |
| are some restrictions how this feature can be used, for example | |
| on some compilers an application using static runtime should | |
| not use shared libraries at all, and on some compilers, | |
| mixing static and shared runtime requires extreme care. Check | |
| your compiler documentation for more details. | |
| </p> | |
| </dd> | |
| <dt><span class="term"><code class="literal">threading</code></span></dt> | |
| <dd> | |
| <p><span class="bold"><strong>Allowed values:</strong></span> <code class="literal">single</code>, | |
| <code class="literal">multi</code></p> | |
| <p class="simpara"> | |
| Controls if the project should be built in multi-threaded mode. This feature does not | |
| necessary change code generation in the compiler, but it causes the compiler to link | |
| to additional or different runtime libraries, and define additional preprocessor | |
| symbols (for example, <code class="computeroutput">_MT</code> on Windows and <code class="computeroutput">_REENTRANT</code> on Linux). | |
| How those symbols affect the compiled code depends on the code itself. | |
| </p> | |
| </dd> | |
| <dt><span class="term"><code class="literal">source</code></span></dt> | |
| <dd> | |
| The <code class="computeroutput"><source>X</code> feature has the same effect on | |
| building a target as putting X in the list of sources. It is useful | |
| when you want to add the same source to all targets in the project | |
| (you can put <source> in requirements) or to conditionally | |
| include a source (using conditional requirements, see <a class="xref" href="tutorial.html#bbv2.tutorial.conditions" title="Conditions and alternatives">the section called “Conditions and alternatives”</a>). See also the <code class="computeroutput"><library> | |
| </code> feature. | |
| </dd> | |
| <dt><span class="term"><code class="literal">library</code></span></dt> | |
| <dd> | |
| This feature is almost equivalent to the <code class="computeroutput"><source></code> | |
| feature, except that it takes effect only for linking. When you want | |
| to link all targets in a Jamfile to certain library, the | |
| <code class="computeroutput"><library></code> feature is preferred over | |
| <code class="computeroutput"><source>X</code> -- the latter will add the library to | |
| all targets, even those that have nothing to do with libraries. | |
| </dd> | |
| <dt><span class="term"><a name="bbv2.builtin.features.dependency"></a> | |
| <code class="literal">dependency</code></span></dt> | |
| <dd> | |
| Introduces a dependency on the target named by the value of this | |
| feature (so it will be brought up-to-date whenever the target being | |
| declared is). The dependency is not used in any other way. | |
| </dd> | |
| <dt><span class="term"><a name="bbv2.builtin.features.use"></a> | |
| <code class="literal">use</code></span></dt> | |
| <dd> | |
| Introduces a dependency on the target named by the value of this | |
| feature (so it will be brought up-to-date whenever the target being | |
| declared is), and adds its usage requirements to the build | |
| properties | |
| of the target being declared. The dependency is not used in any | |
| other way. The primary use case is when you want the usage | |
| requirements (such as <code class="computeroutput">#include</code> paths) of some library | |
| to be applied, but do not want to link to it. | |
| </dd> | |
| <dt><span class="term"><a name="bbv2.reference.features.dll-path"></a> | |
| <code class="literal">dll-path</code></span></dt> | |
| <dd> | |
| Specify an additional directory where the system should | |
| look for shared libraries when the executable or shared | |
| library is run. This feature only affects Unix | |
| compilers. Plase see <a class="xref" href="faq.html#bbv2.faq.dll-path" title="Why are the dll-path and hardcode-dll-paths properties useful?">the section called “ | |
| Why are the <code class="literal">dll-path</code> and <code class="literal">hardcode-dll-paths | |
| </code> properties useful? | |
| ”</a> | |
| in <a class="xref" href="faq.html" title="Frequently Asked Questions">the section called “Frequently Asked Questions”</a> for details. | |
| </dd> | |
| <dt><span class="term"><code class="literal">hardcode-dll-paths</code></span></dt> | |
| <dd> | |
| <p class="simpara"> | |
| Controls automatic generation of dll-path properties. | |
| </p> | |
| <p><span class="bold"><strong>Allowed values:</strong></span> | |
| <code class="literal">true</code>, <code class="literal">false</code>. This property is | |
| specific to Unix systems. If an executable is built with | |
| <code class="computeroutput"><hardcode-dll-paths>true</code>, the generated binary | |
| will contain the list of all the paths to the used shared libraries. | |
| As the result, the executable can be run without changing system | |
| paths to shared libraries or installing the libraries to system | |
| paths. This is very | |
| convenient during development. Plase see the <a class="link" href="faq.html#bbv2.faq.dll-path" title="Why are the dll-path and hardcode-dll-paths properties useful?">FAQ entry</a> for details. Note that on Mac | |
| OSX, the paths are unconditionally hardcoded by the linker, and it | |
| is not possible to disable that behaviour.</p> | |
| </dd> | |
| <dt> | |
| <span class="term"><code class="literal">cflags</code>, </span><span class="term"><code class="literal">cxxflags</code>, </span><span class="term"><code class="literal">linkflags</code></span> | |
| </dt> | |
| <dd> | |
| The value of those features is passed without modification to the | |
| corresponding tools. For <code class="computeroutput">cflags</code> that is both the C and | |
| C++ compilers, for <code class="computeroutput">cxxflags</code> that is the C++ compiler | |
| and for <code class="computeroutput">linkflags</code> that is the linker. The features are | |
| handy when you are trying to do something special that cannot be | |
| achieved by a higher-level feature in Boost.Build. | |
| </dd> | |
| <dt><span class="term"><code class="literal">include</code></span></dt> | |
| <dd> | |
| Specifies an additional include path that is to be passed to C and | |
| C++ compilers. | |
| </dd> | |
| <dt><span class="term"><code class="literal">warnings</code></span></dt> | |
| <dd> | |
| The <code class="computeroutput"><warnings></code> feature controls the warning level | |
| of compilers. It has the following values: | |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | |
| <li class="listitem"><p><code class="computeroutput">off</code> - disables all warnings.</p></li> | |
| <li class="listitem"><p><code class="computeroutput">on</code> - enables default warning level for the tool.</p></li> | |
| <li class="listitem"><p><code class="computeroutput">all</code> - enables all warnings.</p></li> | |
| </ul></div> | |
| Default value is <code class="computeroutput">all</code>. | |
| </dd> | |
| <dt><span class="term"><code class="literal">warnings-as-errors</code></span></dt> | |
| <dd> | |
| The <code class="computeroutput"><warnings-as-errors></code> makes it possible to | |
| treat warnings as errors and abort compilation on a warning. The | |
| value <code class="computeroutput">on</code> enables this behaviour. The default value is | |
| <code class="computeroutput">off</code>. | |
| </dd> | |
| <dt><span class="term"><code class="literal">build</code></span></dt> | |
| <dd> | |
| <p><span class="bold"><strong>Allowed values:</strong></span> <code class="literal">no</code></p> | |
| <p> | |
| The <code class="computeroutput">build</code> feature is used to conditionally disable | |
| build of a target. If <code class="computeroutput"><build>no</code> is in properties | |
| when building a target, build of that target is skipped. Combined | |
| with conditional requirements this allows you to skip building some | |
| target in configurations where the build is known to fail. | |
| </p> | |
| </dd> | |
| <dt><span class="term"><code class="literal">tag</code></span></dt> | |
| <dd> | |
| <p>The <code class="literal">tag</code> feature is used to customize | |
| the name of the generated files. The value should have the form: | |
| </p> | |
| <pre class="programlisting">@<em class="replaceable"><code>rulename</code></em></pre> | |
| <p> where | |
| <em class="replaceable"><code>rulename</code></em> should be a name of a rule with the | |
| following signature: | |
| </p> | |
| <pre class="programlisting">rule tag ( name : type ? : property-set )</pre> | |
| <p> | |
| The rule will be called for each target with the default name computed | |
| by Boost.Build, the type of the target, and property set. The rule can | |
| either return a string that must be used as the name of the target, or | |
| an empty string, in which case the default name will be used. | |
| </p> | |
| <p>Most typical use of the <code class="literal">tag</code> feature is to | |
| encode build properties, or library version in library target names. You | |
| should take care to return non-empty string from the tag rule only for | |
| types you care about — otherwise, you might end up modifying | |
| names of object files, generated header file and other targets for which | |
| changing names does not make sense.</p> | |
| </dd> | |
| <dt><span class="term"><code class="literal">debug-symbols</code></span></dt> | |
| <dd> | |
| <p><span class="bold"><strong>Allowed values:</strong></span> <code class="literal">on</code>, <code class="literal">off</code>.</p> | |
| <p>The <code class="literal">debug-symbols</code> feature specifies if | |
| produced object files, executables and libraries should include | |
| debug information. | |
| Typically, the value of this feature is implicitly set by the | |
| <code class="literal">variant</code> feature, but it can be explicitly | |
| specified by the user. The most common usage is to build | |
| release variant with debugging information.</p> | |
| </dd> | |
| <dt><span class="term"><code class="literal">target-os</code></span></dt> | |
| <dd> | |
| <a name="bbv2.reference.features.target-os"></a><p> | |
| The operating system for which the code is to be generated. The | |
| compiler you used should be the compiler for that operating | |
| system. This option causes Boost.Build to use naming conventions | |
| suitable for that operating system, and adjust build process | |
| accordingly. For example, with gcc, it controls if import | |
| libraries are produced for shared libraries or not. | |
| </p> | |
| <p>The complete list of possible values for this feature is: | |
| aix, bsd, cygwin, darwin, freebsd, hpux, iphone, linux, netbsd, | |
| openbsd, osf, qnx, qnxnto, sgi, solaris, unix, unixware, windows. | |
| </p> | |
| <p>See <a class="xref" href="tasks.html#bbv2.tasks.crosscompile" title="Cross-compilation">the section called “Cross-compilation”</a> for details of | |
| crosscompilation</p> | |
| </dd> | |
| <dt><span class="term"><code class="literal">architecture</code></span></dt> | |
| <dd><p>The <code class="literal">architecture</code> features specifies | |
| the general processor familty to generate code for.</p></dd> | |
| <dt><span class="term"><code class="literal">instruction-set</code></span></dt> | |
| <dd> | |
| <p> | |
| <span class="bold"><strong>Allowed values:</strong></span> depend on the used | |
| toolset. | |
| </p> | |
| <p>The <code class="literal">instruction-set</code> specifies for which | |
| specific instruction set the code should be generated. The | |
| code in general might not run on processors with older/different | |
| instruction sets.</p> | |
| <p>While Boost.Build allows a large set of possible values | |
| for this features, whether a given value works depends on which | |
| compiler you use. Please see | |
| <a class="xref" href="reference.html#bbv2.reference.tools.compilers" title="C++ Compilers">the section called “C++ Compilers”</a> for details. | |
| </p> | |
| </dd> | |
| <dt><span class="term"><code class="literal">address-model</code></span></dt> | |
| <dd> | |
| <p><span class="bold"><strong>Allowed values:</strong></span> <code class="literal">32</code>, <code class="literal">64</code>.</p> | |
| <p>The <code class="literal">address-model</code> specifies if 32-bit or | |
| 64-bit code should be generated by the compiler. Whether this feature | |
| works depends on the used compiler, its version, how the compiler is | |
| configured, and the values of the <code class="literal">architecture</code> | |
| <code class="literal">instruction-set</code> | |
| features. Please see <a class="xref" href="reference.html#bbv2.reference.tools.compilers" title="C++ Compilers">the section called “C++ Compilers”</a> | |
| for details.</p> | |
| </dd> | |
| <dt><span class="term"><code class="literal">c++-template-depth</code></span></dt> | |
| <dd> | |
| <p> | |
| <span class="bold"><strong>Allowed values:</strong></span> Any positive | |
| integer. | |
| </p> | |
| <p> | |
| This feature allows configuring a C++ compiler with the maximal | |
| template instantiation depth parameter. Specific toolsets may or may | |
| not provide support for this feature depending on whether their | |
| compilers provide a corresponding command-line option. | |
| </p> | |
| <p> | |
| <span class="bold"><strong>Note:</strong></span> Due to some internal details | |
| in the current Boost Build implementation it is not possible to have | |
| features whose valid values are all positive integer. As a | |
| workaround a large set of allowed values has been defined for this | |
| feature and, if a different one is needed, user can easily add it by | |
| calling the feature.extend rule. | |
| </p> | |
| </dd> | |
| <dt><span class="term"><code class="literal">embed-manifest</code></span></dt> | |
| <dd> | |
| <a class="indexterm" name="id3273651"></a><a class="indexterm" name="id3273660"></a><p> | |
| <span class="bold"><strong>Allowed values:</strong></span> on, off. | |
| </p> | |
| <p>This feature is specific to the msvc toolset (see | |
| <a class="xref" href="reference.html#bbv2.reference.tools.compiler.msvc" title="Microsoft Visual C++">the section called “Microsoft Visual C++”</a>), | |
| and controls whether the manifest files should be embedded inside | |
| executables and shared libraries, or placed alongside them. This | |
| feature corresponds to the IDE option found in the project settings dialog, | |
| under <span class="guimenu">Configuration Properties</span> → <span class="guisubmenu">Manifest Tool</span> → <span class="guisubmenu">Input and Output</span> → <span class="guimenuitem">Embed manifest</span>. | |
| </p> | |
| </dd> | |
| </dl></div> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h3 class="title"> | |
| <a name="bbv2.reference.tools"></a>Builtin tools</h3></div></div></div> | |
| <div class="toc"><dl> | |
| <dt><span class="section"><a href="reference.html#bbv2.reference.tools.compilers">C++ Compilers</a></span></dt> | |
| <dt><span class="section"><a href="reference.html#id3276330">Third-party libraries</a></span></dt> | |
| </dl></div> | |
| <p>Boost.Build comes with support for a large number of C++ compilers, | |
| and other tools. This section documents how to use those tools.</p> | |
| <p>Before using any tool, you must declare your intention, and possibly | |
| specify additional information about the tool's configuration. This is | |
| done by calling the <code class="computeroutput">using</code> rule, typically in your | |
| <code class="filename">user-config.jam</code>, for example:</p> | |
| <pre class="programlisting"> | |
| using gcc ; | |
| </pre> | |
| <p>additional parameters can be passed just like for other rules, for example:</p> | |
| <pre class="programlisting"> | |
| using gcc : 4.0 : g++-4.0 ; | |
| </pre> | |
| <p>The options that can be passed to each tool are documented in the | |
| subsequent sections.</p> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h4 class="title"> | |
| <a name="bbv2.reference.tools.compilers"></a>C++ Compilers</h4></div></div></div> | |
| <div class="toc"><dl> | |
| <dt><span class="section"><a href="reference.html#bbv2.reference.tools.compiler.gcc">GNU C++</a></span></dt> | |
| <dt><span class="section"><a href="reference.html#bbv2.reference.tools.compiler.darwin">Apple Darwin gcc</a></span></dt> | |
| <dt><span class="section"><a href="reference.html#bbv2.reference.tools.compiler.msvc">Microsoft Visual C++</a></span></dt> | |
| <dt><span class="section"><a href="reference.html#bbv2.reference.tools.compiler.intel">Intel C++</a></span></dt> | |
| <dt><span class="section"><a href="reference.html#bbv2.reference.tools.compiler.acc">HP aC++ compiler</a></span></dt> | |
| <dt><span class="section"><a href="reference.html#bbv2.reference.tools.compiler.borland">Borland C++ Compiler</a></span></dt> | |
| <dt><span class="section"><a href="reference.html#bbv2.reference.tools.compiler.como">Comeau C/C++ Compiler</a></span></dt> | |
| <dt><span class="section"><a href="reference.html#bbv2.reference.tools.compiler.cw">Code Warrior</a></span></dt> | |
| <dt><span class="section"><a href="reference.html#bbv2.reference.tools.compiler.dmc">Digital Mars C/C++ Compiler</a></span></dt> | |
| <dt><span class="section"><a href="reference.html#bbv2.reference.tools.compiler.hp_cxx">HP C++ Compiler for Tru64 Unix</a></span></dt> | |
| <dt><span class="section"><a href="reference.html#bbv2.reference.tools.compiler.sun">Sun Studio</a></span></dt> | |
| <dt><span class="section"><a href="reference.html#bbv2.reference.tools.compiler.vacpp">IBM Visual Age</a></span></dt> | |
| </dl></div> | |
| <p>This section lists all Boost.Build modules that support C++ | |
| compilers and documents how each one can be initialized. The name | |
| of support module for compiler is also the value for | |
| the <code class="computeroutput">toolset</code> feature that can be used to explicitly | |
| request that compiler. </p> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h5 class="title"> | |
| <a name="bbv2.reference.tools.compiler.gcc"></a>GNU C++</h5></div></div></div> | |
| <p>The <code class="computeroutput">gcc</code> module supports the | |
| <a href="http://gcc.gnu.org" target="_top">GNU C++ compiler</a> | |
| on Linux, a number of Unix-like system including SunOS and on Windows | |
| (either <a href="http://www.cygwin.com" target="_top">Cygwin</a> or | |
| <a href="http://www.mingw.org" target="_top">MinGW</a>). On Mac OSX, it is recommended | |
| to use system gcc, see <a class="xref" href="reference.html#bbv2.reference.tools.compiler.darwin" title="Apple Darwin gcc">the section called “Apple Darwin gcc”</a>. | |
| </p> | |
| <p>The <code class="computeroutput">gcc</code> module is initialized using the following | |
| syntax:</p> | |
| <pre class="programlisting"> | |
| using gcc : [<span class="optional"><em class="replaceable"><code>version</code></em></span>] : [<span class="optional"><em class="replaceable"><code>c++-compile-command</code></em></span>] : [<span class="optional"><em class="replaceable"><code>compiler options</code></em></span>] ;</pre> | |
| <p>This statement may be repeated several times, if you want to configure several versions of the compiler.</p> | |
| <p> | |
| If the version is not explicitly specified, it will be | |
| automatically detected by running the compiler with the <code class="computeroutput">-v</code> | |
| option. If the command is not specified, the <span class="command"><strong>g++</strong></span> | |
| binary will be searched in <code class="envar">PATH</code>.</p> | |
| <p>The following options can be provided, using <code class="literal"><<em class="replaceable"><code>option-name</code></em>><em class="replaceable"><code>option-value</code></em></code> syntax:</p> | |
| <div class="variablelist"><dl> | |
| <dt><span class="term"><code class="literal">cflags</code></span></dt> | |
| <dd><p>Specifies additional compiler flags that will be used when | |
| compiling C sources.</p></dd> | |
| <dt><span class="term"><code class="literal">cxxflags</code></span></dt> | |
| <dd><p>Specifies additional compiler flags that will be used when | |
| compiling C++ sources.</p></dd> | |
| <dt><span class="term"><code class="literal">compileflags</code></span></dt> | |
| <dd><p>Specifies additional compiler flags that will be used when | |
| compiling both C and C++ sources.</p></dd> | |
| <dt><span class="term"><code class="literal">linkflags</code></span></dt> | |
| <dd><p>Specifies additional command line options that will be | |
| passed to the linker.</p></dd> | |
| <dt><span class="term"><code class="literal">root</code></span></dt> | |
| <dd><p>Specifies root directory of the compiler installation. | |
| This option is necessary only if it is not possible to detect this | |
| information from the compiler command—for example if the specified | |
| compiler command is a user script.</p></dd> | |
| <dt><span class="term"><code class="literal">rc</code></span></dt> | |
| <dd><p>Specifies the resource compiler command | |
| that will be used with the version of gcc that is being | |
| configured. This setting makes sense only for Windows and only | |
| if you plan to use resource files. By | |
| default <span class="command"><strong>windres</strong></span> will be used.</p></dd> | |
| <dt><span class="term"><code class="literal">rc-type</code></span></dt> | |
| <dd><p>Specifies the type of resource compiler. The value can | |
| be either <code class="computeroutput">windres</code> for msvc resource compiler, | |
| or <code class="computeroutput">rc</code> for borland's resource compiler.</p></dd> | |
| </dl></div> | |
| <a class="indexterm" name="id3274073"></a> | |
| In order to compile 64-bit applications, you have to specify | |
| <code class="computeroutput">address-model=64</code>, and the <code class="computeroutput">instruction-set</code> | |
| feature should refer to a 64 bit processor. Currently, those | |
| include <code class="literal">nocona</code>, <code class="literal">opteron</code>, | |
| <code class="literal">athlon64</code> and <code class="literal">athlon-fx</code>. | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h5 class="title"> | |
| <a name="bbv2.reference.tools.compiler.darwin"></a>Apple Darwin gcc</h5></div></div></div> | |
| <p>The <code class="computeroutput">darwin</code> module supports the version of gcc that is | |
| modified and provided by Apple. The configuration is essentially identical | |
| to that of the gcc module. | |
| </p> | |
| <p> | |
| <a class="indexterm" name="id3274143"></a> | |
| The darwin toolset can generate so called "fat" | |
| binaries—binaries that can run support more than one | |
| architecture, or address mode. To build a binary that can run both | |
| on Intel and PowerPC processors, specify | |
| <code class="computeroutput">architecture=combined</code>. To build a binary that can run | |
| both in 32-bit and 64-bit modes, specify | |
| <code class="computeroutput">address-model=32_64</code>. If you specify both of those | |
| properties, a "4-way" fat binary will be generated. | |
| </p> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h5 class="title"> | |
| <a name="bbv2.reference.tools.compiler.msvc"></a>Microsoft Visual C++</h5></div></div></div> | |
| <p>The <code class="computeroutput">msvc</code> module supports the | |
| <a href="http://msdn.microsoft.com/visualc/" target="_top">Microsoft Visual | |
| C++</a> command-line tools on Microsoft Windows. The supported | |
| products and versions of command line tools are listed below:</p> | |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | |
| <li class="listitem"><p>Visual Studio 2008—9.0</p></li> | |
| <li class="listitem"><p>Visual Studio 2005—8.0</p></li> | |
| <li class="listitem"><p>Visual Studio .NET 2003—7.1</p></li> | |
| <li class="listitem"><p>Visual Studio .NET—7.0</p></li> | |
| <li class="listitem"><p>Visual Studio 6.0, Service Pack 5—6.5</p></li> | |
| </ul></div> | |
| <p>The <code class="computeroutput">msvc</code> module is initialized using the following | |
| syntax:</p> | |
| <pre class="programlisting"> | |
| using msvc : [<span class="optional"><em class="replaceable"><code>version</code></em></span>] : [<span class="optional"><em class="replaceable"><code>c++-compile-command</code></em></span>] : [<span class="optional"><em class="replaceable"><code>compiler options</code></em></span>] ; | |
| </pre> | |
| <p>This statement may be repeated several times, if you want to configure several versions of the compiler.</p> | |
| <p>If the version is not explicitly specified, the most recent | |
| version found in the registry will be used instead. If the special | |
| value <code class="computeroutput">all</code> is passed as the version, all versions found in | |
| the registry will be configured. If a version is specified, but the | |
| command is not, the compiler binary will be searched in standard | |
| installation paths for that version, followed by <code class="envar">PATH</code>. | |
| </p> | |
| <p>The compiler command should be specified using forward slashes, | |
| and quoted.</p> | |
| <p>The following options can be provided, using <code class="literal"><<em class="replaceable"><code>option-name</code></em>><em class="replaceable"><code>option-value</code></em></code> syntax:</p> | |
| <div class="variablelist"><dl> | |
| <dt><span class="term"><code class="literal">cflags</code></span></dt> | |
| <dd><p>Specifies additional compiler flags that will be used when | |
| compiling C sources.</p></dd> | |
| <dt><span class="term"><code class="literal">cxxflags</code></span></dt> | |
| <dd><p>Specifies additional compiler flags that will be used when | |
| compiling C++ sources.</p></dd> | |
| <dt><span class="term"><code class="literal">compileflags</code></span></dt> | |
| <dd><p>Specifies additional compiler flags that will be used when | |
| compiling both C and C++ sources.</p></dd> | |
| <dt><span class="term"><code class="literal">linkflags</code></span></dt> | |
| <dd><p>Specifies additional command line options that will be | |
| passed to the linker.</p></dd> | |
| <dt><span class="term"><code class="literal">assembler</code></span></dt> | |
| <dd><p>The command that compiles assembler sources. If | |
| not specified, <span class="command"><strong>ml</strong></span> will be used. The command | |
| will be invoked after the setup script was executed and adjusted | |
| the <code class="envar">PATH</code> variable.</p></dd> | |
| <dt><span class="term"><code class="literal">compiler</code></span></dt> | |
| <dd><p>The command that compiles C and C++ sources. If | |
| not specified, <span class="command"><strong>cl</strong></span> will be used. The command | |
| will be invoked after the setup script was executed and adjusted | |
| the <code class="envar">PATH</code> variable.</p></dd> | |
| <dt><span class="term"><code class="literal">compiler-filter</code></span></dt> | |
| <dd><p>Command through which to pipe the output of | |
| running the compiler. For example to pass the output to STLfilt. | |
| </p></dd> | |
| <dt><span class="term"><code class="literal">idl-compiler</code></span></dt> | |
| <dd><p>The command that compiles Microsoft COM interface | |
| definition files. If not specified, <span class="command"><strong>midl</strong></span> will | |
| be used. The command will be invoked after the setup script was | |
| executed and adjusted the <code class="envar">PATH</code> variable.</p></dd> | |
| <dt><span class="term"><code class="literal">linker</code></span></dt> | |
| <dd><p>The command that links executables and dynamic | |
| libraries. If not specified, <span class="command"><strong>link</strong></span> will be used. | |
| The command will be invoked after the setup script was executed | |
| and adjusted the <code class="envar">PATH</code> variable.</p></dd> | |
| <dt><span class="term"><code class="literal">mc-compiler</code></span></dt> | |
| <dd><p>The command that compiles Microsoft message | |
| catalog files. If not specified, <span class="command"><strong>mc</strong></span> will be | |
| used. The command will be invoked after the setup script was | |
| executed and adjusted the <code class="envar">PATH</code> variable.</p></dd> | |
| <dt><span class="term"><code class="literal">resource-compiler</code></span></dt> | |
| <dd><p>The command that compiles resource files. If not | |
| specified, <span class="command"><strong>rc</strong></span> will be used. The command will be | |
| invoked after the setup script was executed and adjusted the | |
| <code class="envar">PATH</code> variable.</p></dd> | |
| <dt><span class="term"><code class="literal">setup</code></span></dt> | |
| <dd><p>The filename of the global environment setup | |
| script to run before invoking any of the tools defined in this | |
| toolset. Will not be used in case a target platform specific | |
| script has been explicitly specified for the current target | |
| platform. Used setup script will be passed the target platform | |
| identifier (x86, x86_amd64, x86_ia64, amd64 or ia64) as a | |
| arameter. If not specified a default script is chosen based on the | |
| used compiler binary, e.g. <span class="command"><strong>vcvars32.bat</strong></span> or | |
| <span class="command"><strong>vsvars32.bat</strong></span>.</p></dd> | |
| <dt> | |
| <span class="term"><code class="literal">setup-amd64</code>, </span><span class="term"><code class="literal">setup-i386</code>, </span><span class="term"><code class="literal">setup-ia64</code></span> | |
| </dt> | |
| <dd><p>The filename of the target platform specific | |
| environment setup script to run before invoking any of the tools | |
| defined in this toolset. If not specified the global environment | |
| setup script is used.</p></dd> | |
| </dl></div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h6 class="title"> | |
| <a name="v2.reference.tools.compiler.msvc.64"></a>64-bit support</h6></div></div></div> | |
| <a class="indexterm" name="id3274616"></a><p>Starting with version 8.0, Microsoft Visual Studio can | |
| generate binaries for 64-bit processor, both 64-bit flavours of x86 | |
| (codenamed AMD64/EM64T), and Itanium (codenamed IA64). In addition, | |
| compilers that are itself run in 64-bit mode, for better | |
| performance, are provided. The complete list of compiler | |
| configurations are as follows (we abbreviate AMD64/EM64T to just | |
| AMD64):</p> | |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | |
| <li class="listitem"><p>32-bit x86 host, 32-bit x86 target</p></li> | |
| <li class="listitem"><p>32-bit x86 host, 64-bit AMD64 target</p></li> | |
| <li class="listitem"><p>32-bit x86 host, 64-bit IA64 target</p></li> | |
| <li class="listitem"><p>64-bit AMD64 host, 64-bit AMD64 target</p></li> | |
| <li class="listitem"><p>64-bit IA64 host, 64-bit IA64 target</p></li> | |
| </ul></div> | |
| <p> | |
| The 32-bit host compilers can be always used, even on 64-bit | |
| Windows. On the contrary, 64-bit host compilers require both 64-bit | |
| host processor and 64-bit Windows, but can be faster. By default, | |
| only 32-bit host, 32-bit target compiler is installed, and | |
| additional compilers need to be installed explicitly. | |
| </p> | |
| <p>To use 64-bit compilation you should:</p> | |
| <div class="orderedlist"><ol class="orderedlist" type="1"> | |
| <li class="listitem"><p>Configure you compiler as usual. If you provide a | |
| path to the compiler explicitly, provide the path to the 32-bit | |
| compiler. If you try to specify the path to any of 64-bit | |
| compilers, configuration will not work.</p></li> | |
| <li class="listitem"><p>When compiling, use <code class="computeroutput">address-model=64</code>, | |
| to generate AMD64 code.</p></li> | |
| <li class="listitem"><p>To generate IA64 code, use | |
| <code class="computeroutput">architecture=ia64</code></p></li> | |
| </ol></div> | |
| <p>The (AMD64 host, AMD64 target) compiler will be used | |
| automatically when you are generating AMD64 code and are running | |
| 64-bit Windows on AMD64. The (IA64 host, IA64 target) compiler will | |
| never be used, since nobody has an IA64 machine to test.</p> | |
| <p>It is believed that AMD64 and EM64T targets are essentially | |
| compatible. The compiler options <code class="computeroutput">/favor:AMD64</code> and | |
| <code class="computeroutput">/favor:EM64T</code>, which are accepted only by AMD64 | |
| targeting compilers, cause the generated code to be tuned to a | |
| specific flavor of 64-bit x86. Boost.Build will make use of those | |
| options depending on the value of the<code class="computeroutput">instruction-set</code> | |
| feature.</p> | |
| </div> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h5 class="title"> | |
| <a name="bbv2.reference.tools.compiler.intel"></a>Intel C++</h5></div></div></div> | |
| <p>The <code class="computeroutput">intel-linux</code> and <code class="computeroutput">intel-win</code> modules | |
| support the Intel C++ command-line compiler—the <a href="http://www.intel.com/software/products/compilers/clin/index.htm" target="_top">Linux</a> | |
| and <a href="http://www.intel.com/cd/software/products/asmo-na/eng/compilers/284527.htm" target="_top"> | |
| Windows</a> versions respectively.</p> | |
| <p>The module is initialized using the following syntax:</p> | |
| <pre class="programlisting"> | |
| using intel-linux : [<span class="optional"><em class="replaceable"><code>version</code></em></span>] : [<span class="optional"><em class="replaceable"><code>c++-compile-command</code></em></span>] : [<span class="optional"><em class="replaceable"><code>compiler options</code></em></span>] ;</pre> | |
| <p>or</p> | |
| <pre class="programlisting"> | |
| using intel-win : [<span class="optional"><em class="replaceable"><code>version</code></em></span>] : [<span class="optional"><em class="replaceable"><code>c++-compile-command</code></em></span>] : [<span class="optional"><em class="replaceable"><code>compiler options</code></em></span>] ;</pre> | |
| <p>respectively.</p> | |
| <p>This statement may be repeated several times, if you want to configure several versions of the compiler.</p> | |
| <p> | |
| If compiler command is not specified, then Boost.Build will | |
| look in <code class="envar">PATH</code> for an executable <span class="command"><strong>icpc</strong></span> | |
| (on Linux), or <span class="command"><strong>icc.exe</strong></span> (on Windows). | |
| </p> | |
| <p>The following options can be provided, using <code class="literal"><<em class="replaceable"><code>option-name</code></em>><em class="replaceable"><code>option-value</code></em></code> syntax:</p> | |
| <div class="variablelist"><dl> | |
| <dt><span class="term"><code class="literal">cflags</code></span></dt> | |
| <dd><p>Specifies additional compiler flags that will be used when | |
| compiling C sources.</p></dd> | |
| <dt><span class="term"><code class="literal">cxxflags</code></span></dt> | |
| <dd><p>Specifies additional compiler flags that will be used when | |
| compiling C++ sources.</p></dd> | |
| <dt><span class="term"><code class="literal">compileflags</code></span></dt> | |
| <dd><p>Specifies additional compiler flags that will be used when | |
| compiling both C and C++ sources.</p></dd> | |
| <dt><span class="term"><code class="literal">linkflags</code></span></dt> | |
| <dd><p>Specifies additional command line options that will be | |
| passed to the linker.</p></dd> | |
| </dl></div> | |
| <p>The Linux version supports the following additional options:</p> | |
| <div class="variablelist"><dl> | |
| <dt><span class="term"><code class="literal">root</code></span></dt> | |
| <dd><p>Specifies root directory of the compiler installation. | |
| This option is necessary only if it is not possible to detect this | |
| information from the compiler command—for example if the specified | |
| compiler command is a user script.</p></dd> | |
| </dl></div> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h5 class="title"> | |
| <a name="bbv2.reference.tools.compiler.acc"></a>HP aC++ compiler</h5></div></div></div> | |
| <p>The <code class="computeroutput">acc</code> module supports the | |
| <a href="http://h21007.www2.hp.com/dspp/tech/tech_TechSoftwareDetailPage_IDX/1,1703,1740,00.html" target="_top">HP aC++ compiler</a> | |
| for the HP-UX operating system.</p> | |
| <p>The module is initialized using the following | |
| syntax:</p> | |
| <pre class="programlisting"> | |
| using acc : [<span class="optional"><em class="replaceable"><code>version</code></em></span>] : [<span class="optional"><em class="replaceable"><code>c++-compile-command</code></em></span>] : [<span class="optional"><em class="replaceable"><code>compiler options</code></em></span>] ;</pre> | |
| <p>This statement may be repeated several times, if you want to configure several versions of the compiler.</p> | |
| <p> | |
| If the command is not specified, the <span class="command"><strong>aCC</strong></span> | |
| binary will be searched in <code class="envar">PATH</code>.</p> | |
| <p>The following options can be provided, using <code class="literal"><<em class="replaceable"><code>option-name</code></em>><em class="replaceable"><code>option-value</code></em></code> syntax:</p> | |
| <div class="variablelist"><dl> | |
| <dt><span class="term"><code class="literal">cflags</code></span></dt> | |
| <dd><p>Specifies additional compiler flags that will be used when | |
| compiling C sources.</p></dd> | |
| <dt><span class="term"><code class="literal">cxxflags</code></span></dt> | |
| <dd><p>Specifies additional compiler flags that will be used when | |
| compiling C++ sources.</p></dd> | |
| <dt><span class="term"><code class="literal">compileflags</code></span></dt> | |
| <dd><p>Specifies additional compiler flags that will be used when | |
| compiling both C and C++ sources.</p></dd> | |
| <dt><span class="term"><code class="literal">linkflags</code></span></dt> | |
| <dd><p>Specifies additional command line options that will be | |
| passed to the linker.</p></dd> | |
| </dl></div> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h5 class="title"> | |
| <a name="bbv2.reference.tools.compiler.borland"></a>Borland C++ Compiler</h5></div></div></div> | |
| <p>The <code class="computeroutput">borland</code> module supports the command line | |
| C++ compiler included in | |
| <a href="http://www.borland.com/us/products/cbuilder/index.html" target="_top">C++ Builder 2006</a> | |
| product and earlier version of it, running on Microsoft Windows.</p> | |
| <p>The supported products are listed below. The version reported | |
| by the command lines tools is also listed for reference.:</p> | |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | |
| <li class="listitem"><p>C++ Builder 2006—5.8.2</p></li> | |
| <li class="listitem"><p>CBuilderX—5.6.5, 5.6.4 (depending on release)</p></li> | |
| <li class="listitem"><p>CBuilder6—5.6.4</p></li> | |
| <li class="listitem"><p>Free command line tools—5.5.1</p></li> | |
| </ul></div> | |
| <p>The module is initialized using the following syntax:</p> | |
| <pre class="programlisting"> | |
| using borland : [<span class="optional"><em class="replaceable"><code>version</code></em></span>] : [<span class="optional"><em class="replaceable"><code>c++-compile-command</code></em></span>] : [<span class="optional"><em class="replaceable"><code>compiler options</code></em></span>] ;</pre> | |
| <p>This statement may be repeated several times, if you want to configure several versions of the compiler.</p> | |
| <p>If the command is not specified, Boost.Build will search for | |
| a binary named <span class="command"><strong>bcc32</strong></span> in <code class="envar">PATH</code>.</p> | |
| <p>The following options can be provided, using <code class="literal"><<em class="replaceable"><code>option-name</code></em>><em class="replaceable"><code>option-value</code></em></code> syntax:</p> | |
| <div class="variablelist"><dl> | |
| <dt><span class="term"><code class="literal">cflags</code></span></dt> | |
| <dd><p>Specifies additional compiler flags that will be used when | |
| compiling C sources.</p></dd> | |
| <dt><span class="term"><code class="literal">cxxflags</code></span></dt> | |
| <dd><p>Specifies additional compiler flags that will be used when | |
| compiling C++ sources.</p></dd> | |
| <dt><span class="term"><code class="literal">compileflags</code></span></dt> | |
| <dd><p>Specifies additional compiler flags that will be used when | |
| compiling both C and C++ sources.</p></dd> | |
| <dt><span class="term"><code class="literal">linkflags</code></span></dt> | |
| <dd><p>Specifies additional command line options that will be | |
| passed to the linker.</p></dd> | |
| </dl></div> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h5 class="title"> | |
| <a name="bbv2.reference.tools.compiler.como"></a>Comeau C/C++ Compiler</h5></div></div></div> | |
| <p>The <code class="computeroutput">como-linux</code> and the <code class="computeroutput">como-win</code> | |
| modules supports the | |
| <a href="http://www.comeaucomputing.com/" target="_top">Comeau C/C++ Compiler</a> | |
| on Linux and Windows respectively.</p> | |
| <p>The module is initialized using the following syntax:</p> | |
| <pre class="programlisting"> | |
| using como-linux : [<span class="optional"><em class="replaceable"><code>version</code></em></span>] : [<span class="optional"><em class="replaceable"><code>c++-compile-command</code></em></span>] : [<span class="optional"><em class="replaceable"><code>compiler options</code></em></span>] ;</pre> | |
| <p>This statement may be repeated several times, if you want to configure several versions of the compiler.</p> | |
| <p>If the command is not specified, Boost.Build will search for | |
| a binary named <span class="command"><strong>como</strong></span> in | |
| <code class="envar">PATH</code>.</p> | |
| <p>The following options can be provided, using <code class="literal"><<em class="replaceable"><code>option-name</code></em>><em class="replaceable"><code>option-value</code></em></code> syntax:</p> | |
| <div class="variablelist"><dl> | |
| <dt><span class="term"><code class="literal">cflags</code></span></dt> | |
| <dd><p>Specifies additional compiler flags that will be used when | |
| compiling C sources.</p></dd> | |
| <dt><span class="term"><code class="literal">cxxflags</code></span></dt> | |
| <dd><p>Specifies additional compiler flags that will be used when | |
| compiling C++ sources.</p></dd> | |
| <dt><span class="term"><code class="literal">compileflags</code></span></dt> | |
| <dd><p>Specifies additional compiler flags that will be used when | |
| compiling both C and C++ sources.</p></dd> | |
| <dt><span class="term"><code class="literal">linkflags</code></span></dt> | |
| <dd><p>Specifies additional command line options that will be | |
| passed to the linker.</p></dd> | |
| </dl></div> | |
| <p>Before using the Windows version of the compiler, you need to | |
| setup necessary environment variables per compiler's documentation. In | |
| particular, the <code class="envar">COMO_XXX_INCLUDE</code> variable should be | |
| set, where <code class="envar">XXX</code> corresponds to the used backend C | |
| compiler.</p> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h5 class="title"> | |
| <a name="bbv2.reference.tools.compiler.cw"></a>Code Warrior</h5></div></div></div> | |
| <p>The <code class="computeroutput">cw</code> module support CodeWarrior compiler, | |
| originally produced by Metrowerks and presently developed by | |
| Freescale. Boost.Build supports only the versions of the compiler that | |
| target x86 processors. All such versions were released by Metrowerks | |
| before aquisition and are not sold any longer. The last version known | |
| to work is 9.4.</p> | |
| <p>The module is initialized using the following syntax:</p> | |
| <pre class="programlisting"> | |
| using cw : [<span class="optional"><em class="replaceable"><code>version</code></em></span>] : [<span class="optional"><em class="replaceable"><code>c++-compile-command</code></em></span>] : [<span class="optional"><em class="replaceable"><code>compiler options</code></em></span>] ;</pre> | |
| <p>This statement may be repeated several times, if you want to configure several versions of the compiler.</p> | |
| <p>If the command is not specified, Boost.Build will search for a | |
| binary named <span class="command"><strong>mwcc</strong></span> in default installation paths and | |
| in <code class="envar">PATH</code>.</p> | |
| <p>The following options can be provided, using <code class="literal"><<em class="replaceable"><code>option-name</code></em>><em class="replaceable"><code>option-value</code></em></code> syntax:</p> | |
| <div class="variablelist"><dl> | |
| <dt><span class="term"><code class="literal">cflags</code></span></dt> | |
| <dd><p>Specifies additional compiler flags that will be used when | |
| compiling C sources.</p></dd> | |
| <dt><span class="term"><code class="literal">cxxflags</code></span></dt> | |
| <dd><p>Specifies additional compiler flags that will be used when | |
| compiling C++ sources.</p></dd> | |
| <dt><span class="term"><code class="literal">compileflags</code></span></dt> | |
| <dd><p>Specifies additional compiler flags that will be used when | |
| compiling both C and C++ sources.</p></dd> | |
| <dt><span class="term"><code class="literal">linkflags</code></span></dt> | |
| <dd><p>Specifies additional command line options that will be | |
| passed to the linker.</p></dd> | |
| <dt><span class="term"><code class="literal">root</code></span></dt> | |
| <dd><p>Specifies root directory of the compiler installation. | |
| This option is necessary only if it is not possible to detect this | |
| information from the compiler command—for example if the specified | |
| compiler command is a user script.</p></dd> | |
| <dt><span class="term"><code class="literal">setup</code></span></dt> | |
| <dd><p>The command that sets up environment variables | |
| prior to invoking the compiler. If not specified, | |
| <span class="command"><strong>cwenv.bat</strong></span> alongside the compiler binary | |
| will be used.</p></dd> | |
| <dt><span class="term"><code class="literal">compiler</code></span></dt> | |
| <dd><p>The command that compiles C and C++ sources. | |
| If not specified, <span class="command"><strong>mwcc</strong></span> will be used. The | |
| command will be invoked after the setup script was | |
| executed and adjusted the <code class="envar">PATH</code> variable.</p></dd> | |
| <dt><span class="term"><code class="literal">linker</code></span></dt> | |
| <dd><p>The command that links executables and dynamic | |
| libraries. | |
| If not specified, <span class="command"><strong>mwld</strong></span> will be used. The | |
| command will be invoked after the setup script was | |
| executed and adjusted the <code class="envar">PATH</code> variable.</p></dd> | |
| </dl></div> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h5 class="title"> | |
| <a name="bbv2.reference.tools.compiler.dmc"></a>Digital Mars C/C++ Compiler</h5></div></div></div> | |
| <p>The <code class="computeroutput">dmc</code> module supports the | |
| <a href="http://www.digitalmars.com/" target="_top">Digital Mars C++ compiler.</a> | |
| </p> | |
| <p>The module is initialized using the following syntax:</p> | |
| <pre class="programlisting"> | |
| using dmc : [<span class="optional"><em class="replaceable"><code>version</code></em></span>] : [<span class="optional"><em class="replaceable"><code>c++-compile-command</code></em></span>] : [<span class="optional"><em class="replaceable"><code>compiler options</code></em></span>] ;</pre> | |
| <p>This statement may be repeated several times, if you want to configure several versions of the compiler.</p> | |
| <p>If the command is not specified, Boost.Build will search for | |
| a binary named <span class="command"><strong>dmc</strong></span> in | |
| <code class="envar">PATH</code>.</p> | |
| <p>The following options can be provided, using <code class="literal"><<em class="replaceable"><code>option-name</code></em>><em class="replaceable"><code>option-value</code></em></code> syntax:</p> | |
| <div class="variablelist"><dl> | |
| <dt><span class="term"><code class="literal">cflags</code></span></dt> | |
| <dd><p>Specifies additional compiler flags that will be used when | |
| compiling C sources.</p></dd> | |
| <dt><span class="term"><code class="literal">cxxflags</code></span></dt> | |
| <dd><p>Specifies additional compiler flags that will be used when | |
| compiling C++ sources.</p></dd> | |
| <dt><span class="term"><code class="literal">compileflags</code></span></dt> | |
| <dd><p>Specifies additional compiler flags that will be used when | |
| compiling both C and C++ sources.</p></dd> | |
| <dt><span class="term"><code class="literal">linkflags</code></span></dt> | |
| <dd><p>Specifies additional command line options that will be | |
| passed to the linker.</p></dd> | |
| </dl></div> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h5 class="title"> | |
| <a name="bbv2.reference.tools.compiler.hp_cxx"></a>HP C++ Compiler for Tru64 Unix</h5></div></div></div> | |
| <p>The <code class="computeroutput">hp_cxx</code> modules supports the | |
| <a href="http://h30097.www3.hp.com/cplus/?jumpid=reg_R1002_USEN" target="_top"> | |
| HP C++ Compiler</a> for Tru64 Unix.</p> | |
| <p>The module is initialized using the following syntax:</p> | |
| <pre class="programlisting"> | |
| using hp_cxx : [<span class="optional"><em class="replaceable"><code>version</code></em></span>] : [<span class="optional"><em class="replaceable"><code>c++-compile-command</code></em></span>] : [<span class="optional"><em class="replaceable"><code>compiler options</code></em></span>] ;</pre> | |
| <p>This statement may be repeated several times, if you want to configure several versions of the compiler.</p> | |
| <p>If the command is not specified, Boost.Build will search for | |
| a binary named <span class="command"><strong>hp_cxx</strong></span> in <code class="envar">PATH</code>.</p> | |
| <p>The following options can be provided, using <code class="literal"><<em class="replaceable"><code>option-name</code></em>><em class="replaceable"><code>option-value</code></em></code> syntax:</p> | |
| <div class="variablelist"><dl> | |
| <dt><span class="term"><code class="literal">cflags</code></span></dt> | |
| <dd><p>Specifies additional compiler flags that will be used when | |
| compiling C sources.</p></dd> | |
| <dt><span class="term"><code class="literal">cxxflags</code></span></dt> | |
| <dd><p>Specifies additional compiler flags that will be used when | |
| compiling C++ sources.</p></dd> | |
| <dt><span class="term"><code class="literal">compileflags</code></span></dt> | |
| <dd><p>Specifies additional compiler flags that will be used when | |
| compiling both C and C++ sources.</p></dd> | |
| <dt><span class="term"><code class="literal">linkflags</code></span></dt> | |
| <dd><p>Specifies additional command line options that will be | |
| passed to the linker.</p></dd> | |
| </dl></div> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h5 class="title"> | |
| <a name="bbv2.reference.tools.compiler.sun"></a>Sun Studio</h5></div></div></div> | |
| <p>The <code class="computeroutput">sun</code> module supports the | |
| <a href="http://developers.sun.com/sunstudio/index.jsp" target="_top"> | |
| Sun Studio</a> C++ compilers for the Solaris OS.</p> | |
| <p>The module is initialized using the following syntax:</p> | |
| <pre class="programlisting"> | |
| using sun : [<span class="optional"><em class="replaceable"><code>version</code></em></span>] : [<span class="optional"><em class="replaceable"><code>c++-compile-command</code></em></span>] : [<span class="optional"><em class="replaceable"><code>compiler options</code></em></span>] ;</pre> | |
| <p>This statement may be repeated several times, if you want to configure several versions of the compiler.</p> | |
| <p>If the command is not specified, Boost.Build will search for | |
| a binary named <span class="command"><strong>CC</strong></span> | |
| in <code class="filename">/opt/SUNWspro/bin</code> and in | |
| <code class="envar">PATH</code>.</p> | |
| <p>When using this compiler on complex C++ code, such as the | |
| <a href="http://boost.org" target="_top">Boost C++ library</a>, it is | |
| recommended to specify the following options when intializing the | |
| <code class="computeroutput">sun</code> module: | |
| </p> | |
| <pre class="screen"> | |
| -library=stlport4 -features=tmplife -features=tmplrefstatic | |
| </pre> | |
| <p> See the <a href="http://blogs.sun.com/sga/entry/command_line_options" target="_top"> | |
| Sun C++ Frontend Tales</a> for details.</p> | |
| <p>The following options can be provided, using <code class="literal"><<em class="replaceable"><code>option-name</code></em>><em class="replaceable"><code>option-value</code></em></code> syntax:</p> | |
| <div class="variablelist"><dl> | |
| <dt><span class="term"><code class="literal">cflags</code></span></dt> | |
| <dd><p>Specifies additional compiler flags that will be used when | |
| compiling C sources.</p></dd> | |
| <dt><span class="term"><code class="literal">cxxflags</code></span></dt> | |
| <dd><p>Specifies additional compiler flags that will be used when | |
| compiling C++ sources.</p></dd> | |
| <dt><span class="term"><code class="literal">compileflags</code></span></dt> | |
| <dd><p>Specifies additional compiler flags that will be used when | |
| compiling both C and C++ sources.</p></dd> | |
| <dt><span class="term"><code class="literal">linkflags</code></span></dt> | |
| <dd><p>Specifies additional command line options that will be | |
| passed to the linker.</p></dd> | |
| </dl></div> | |
| <a class="indexterm" name="id3276248"></a> | |
| Starting with Sun Studio 12, you can create 64-bit applications | |
| by using the <code class="computeroutput">address-model=64</code> property. | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h5 class="title"> | |
| <a name="bbv2.reference.tools.compiler.vacpp"></a>IBM Visual Age</h5></div></div></div> | |
| <p>The <code class="computeroutput">vacpp</code> module supports the | |
| <a href="http://www.ibm.com/software/ad/vacpp" target="_top">IBM Visual | |
| Age</a> C++ Compiler, for the AIX operating system. Versions | |
| 7.1 and 8.0 are known to work.</p> | |
| <p>The module is initialized using the following | |
| syntax:</p> | |
| <pre class="programlisting"> | |
| using vacpp ;</pre> | |
| <p>The module does not accept any initialization options. The | |
| compiler should be installed in the <code class="filename">/usr/vacpp/bin</code> | |
| directory.</p> | |
| <p>Later versions of Visual Age are known as XL C/C++. They | |
| were not tested with the the <code class="computeroutput">vacpp</code> module.</p> | |
| </div> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h4 class="title"> | |
| <a name="id3276330"></a>Third-party libraries</h4></div></div></div> | |
| <div class="toc"><dl><dt><span class="section"><a href="reference.html#bbv2.reference.tools.libraries.stlport">STLport library</a></span></dt></dl></div> | |
| <p>Boost.Build provides special support for some | |
| third-party C++ libraries, documented below.</p> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h5 class="title"> | |
| <a name="bbv2.reference.tools.libraries.stlport"></a>STLport library</h5></div></div></div> | |
| <a class="indexterm" name="id3276353"></a><p>The <a href="http://stlport.org" target="_top">STLport</a> library | |
| is an alternative implementation of C++ runtime library. Boost.Build | |
| supports using that library on Windows platfrom. Linux is | |
| hampered by different naming of libraries in each STLport | |
| version and is not officially supported.</p> | |
| <p>Before using STLport, you need to configure it in | |
| <code class="filename">user-config.jam</code> using the following syntax: | |
| </p> | |
| <pre class="programlisting"> | |
| using stlport : [<span class="optional"><em class="replaceable"><code>version</code></em></span>] : <em class="replaceable"><code>header-path</code></em> : [<span class="optional"><em class="replaceable"><code>library-path</code></em></span>] ; | |
| </pre> | |
| <p> | |
| Where <em class="replaceable"><code>version</code></em> is the version of | |
| STLport, for example <code class="literal">5.1.4</code>, | |
| <em class="replaceable"><code>headers</code></em> is the location where | |
| STLport headers can be found, and <em class="replaceable"><code>libraries</code></em> | |
| is the location where STLport libraries can be found. | |
| The version should always be provided, and the library path should | |
| be provided if you're using STLport's implementation of | |
| iostreams. Note that STLport 5.* always uses its own iostream | |
| implementation, so the library path is required. | |
| </p> | |
| <p>When STLport is configured, you can build with STLport by | |
| requesting <code class="literal">stdlib=stlport</code> on the command line. | |
| </p> | |
| </div> | |
| </div> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h3 class="title"> | |
| <a name="bbv2.reference.buildprocess"></a>Build process</h3></div></div></div> | |
| <div class="toc"><dl> | |
| <dt><span class="section"><a href="reference.html#bbv2.reference.buildprocess.alternatives">Alternative selection</a></span></dt> | |
| <dt><span class="section"><a href="reference.html#bbv2.reference.buildprocess.common">Determining common properties</a></span></dt> | |
| </dl></div> | |
| <p>The general overview of the build process was given in the | |
| <a class="link" href="overview.html#bbv2.overview.build_process" title="The Build Process">user documentation</a>. | |
| This section provides additional details, and some specific rules. | |
| </p> | |
| <p>To recap, building a target with specific properties includes the | |
| following steps: | |
| </p> | |
| <div class="orderedlist"><ol class="orderedlist" type="1"> | |
| <li class="listitem"><p>applying default build,</p></li> | |
| <li class="listitem"><p>selecting the main target alternative to use, | |
| </p></li> | |
| <li class="listitem"><p>determining "common" properties,</p></li> | |
| <li class="listitem"><p>building targets referred by the sources list and | |
| dependency properties,</p></li> | |
| <li class="listitem"><p>adding the usage requirements produces when building | |
| dependencies to the "common" properties,</p></li> | |
| <li class="listitem"><p>building the target using generators,</p></li> | |
| <li class="listitem"><p>computing the usage requirements to be returned.</p></li> | |
| </ol></div> | |
| <p> | |
| </p> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h4 class="title"> | |
| <a name="bbv2.reference.buildprocess.alternatives"></a>Alternative selection</h4></div></div></div> | |
| <p>When there are several alternatives, one of them must be | |
| selected. The process is as follows:</p> | |
| <div class="orderedlist"><ol class="orderedlist" type="1"> | |
| <li class="listitem"> | |
| For each alternative <span class="emphasis"><em>condition</em></span> is defined as | |
| the set of base properties in requirements. [Note: it might be | |
| better to specify the condition explicitly, as in conditional | |
| requirements]. | |
| </li> | |
| <li class="listitem"> | |
| An alternative is viable only if all properties in condition | |
| are present in build request. | |
| </li> | |
| <li class="listitem"> | |
| If there's one viable alternative, it's choosen. Otherwise, | |
| an attempt is made to find one best alternative. An alternative | |
| a is better than another alternative b, iff the set of properties | |
| in b's condition is a strict subset of the set of properities of | |
| 'a's condition. If there's one viable alternative, which is | |
| better than all others, it's selected. Otherwise, an error is | |
| reported. | |
| </li> | |
| </ol></div> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h4 class="title"> | |
| <a name="bbv2.reference.buildprocess.common"></a>Determining common properties</h4></div></div></div> | |
| <p>The "common" properties is a somewhat artificial term. Those are | |
| the intermediate property set from which both the build request for | |
| dependencies and properties for building the target are derived. | |
| </p> | |
| <p>Since default build and alternatives are already handled, we have | |
| only two inputs: build requests and requirements. Here are the rules | |
| about common properties. | |
| </p> | |
| <div class="orderedlist"><ol class="orderedlist" type="1"> | |
| <li class="listitem"><p>Non-free feature can have only one | |
| value</p></li> | |
| <li class="listitem"><p>A non-conditional property in requirement in always | |
| present in common properties.</p></li> | |
| <li class="listitem"><p>A property in build request is present in | |
| common properties, unless (2) tells otherwise.</p></li> | |
| <li class="listitem"><p>If either build request, or requirements (non-conditional | |
| or conditional) include an expandable property (either composite, | |
| or property with specified subfeature value), the behaviour is | |
| equivalent to explicitly adding all expanded properties to build | |
| request or requirements.</p></li> | |
| <li class="listitem"><p>If requirements include a conditional property, and | |
| condiiton of this property is true in context of common | |
| properties, then the conditional property should be in common | |
| properties as well.</p></li> | |
| <li class="listitem"><p>If no value for a feature is given by other rules | |
| here, it has default value in common properties.</p></li> | |
| </ol></div> | |
| <p>Those rules are declarative, they don't specify how to compute the | |
| common properties. However, they provide enough information for the | |
| user. The important point is the handling of conditional | |
| requirements. The condition can be satisfied either by property in | |
| build request, by non-conditional requirements, or even by another | |
| conditional property. For example, the following example works as | |
| expected: | |
| </p> | |
| <pre class="programlisting"> | |
| exe a : a.cpp | |
| : <toolset>gcc:<variant>release | |
| <variant>release:<define>FOO ; | |
| </pre> | |
| <p> | |
| </p> | |
| </div> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h3 class="title"> | |
| <a name="bbv2.reference.definitions"></a>Definitions</h3></div></div></div> | |
| <div class="toc"><dl> | |
| <dt><span class="section"><a href="reference.html#bbv2.reference.features">Features and properties</a></span></dt> | |
| <dt><span class="section"><a href="reference.html#bbv2.reference.variants">Build Variants</a></span></dt> | |
| <dt><span class="section"><a href="reference.html#bbv2.reference.variants.proprefine">Property refinement</a></span></dt> | |
| <dt><span class="section"><a href="reference.html#bbv2.reference.variants.propcond">Conditional properties</a></span></dt> | |
| <dt><span class="section"><a href="reference.html#bbv2.reference.ids">Target identifiers and references</a></span></dt> | |
| </dl></div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h4 class="title"> | |
| <a name="bbv2.reference.features"></a>Features and properties</h4></div></div></div> | |
| <div class="toc"><dl> | |
| <dt><span class="section"><a href="reference.html#bbv2.reference.features.validity">Property Validity</a></span></dt> | |
| <dt><span class="section"><a href="reference.html#bbv2.reference.features.attributes">Feature Attributes</a></span></dt> | |
| <dt><span class="section"><a href="reference.html#bbv2.reference.features.declaration">Feature Declaration</a></span></dt> | |
| </dl></div> | |
| <p>A <span class="emphasis"><em>feature</em></span> is a normalized (toolset-independent) | |
| aspect of a build configuration, such as whether inlining is | |
| enabled. Feature names may not contain the '<code class="literal">></code>' | |
| character.</p> | |
| <p>Each feature in a build configuration has one or more | |
| associated <span class="emphasis"><em>value</em></span>s. Feature values for non-free features | |
| may not contain the '<code class="literal"><</code>', '<code class="literal">:</code>', or | |
| '<code class="literal">=</code>' characters. Feature values for free features may not | |
| contain the '<code class="literal"><</code>' character.</p> | |
| <p>A <span class="emphasis"><em>property</em></span> is a (feature,value) pair, expressed as | |
| <feature>value.</p> | |
| <p>A <span class="emphasis"><em>subfeature</em></span> is a feature that only exists in the | |
| presence of its parent feature, and whose identity can be derived | |
| (in the context of its parent) from its value. A subfeature's | |
| parent can never be another subfeature. Thus, features and their | |
| subfeatures form a two-level hierarchy.</p> | |
| <p>A <span class="emphasis"><em>value-string</em></span> for a feature <span class="bold"><strong>F</strong></span> is a string of | |
| the form | |
| <code class="literal">value-subvalue1-subvalue2</code>...<code class="literal">-subvalueN</code>, where | |
| <code class="literal">value</code> is a legal value for <span class="bold"><strong>F</strong></span> and | |
| <code class="literal">subvalue1</code>...<code class="literal">subvalueN</code> are legal values of some | |
| of <span class="bold"><strong>F</strong></span>'s subfeatures. For example, the properties | |
| <code class="literal"><toolset>gcc <toolset-version>3.0.1</code> can be | |
| expressed more conscisely using a value-string, as | |
| <code class="literal"><toolset>gcc-3.0.1</code>.</p> | |
| <p>A <span class="emphasis"><em>property set</em></span> is a set of properties (i.e. a | |
| collection without duplicates), for instance: | |
| <code class="literal"><toolset>gcc <runtime-link>static</code>.</p> | |
| <p>A <span class="emphasis"><em>property path</em></span> is a property set whose elements have | |
| been joined into a single string separated by slashes. A property | |
| path representation of the previous example would be | |
| <code class="literal"><toolset>gcc/<runtime-link>static</code>.</p> | |
| <p>A <span class="emphasis"><em>build specification</em></span> is a property set that fully | |
| describes the set of features used to build a target.</p> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h5 class="title"> | |
| <a name="bbv2.reference.features.validity"></a>Property Validity</h5></div></div></div> | |
| <p> | |
| For <a class="link" href="reference.html#bbv2.reference.features.attributes.free">free</a> | |
| features, all values are valid. For all other features, | |
| the valid values are explicitly specified, and the build | |
| system will report an error for the use of an invalid | |
| feature-value. Subproperty validity may be restricted so | |
| that certain values are valid only in the presence of | |
| certain other subproperties. For example, it is possible | |
| to specify that the <code class="computeroutput"><gcc-target>mingw</code> | |
| property is only valid in the presence of | |
| <code class="computeroutput"><gcc-version>2.95.2</code>. | |
| </p> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h5 class="title"> | |
| <a name="bbv2.reference.features.attributes"></a>Feature Attributes</h5></div></div></div> | |
| <p>Each feature has a collection of zero or more of the following | |
| attributes. Feature attributes are low-level descriptions of how the | |
| build system should interpret a feature's values when they appear in | |
| a build request. We also refer to the attributes of properties, so | |
| that an <span class="emphasis"><em>incidental</em></span> property, for example, is | |
| one whose feature has the <span class="emphasis"><em>incidental</em></span> | |
| attribute.</p> | |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | |
| <li class="listitem"> | |
| <p><span class="emphasis"><em>incidental</em></span></p> | |
| <p>Incidental features are assumed not to affect build | |
| products at all. As a consequence, the build system may use | |
| the same file for targets whose build specification differs | |
| only in incidental features. A feature that controls a | |
| compiler's warning level is one example of a likely | |
| incidental feature.</p> | |
| <p>Non-incidental features are assumed to affect build | |
| products, so the files for targets whose build specification | |
| differs in non-incidental features are placed in different | |
| directories as described in "target paths" below. [ where? ] | |
| </p> | |
| </li> | |
| <li class="listitem"> | |
| <p> | |
| <a name="bbv2.reference.features.attributes.propagated"></a> | |
| <span class="emphasis"><em>propagated</em></span> | |
| </p> | |
| <p>Features of this kind are | |
| propagated to dependencies. That is, if a <a class="link" href="overview.html#bbv2.overview.targets.main">main target</a> is built using a | |
| propagated | |
| property, the build systems attempts to use the same property | |
| when building any of its dependencies as part of that main | |
| target. For instance, when an optimized exectuable is | |
| requested, one usually wants it to be linked with optimized | |
| libraries. Thus, the <code class="literal"><optimization></code> feature is | |
| propagated.</p> | |
| </li> | |
| <li class="listitem"> | |
| <p> | |
| <a name="bbv2.reference.features.attributes.free"></a> | |
| <span class="emphasis"><em>free</em></span> | |
| </p> | |
| <p>Most features have a finite set of allowed values, and can | |
| only take on a single value from that set in a given build | |
| specification. Free features, on the other hand, can have | |
| several values at a time and each value can be an arbitrary | |
| string. For example, it is possible to have several | |
| preprocessor symbols defined simultaneously:</p> | |
| <pre class="programlisting"> | |
| <define>NDEBUG=1 <define>HAS_CONFIG_H=1 | |
| </pre> | |
| </li> | |
| <li class="listitem"> | |
| <p><span class="emphasis"><em>optional</em></span></p> | |
| <p>An optional feature is a feature that is not required to | |
| appear in a build specification. Every non-optional non-free | |
| feature has a default value that is used when a value for | |
| the feature is not otherwise specified, either in a target's | |
| requirements or in the user's build request. [A feature's | |
| default value is given by the first value listed in the | |
| feature's declaration. -- move this elsewhere - dwa]</p> | |
| </li> | |
| <li class="listitem"> | |
| <p><span class="emphasis"><em>symmetric</em></span></p> | |
| <p>A symmetric feature's default value is not automatically | |
| included in <a class="link" href="reference.html#bbv2.reference.variants" title="Build Variants">build variants</a>. Normally | |
| a feature only generates a subvariant directory when its | |
| value differs from the value specified by the build variant, | |
| leading to an assymmetric subvariant directory structure for | |
| certain values of the feature. A symmetric feature, when | |
| relevant to the toolset, always generates a corresponding | |
| subvariant directory.</p> | |
| </li> | |
| <li class="listitem"> | |
| <p><span class="emphasis"><em>path</em></span></p> | |
| <p>The value of a path feature specifies a path. The path is | |
| treated as relative to the directory of Jamfile where path | |
| feature is used and is translated appropriately by the build | |
| system when the build is invoked from a different | |
| directory</p> | |
| </li> | |
| <li class="listitem"> | |
| <p><span class="emphasis"><em>implicit</em></span></p> | |
| <p>Values of implicit features alone identify the feature. | |
| For example, a user is not required to write | |
| "<toolset>gcc", but can simply write "gcc". Implicit | |
| feature names also don't appear in variant paths, although | |
| the values do. Thus: bin/gcc/... as opposed to | |
| bin/toolset-gcc/.... There should typically be only a few | |
| such features, to avoid possible name clashes.</p> | |
| </li> | |
| <li class="listitem"> | |
| <p><span class="emphasis"><em>composite</em></span></p> | |
| <p>Composite features actually correspond to groups of | |
| properties. For example, a build variant is a composite | |
| feature. When generating targets from a set of build | |
| properties, composite features are recursively expanded and | |
| <span class="emphasis"><em>added</em></span> to the build property set, so rules can find | |
| them if necessary. Non-composite non-free features override | |
| components of composite features in a build property set.</p> | |
| </li> | |
| <li class="listitem"> | |
| <p><span class="emphasis"><em>dependency</em></span></p> | |
| <p>The value of a dependency feature is a target reference. | |
| When used for building of a main target, the value of | |
| dependency feature is treated as additional dependency.</p> | |
| <p>For example, dependency features allow to state that | |
| library A depends on library B. As the result, whenever an | |
| application will link to A, it will also link to B. | |
| Specifying B as dependency of A is different from adding B to | |
| the sources of A. </p> | |
| </li> | |
| </ul></div> | |
| <p>Features that are neither free nor incidental are called | |
| <span class="emphasis"><em>base</em></span> features.</p> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h5 class="title"> | |
| <a name="bbv2.reference.features.declaration"></a>Feature Declaration</h5></div></div></div> | |
| <p>The low-level feature declaration interface is the | |
| <code class="literal">feature</code> rule from the | |
| <code class="literal">feature</code> module: | |
| </p> | |
| <pre class="programlisting"> | |
| rule feature ( name : allowed-values * : attributes * ) | |
| </pre> | |
| <p> | |
| A feature's allowed-values may be extended with the | |
| <code class="computeroutput">feature.extend</code> rule. | |
| </p> | |
| </div> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h4 class="title"> | |
| <a name="bbv2.reference.variants"></a>Build Variants</h4></div></div></div> | |
| <p> | |
| A build variant, or (simply variant) is a special kind of composite | |
| feature that automatically incorporates the default values of | |
| features that . Typically you'll want at least two separate | |
| variants: one for debugging, and one for your release code. [ | |
| Volodya says: "Yea, we'd need to mention that it's a composite | |
| feature and describe how they are declared, in pacticular that | |
| default values of non-optional features are incorporated into | |
| build variant automagically. Also, do we wan't some variant | |
| inheritance/extension/templates. I don't remember how it works in | |
| V1, so can't document this for V2.". Will clean up soon -DWA ] | |
| </p> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h4 class="title"> | |
| <a name="bbv2.reference.variants.proprefine"></a>Property refinement</h4></div></div></div> | |
| <p>When a target with certain properties is requested, and that | |
| target requires some set of properties, it is needed to find the | |
| set of properties to use for building. This process is called | |
| <span class="emphasis"><em>property refinement</em></span> and is performed by these rules</p> | |
| <div class="orderedlist"><ol class="orderedlist" type="1"> | |
| <li class="listitem"> | |
| Each property in the required set is added to the original | |
| property set | |
| </li> | |
| <li class="listitem"> | |
| If the original property set includes property with a different | |
| value of non free feature, that property is removed. | |
| </li> | |
| </ol></div> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h4 class="title"> | |
| <a name="bbv2.reference.variants.propcond"></a>Conditional properties</h4></div></div></div> | |
| <p>Sometime it's desirable to apply certain requirements only for | |
| a specific combination of other properties. For example, one of | |
| compilers that you use issues a pointless warning that you want to | |
| suppress by passing a command line option to it. You would not | |
| want to pass that option to other compilers. Conditional | |
| properties allow you to do just that. Their syntax is:</p> | |
| <pre class="programlisting"> | |
| property ( "," property ) * ":" property | |
| </pre> | |
| <p> | |
| For example, the problem above would be solved by: | |
| </p> | |
| <pre class="programlisting"> | |
| exe hello : hello.cpp : <toolset>yfc:<cxxflags>-disable-pointless-warning ; | |
| </pre> | |
| <p> | |
| </p> | |
| <p>The syntax also allows several properties in the condition, for | |
| example: | |
| </p> | |
| <pre class="programlisting"> | |
| exe hello : hello.cpp : <os>NT,<toolset>gcc:<link>static ; | |
| </pre> | |
| <p> | |
| </p> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h4 class="title"> | |
| <a name="bbv2.reference.ids"></a>Target identifiers and references</h4></div></div></div> | |
| <p><span class="emphasis"><em>Target identifier</em></span> is used to denote a | |
| target. The syntax is:</p> | |
| <pre class="programlisting"> | |
| target-id -> (project-id | target-name | file-name ) | |
| | (project-id | directory-name) "//" target-name | |
| project-id -> path | |
| target-name -> path | |
| file-name -> path | |
| directory-name -> path | |
| </pre> | |
| <p> | |
| This grammar allows some elements to be recognized as either | |
| </p> | |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | |
| <li class="listitem"> | |
| project id (at this point, all project ids start with slash). | |
| </li> | |
| <li class="listitem"> | |
| name of target declared in current Jamfile (note that target | |
| names may include slash). | |
| </li> | |
| <li class="listitem"> | |
| a regular file, denoted by absolute name or name relative to | |
| project's sources location. | |
| </li> | |
| </ul></div> | |
| <p> | |
| To determine the real meaning a check is made if project-id | |
| by the specified name exists, and then if main target of that | |
| name exists. For example, valid target ids might be: | |
| </p> | |
| <pre class="screen"> | |
| a -- target in current project | |
| lib/b.cpp -- regular file | |
| /boost/thread -- project "/boost/thread" | |
| /home/ghost/build/lr_library//parser -- target in specific project | |
| </pre> | |
| <p> | |
| </p> | |
| <p><span class="bold"><strong>Rationale:</strong></span>Target is separated from project by special | |
| separator (not just slash), because:</p> | |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | |
| <li class="listitem"> | |
| It emphasises that projects and targets are different things. | |
| </li> | |
| <li class="listitem"> | |
| It allows to have main target names with slashes. | |
| </li> | |
| </ul></div> | |
| <p><a name="bbv2.reference.targets.references"></a> | |
| <span class="emphasis"><em>Target reference</em></span> is used to | |
| specify a source target, and may additionally specify desired | |
| properties for that target. It has this syntax:</p> | |
| <pre class="programlisting"> | |
| target-reference -> target-id [ "/" requested-properties ] | |
| requested-properties -> property-path | |
| </pre> | |
| <p> | |
| For example, | |
| </p> | |
| <pre class="programlisting"> | |
| exe compiler : compiler.cpp libs/cmdline/<optimization>space ; | |
| </pre> | |
| <p> | |
| would cause the version of <code class="literal">cmdline</code> library, | |
| optimized for space, to be linked in even if the | |
| <code class="literal">compiler</code> executable is build with optimization for | |
| speed. | |
| </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="tasks.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="extender.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> | |
| </div> | |
| </body> | |
| </html> |