Reference

General information

Initialization

Immediately upon starting, the B2 engine (b2) loads the Jam code that implements the build system. To do this, it searches for the build system bootstrap.jam file in specific installation locations. The search is based on the location of the b2(.exe) executable location.

The default bootstrap.jam, after loading some standard definitions, loads both site-config.jam and user-config.jam.

Note

To maintain backward compatibility the file called boost-build.jam, is loaded if present. The search starts 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. On Unix BOOST_BUILD_PATH defaults to /usr/share/b2.

Builtin rules

This section contains the list of all rules that can be used in Jamfile — both rules that define new targets and auxiliary rules.

exe

Creates an executable file. See the section called “Programs”.

lib

Creates an library file. See the section called “Libraries”.

install

Installs built targets and other files. See the section called “Installing”.

alias

Creates an alias for other targets. See the section called “Alias”.

unit-test

Creates an executable that will be automatically run. See the section called “Testing”.

compile; compile-fail; link; link-fail; run; run-fail

Specialized rules for testing. See the section called “Testing”.

check-target-builds

The check-target-builds allows you to conditionally use different properties depending on whether some metatarget builds, or not. This is similar to functionality of configure script in autotools projects. The function signature is:

rule check-target-builds ( target message ? : true-properties * : false-properties * )

This function can only be used when passing requirements or usage requirements to a metatarget rule. For example, to make an application link to a library if it’s available, one has use the following:

exe app : app.cpp : [ check-target-builds has_foo "System has foo" : <library>foo : <define>FOO_MISSING=1 ] ;

For another example, the alias rule can be used to consolidate configuration choices and make them available to other metatargets, like so:

alias foobar : : : : [ check-target-builds has_foo "System has foo" : <library>foo : <library>bar ] ;

obj

Creates an object file. Useful when a single source file must be compiled with special properties.

preprocessed

Creates an preprocessed source file. The arguments follow the common syntax.

glob

The glob rule takes a list shell pattern and returns the list of files in the project’s source directory that match the pattern. For example:

lib tools : [ glob *.cpp ] ;

It is possible to also pass a second argument—the list of exclude patterns. The result will then include the list of files matching any of include patterns, and not matching any of the exclude patterns. For example:

lib tools : [ glob *.cpp : file_to_exclude.cpp bad*.cpp ] ;

glob-tree

The glob-tree is similar to the glob except that it operates recursively from the directory of the containing Jamfile. For example:

ECHO [ glob-tree *.cpp : .svn ] ;

will print the names of all C++ files in your project. The .svn exclude pattern prevents the glob-tree rule from entering administrative directories of the Subversion version control system.

project

Declares project id and attributes, including project requirements. See the section called “Projects”.

use-project

Assigns a symbolic project ID to a project at a given path. This rule must be better documented!

explicit

The explicit 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.

always

The always function takes a single parameter—a list of metatarget names. The targets produced by the named metatargets will be always considered out of date. Consider this example:

exe hello : hello.cpp ;
exe bye : bye.cpp ;
always hello ;

If a build of hello is requested, then it will always be recompiled. Note that if a build of hello is not requested, for example you specify just bye on the command line, hello will not be recompiled.

constant

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:

constant VERSION : 1.34.0 ;

path-constant

Same as constant except that the value is treated as path relative to Jamfile location. For example, if b2 is invoked in the current directory, and Jamfile in helper subdirectory has:

path-constant DATA : data/a.txt ;

then the variable DATA will be set to helper/data/a.txt, and if b2 is invoked from the helper directory, then the variable DATA will be set to data/a.txt.

build-project

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.

test-suite

This rule is deprecated and equivalent to alias.

import-search

Jam	`rule import-search ( reference )`

Adds the given reference path to the set of directories that an import will search. The reference can be a plain directory or a known project path. If a project path is given it will be searched for and resolved to include any sub-project path in the reference. If a directory is given it will be rooted relative to the current project location. Example project path usage:

import-search /boost/config/checks ;
import-search /boost/predef/tools/checks ;

../../src/engine/mod_jam_builtin.h

Builtin features

This section documents the features that are built-in into B2. For features with a fixed set of values, that set is provided, with the default value listed first.

Builtin tools

B2 comes with support for a large number of C++ compilers, and other tools. This section documents how to use those tools.

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 using rule, typically in your user-config.jam, for example:

using gcc ;

additional parameters can be passed just like for other rules, for example:

using gcc : 4.0 : g++-4.0 ;

The options that can be passed to each tool are documented in the subsequent sections.

C++ Compilers

This section lists all B2 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 toolset feature that can be used to explicitly request that compiler.

../../src/tools/acc.jam ../../src/tools/borland.jam ../../src/tools/clang-linux.jam ../../src/tools/clang-win.jam ../../src/tools/como.jam ../../src/tools/cw.jam ../../src/tools/dmc.jam ../../src/tools/embarcadero.jam ../../src/tools/emscripten.jam ../../src/tools/gcc.jam ../../src/tools/hp_cxx.jam ../../src/tools/intel.jam ../../src/tools/msvc.jam ../../src/tools/sun.jam ../../src/tools/vacpp.jam :leveloffset: -3

Third-party libraries

B2 provides special support for some third-party C++ libraries, documented below.

STLport library

The STLport library is an alternative implementation of C++ runtime library. B2 supports using that library on Windows platform. Linux is hampered by different naming of libraries in each STLport version and is not officially supported.

Before using STLport, you need to configure it in user-config.jam using the following syntax:

using stlport : version : header-path : library-path ;

Where version is the version of STLport, for example 5.1.4, headers is the location where STLport headers can be found, and libraries 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.

When STLport is configured, you can build with STLport by requesting stdlib=stlport on the command line.

zlib

Provides support for the zlib library. zlib can be configured either to use precompiled binaries or to build the library from source.

zlib can be initialized using the following syntax

using zlib : version : options : condition : is-default ;

Options for using a prebuilt library:

search: The directory containing the zlib binaries.
name: Overrides the default library name.
include: The directory containing the zlib headers.

If none of these options is specified, then the environmental variables ZLIB_LIBRARY_PATH, ZLIB_NAME, and ZLIB_INCLUDE will be used instead.

Options for building zlib from source:

source: The zlib source directory. Defaults to the environmental variable ZLIB_SOURCE.
tag: Sets the tag property to adjust the file name of the library. Ignored when using precompiled binaries.
build-name: The base name to use for the compiled library. Ignored when using precompiled binaries.

Examples:

# Find zlib in the default system location
using zlib ;
# Build zlib from source
using zlib : 1.2.7 : <source>/home/steven/zlib-1.2.7 ;
# Find zlib in /usr/local
using zlib : 1.2.7 : <include>/usr/local/include <search>/usr/local/lib ;
# Build zlib from source for msvc and find
# prebuilt binaries for gcc.
using zlib : 1.2.7 : <source>C:/Devel/src/zlib-1.2.7 : <toolset>msvc ;
using zlib : 1.2.7 : : <toolset>gcc ;

bzip2

Provides support for the bzip2 library. bzip2 can be configured either to use precompiled binaries or to build the library from source.

bzip2 can be initialized using the following syntax

using bzip2 : version : options : condition : is-default ;

Options for using a prebuilt library:

search: The directory containing the bzip2 binaries.
name: Overrides the default library name.
include: The directory containing the bzip2 headers.

If none of these options is specified, then the environmental variables BZIP2_LIBRARY_PATH, BZIP2_NAME, and BZIP2_INCLUDE will be used instead.

Options for building bzip2 from source:

source: The bzip2 source directory. Defaults to the environmental variable BZIP2_SOURCE.
tag: Sets the tag property to adjust the file name of the library. Ignored when using precompiled binaries.
build-name: The base name to use for the compiled library. Ignored when using precompiled binaries.

Examples:

# Find bzip in the default system location
using bzip2 ;
# Build bzip from source
using bzip2 : 1.0.6 : <source>/home/sergey/src/bzip2-1.0.6 ;
# Find bzip in /usr/local
using bzip2 : 1.0.6 : <include>/usr/local/include <search>/usr/local/lib ;
# Build bzip from source for msvc and find
# prebuilt binaries for gcc.
using bzip2 : 1.0.6 : <source>C:/Devel/src/bzip2-1.0.6 : <toolset>msvc ;
using bzip2 : 1.0.6 : : <toolset>gcc ;

Python

Provides support for the python language environment to be linked in as a library.

python can be initialized using the following syntax

using python : [version] : [command-or-prefix] : [includes] : [libraries] : [conditions] : [extension-suffix] ;

Options for using python:

version: The version of Python to use. Should be in Major.Minor format, for example 2.3. Do not include the sub-minor version.
command-or-prefix: Preferably, a command that invokes a Python interpreter. Alternatively, the installation prefix for Python libraries and includes. If empty, will be guessed from the version, the platform’s installation patterns, and the python executables that can be found in PATH.
includes: the include path to Python headers. If empty, will be guessed.
libraries: the path to Python library binaries. If empty, will be guessed. On MacOS/Darwin, you can also pass the path of the Python framework.
conditions: if specified, should be a set of properties that are matched against the build configuration when B2 selects a Python configuration to use.
extension-suffix: A string to append to the name of extension modules before the true filename extension. Ordinarily we would just compute this based on the value of the <python-debugging> feature. However ubuntu’s python-dbg package uses the windows convention of appending _d to debug-build extension modules. We have no way of detecting ubuntu, or of probing python for the "_d" requirement, and if you configure and build python using --with-pydebug, you’ll be using the standard *nix convention. Defaults to "" (or "_d" when targeting windows and <python-debugging> is set).

Examples:

# Find python in the default system location
using python ;
# 2.7
using python : 2.7 ;
# 3.5
using python : 3.5 ;

# On ubuntu 16.04
using python
: 2.7 # version
: # Interpreter/path to dir
: /usr/include/python2.7 # includes
: /usr/lib/x86_64-linux-gnu # libs
: # conditions
;

using python
: 3.5 # version
: # Interpreter/path to dir
: /usr/include/python3.5 # includes
: /usr/lib/x86_64-linux-gnu # libs
: # conditions
;

# On windows
using python
: 2.7 # version
: C:\\Python27-32\\python.exe # Interperter/path to dir
: C:\\Python27-32\\include # includes
: C:\\Python27-32\\libs # libs
: <address-model>32 <address-model> # conditions - both 32 and unspecified
;

using python
: 2.7 # version
: C:\\Python27-64\\python.exe # Interperter/path to dir
: C:\\Python27-64\\include # includes
: C:\\Python27-64\\libs # libs
: <address-model>64 # conditions
;

Documentation tools

B2 support for the Boost documentation tools is documented below.

xsltproc

To use xsltproc, you first need to configure it using the following syntax:

using xsltproc : xsltproc ;

Where xsltproc is the xsltproc executable. If xsltproc is not specified, and the variable XSLTPROC is set, the value of XSLTPROC will be used. Otherwise, xsltproc will be searched for in PATH.

The following options can be provided, using `<option-name>option-value syntax`:

xsl:param: Values should have the form name=value
xsl:path: Sets an additional search path for xi:include elements.
catalog: A catalog file used to rewrite remote URL’s to a local copy.

The xsltproc module provides the following rules. Note that these operate on jam targets and are intended to be used by another toolset, such as boostbook, rather than directly by users.

xslt

rule xslt ( target : source stylesheet : properties * )

Runs xsltproc to create a single output file.

xslt-dir

rule xslt-dir ( target : source stylesheet : properties * : dirname )

Runs xsltproc to create multiple outputs in a directory. dirname is unused, but exists for historical reasons. The output directory is determined from the target.

boostbook

To use boostbook, you first need to configure it using the following syntax:

using boostbook : docbook-xsl-dir : docbook-dtd-dir : boostbook-dir ;

docbook-xsl-dir is the DocBook XSL stylesheet directory. If not provided, we use DOCBOOK_XSL_DIR from the environment (if available) or look in standard locations. Otherwise, we let the XML processor load the stylesheets remotely.

docbook-dtd-dir is the DocBook DTD directory. If not provided, we use DOCBOOK_DTD_DIR From the environment (if available) or look in standard locations. Otherwise, we let the XML processor load the DTD remotely.

boostbook-dir is the BoostBook directory with the DTD and XSL sub-dirs.

The boostbook module depends on xsltproc. For pdf or ps output, it also depends on fop.

The following options can be provided, using `<option-name>option-value syntax`:

format: Allowed values: html, xhtml, htmlhelp, onehtml, man, pdf, ps, docbook, fo, tests.

The format feature determines the type of output produced by the boostbook rule.

The boostbook module defines a rule for creating a target following the common syntax.

boostbook

rule boostbook ( target-name : sources * : requirements * : default-build * )

Creates a boostbook target.

doxygen

To use doxygen, you first need to configure it using the following syntax:

using doxygen : name ;

name is the doxygen command. If it is not specified, it will be found in the PATH.

The doxygen module depends on the boostbook module when generating BoostBook XML.

The following options can be provided, using `<option-name>option-value syntax`:

doxygen:param

All the values of doxygen:param are added to the doxyfile.

prefix

Specifies the common prefix of all headers when generating BoostBook XML. Everything before this will be stripped off.

reftitle

Specifies the title of the library-reference section, when generating BoostBook XML.

doxygen:xml-imagedir

When generating BoostBook XML, specifies the directory in which to place the images generated from LaTex formulae.

Warning

The path is interpreted relative to the current working directory, not relative to the Jamfile. This is necessary to match the behavior of BoostBook.

The doxygen module defines a rule for creating a target following the common syntax.

doxygen

rule doxygen ( target : sources * : requirements * : default-build * : usage-requirements * )

Creates a doxygen target. If the target name ends with .html, then this will generate an html directory. Otherwise it will generate BoostBook XML.

quickbook

The quickbook module provides a generator to convert from Quickbook to BoostBook XML.

To use quickbook, you first need to configure it using the following syntax:

using quickbook : command ;

command is the quickbook executable. If it is not specified, B2 will compile it from source. If it is unable to find the source it will search for a quickbook executable in PATH.

fop

The fop module provides generators to convert from XSL formatting objects to Postscript and PDF.

To use fop, you first need to configure it using the following syntax:

using fop : fop-command : java-home : java ;

fop-command is the command to run fop. If it is not specified, B2 will search for it in PATH and FOP_HOME.

Either java-home or java can be used to specify where to find java.

Builtin modules

This section describes the modules that are provided by B2. The import rule allows rules from one module to be used in another module or Jamfile.

../../src/engine/mod_jam_modules.h ../../src/engine/mod_jam_class.h ../../src/engine/mod_jam_errors.h ../../src/engine/mod_regex.h ../../src/engine/mod_set.h ../../src/engine/mod_string.h ../../src/engine/mod_version.h ../../src/engine/mod_db.h

path.adoc

sequence.adoc

../../src/tools/stage.jam

type.adoc

Builtin classes

Build process

The general overview of the build process was given in the user documentation. This section provides additional details, and some specific rules.

To recap, building a target with specific properties includes the following steps:

applying the default build,
selecting the main target alternative to use,
determining the "common" properties,
building targets referred by the the sources list and dependency properties,
adding the usage requirements produced when building dependencies to the "common" properties,
building the target using generators,
computing the usage requirements to be returned.

Alternative selection

When a target has several alternatives, one of them must be selected. The process is as follows:

For each alternative, its condition is defined as the set of base properties in its requirements. Conditional properties are excluded.
An alternative is viable only if all properties in its condition are present in the build request.
If there’s only one viable alternative, it’s chosen. Otherwise, an attempt is made to find the best alternative. An alternative a is better than another alternative b, if the set of properties in b’s condition is a strict subset of the set of properties of a’s condition. If one viable alternative is better than all the others, it’s selected. Otherwise, an error is reported.

Determining common properties

"Common" properties is a somewhat artificial term. This is the intermediate property set from which both the build request for dependencies and the properties for building the target are derived.

Since the default build and alternatives are already handled, we have only two inputs: the build request and the requirements. Here are the rules about common properties.

Non-free features can have only one value
A non-conditional property in the requirements is always present in common properties.
A property in the build request is present in common properties, unless it is overridden by a property in the requirements.
If either the build request, or the requirements (non-conditional or conditional) include an expandable property (either composite, or with a specified sub-feature value), the behavior is equivalent to explicitly adding all the expanded properties to the build request or the requirements respectively.
If the requirements include a conditional property, and the condition of this property is true in the context of common properties, then the conditional property should be in common properties as well.
If no value for a feature is given by other rules here, it has default value in common properties.

These 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 a property in the build request, by non-conditional requirements, or even by another conditional property. For example, the following example works as expected:

exe a : a.cpp
      : <toolset>gcc:<variant>release
        <variant>release:<define>FOO ;

Target Paths

Several factors determine the location of a concrete file target. All files in a project are built under the directory bin unless this is overridden by the build-dir project attribute. Under bin is a path that depends on the properties used to build each target. This path is uniquely determined by all non-free, non-incidental properties. For example, given a property set containing: <toolset>gcc <toolset-gcc:version>4.6.1 <variant>debug <warnings>all <define>_DEBUG <include>/usr/local/include <link>static, the path will be gcc-4.6.1/debug/link-static. <warnings> is an incidental feature and <define> and <include> are free features, so they do not affect the path.

Sometimes the paths produced by B2 can become excessively long. There are a couple of command line options that can help with this. --abbreviate-paths reduces each element to no more than five characters. For example, link-static becomes lnk-sttc. The --hash option reduces the path to a single directory using an MD5 hash.

There are two features that affect the build directory. The <location> feature completely overrides the default build directory. For example,

exe a : a.cpp : <location>. ;

builds all the files produced by a in the directory of the Jamfile. This is generally discouraged, as it precludes variant builds.

The <location-prefix> feature adds a prefix to the path, under the project’s build directory. For example,

exe a : a.cpp : <location-prefix>subdir ;

will create the files for a in bin/subdir/gcc-4.6.1/debug

Definitions

Features and properties

A feature is a normalized (toolset-independent) aspect of a build configuration, such as whether inlining is enabled. Feature names may not contain the ‘>’ character.

Each feature in a build configuration has one or more associated values. Feature values for non-free features may not contain the punctuation characters of pointy bracket (‘<’), colon (‘:’ ), equal sign (‘=’) and dashes (‘-’). Feature values for free features may not contain the pointy bracket (‘<’) character.

A property is a (feature,value) pair, expressed as <feature>value.

A subfeature 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.

A value-string for a feature F is a string of the form value-subvalue1-subvalue2…-subvalueN, where value is a legal value for F and subvalue1…subvalueN are legal values of some of F's subfeatures separated with dashes (‘-’). For example, the properties <toolset>gcc <toolset-version>3.0.1 can be expressed more concisely using a value-string, as <toolset>gcc-3.0.1.

A property set is a set of properties (i.e. a collection without duplicates), for instance: <toolset>gcc <runtime-link>static.

A property path 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 <toolset>gcc/<runtime-link>static.

A build specification is a property set that fully describes the set of features used to build a target.

Property Validity

For free 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 <gcc-target>mingw property is only valid in the presence of <gcc-version>2.95.2.

Feature Attributes

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 incidental property, for example, is one whose feature has the incidental attribute.

incidental

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.

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.
propagated

Features of this kind are propagated to dependencies. That is, if a main target 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 executable is requested, one usually wants it to be linked with optimized libraries. Thus, the <optimization> feature is propagated.
free

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:
```
<define>NDEBUG=1 <define>HAS_CONFIG_H=1
```
optional

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]
symmetric

Normally a feature only generates a sub-variant directory when its value differs from its default value, leading to an asymmetric sub-variant directory structure for certain values of the feature. A symmetric feature always generates a corresponding sub-variant directory.
path

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
implicit

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.
composite

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 added 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.
dependency

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.

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.

Features that are neither free nor incidental are called base features.

Feature Declaration

The low-level feature declaration interface is the feature rule from the feature module:

rule feature ( name : allowed-values * : attributes * )

A feature’s allowed-values may be extended with the feature.extend rule.

Property refinement

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 property refinement and is performed by these rules

Each property in the required set is added to the original property set
If the original property set includes property with a different value of non free feature, that property is removed.

Conditional properties

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:

property ( "," property ) * ":" property

For example, the problem above would be solved by:

exe hello : hello.cpp : <toolset>yfc:<cxxflags>-disable-pointless-warning ;

The syntax also allows several properties in the condition, for example:

exe hello : hello.cpp : <os>NT,<toolset>gcc:<link>static ;

Target identifiers and references

Target identifier is used to denote a target. The syntax is:

target-id -> (target-name | file-name | project-id | directory-name)
              | (project-id | directory-name) "//" target-name
project-id -> path
target-name -> path
file-name -> path
directory-name -> path

This grammar allows some elements to be recognized as either

name of target declared in current Jamfile (note that target names may include slash).
a regular file, denoted by absolute name or name relative to project’s sources location.
project id (at this point, all project ids start with slash).
the directory of another project, denoted by absolute name or name relative to the current project’s location.

To determine the real meaning the possible interpretations are checked in this order. For example, valid target ids might be:

`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
`../boost_1_61_0`	project in specific directory

Rationale:Target is separated from project by special separator (not just slash), because:

It emphasis that projects and targets are different things.
It allows to have main target names with slashes.

Target reference is used to specify a source target, and may additionally specify desired properties for that target. It has this syntax:

target-reference -> target-id [ "/" requested-properties ]
requested-properties -> property-path

For example,

exe compiler : compiler.cpp libs/cmdline/<optimization>space ;

would cause the version of cmdline library, optimized for space, to be linked in even if the compiler executable is build with optimization for speed.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

reference.adoc

reference.adoc

Reference

General information

Initialization

Builtin rules

Builtin features

Builtin tools

C++ Compilers

Third-party libraries

Documentation tools

Builtin modules

Builtin classes

Build process

Alternative selection

Determining common properties

Target Paths

Definitions

Features and properties

Property Validity

Feature Attributes

Feature Declaration

Property refinement

Conditional properties

Target identifiers and references

Files

reference.adoc

Latest commit

History

reference.adoc

File metadata and controls

Reference

General information

Initialization

Builtin rules

Builtin features

Builtin tools

C++ Compilers

Third-party libraries

Documentation tools

Builtin modules

Builtin classes

Build process

Alternative selection

Determining common properties

Target Paths

Definitions

Features and properties

Property Validity

Feature Attributes

Feature Declaration

Property refinement

Conditional properties

Target identifiers and references