Boost Build System

Synopsis

Boost.Build is a system for large project software construction built on Boost.Jam, a descendant of "Perforce Jam", an open-source make replacement[1]. Key features are:

• A simple target description language
• Build with your choice (or multiple) toolsets from a single command invocation
• Build your choice of basic variants (e.g. debug, release, profile...) and subvariant modifications (e.g. inlining off) from a single command invocation
• ``Feature Normalization'' allows target configurations to be described independently from the toolset used
• Modular toolset description files allow build instructions for different toolsets to be described independently
• Multiple subproject support
• Automatic building of subproject dependencies

Status

Here are some of the design criteria that led to these features.

Table of Contents

• Synopsis
• Status
• Getting Started
  • Installing Boost.Jam
  • Initiating a Build
  • Setting Jam Variables
  • An Example Jamfile
  • Support Files
• Basic Design and Terminology
  • Projects and Subprojects
  • Targets
  • Features and Properties
  • Build Variants
  • Subvariants
  • Dependent Targets
• Usage
  • The Command-Line
    • User Targets
    • Global Variables
  • Subproject Jamfiles
    • The subproject Rule
    • Describing Main Targets
    • Describing Template Targets
    • Describing Stage Targets
    • Example
  • Using External Projects
  • Requirement Rules
  • Install Descriptions
  • Feature Descriptions
  • Variant Descriptions
  • Toolset Description Files
    • Example
• Internals
  • Target Names
  • Global Variables
• Design Criteria
  • Assumptions
  • Requirements
• Footnotes

Getting Started

Installing Boost.Jam

Initiating a Build

Boost.Build responds to several global variable settings. The easiest way to get going is usually to use environment variables, though you can also set them on the command-line, using -sVARIABLE_NAME=value. In addition to the toolset configuration variables, you can use the TOOLS variable to indicate which toolset(s) to build with, and the BUILD variable to describe how you want things built. In many cases it should be sufficient to invoke bjam with no variable settings.

Some example Boost.Jam invocations:

bjam -sTOOLS=gcc my_target

bjam "-sTOOLS=msvc gcc"

set TOOLS=msvc
bjam

bjam "-sBUILD=release <debug-symbols>on"

bjam "-sBUILD=debug release"

Setting Jam Variables

The "-s" options in the command lines above are passing variable settings to the build system. There are actually three ways to do that:

• Jam picks up variable settings from your environment by default, so you can set them there:

  > BUILD="debug release"  # assuming Unix
  > export BUILD
  > bjam ...
  

  This approach can be OK for quick-and-dirty tests, but environment variable settings tend to be unstable and non-uniform across users and machines, so it's best not to rely on the environment much.
• Explicitly on the command-line, with the "-s" option.
• Directly in Jam code. A project's Jamrules file is a convenient place to make global settings.

An Example Jamfile

subproject foo/bar/baz ; # path to here from project root

# A static library called 'baz'
lib baz : baz1.cpp baz2.cpp # C++ sources
          parser/src/baz4.ll # Lex->C++ sources
          parser/src/baz5.yy  # Yacc->C++ sources
        : <include>$(BOOST_PARENT_DIRECTORY)  # Put boost in #include path
    ;

# An executable called 'test'
exe test : <lib>baz # use the 'baz' library
           baz_test.cpp   # C++ source
         : <include>$(BOOST_ROOT)
    ;

That's it! The build system takes care of the rest. If the you want to be able to build all subprojects from the project root directory, you can add a Jamfile at the root:

project-root ; # declare this to be the project root directory
# Read subproject Jamfiles
subinclude foo/bar/baz foo/bar/... ;
subinclude a/b/c ... ; # more subincludes

Support Files

To use the build system, the following must be located in your project's root directory, or in a directory specified in the BOOST_BUILD_PATH variable. It is usually convenient to specify the BOOST_BUILD_PATH in your project's Jamrules file. The Boost Jamrules file shows an example.

Basic Design and Terminology

Projects and Subprojects

A project is a source directory tree containing at least one Jamfile. The root directory of the project is known as the project root. The root directory of a project may contain a Jamrules file, which contains project-specific Jam code. If the Jamrules file is not present when Jam is invoked, a warning will be issued.

Subdirectories containing Jamfiles are called subproject directories. Each such Jamfile describes a subproject.

The build system installation directory is a directory containing Jam files describing compilers and build variants. The installation directory can be specified in a file called boost-build.jam in the project root directory. This file should contain a line boost-build $path-to-installation-dir. If no such file is available the environment variable BOOST_BUILD_PATH will be used. This lists a set of directories to search for the files comprising the build system. If the installation directory is not specified, it is the same as the project root, and BOOST_BUILD_PATH is set to include that directory.

Targets

Each Jamfile describes one or more main targets.

Each main target is an abstract description of one or more built targets which are expressions of the corresponding main target under particular compilers and build variants. Intermediate files such as .o/.obj files generated by compiling .cpp files as a consequence of building a main target are also referred to as built targets. The term build directory tree refers to the location of built target files.

• By default, the build directory tree is overlaid with the project directory tree, with targets generated into a subtree rooted at the bin subdirectory of each subproject directory (the name of this directory can be customized by changing the BIN_DIRECTORY variable.
• If the variable ALL_LOCATE_TARGET is set, it specifies an alternate build directory tree whose structure mirrors that of the project. In this case, built targets of a subproject are generated into the corresponding directory of the build directory tree.

Features and Properties

A feature is a normalized (toolset-independent) description of an individual build parameter, such as whether inlining is enabled. Each feature usually corresponds to a command-line option of one or more build tools. Features come in four varieties:

1. Simple features can take on any of several predetermined values. For example, the feature optimization might take one of the values off, speed, or space. Simple features have a default value. The key aspect of simple features is that they are assumed to affect link compatibility: object files generated with different values for a simple feature are generated into a separate directories, and (with a few exceptions) main targets generated with different values won't be linked together.
2. Free features can either be single-valued, as above, or may take on any number of user-specified values simultaneously. For example, the define feature for a release build might have the values NDEBUG and BOOST_RELEASE_BUILD. Free features are assumed not to affect link compatibility.
3. Path features are free features whose values describe paths which may be relative to the subproject (such as linked libraries or #include search directories). The build system treats the values of these features specially to ensure that they are interpreted relative to the subproject directory regardless of the directory where Jam was invoked.
4. Dependency features are path features whose values describe a dependency of built targets. For example, an external library might be specified with a dependency-feature: if the library is updated, the target will be updated also. The <library-file> feature works this way [2].

A feature-value pair is known as a build property, or simply property. The prefixes simple, free, path, and dependency apply to properties in an analogous way to features.

Build Variants

A build variant, or simply variant is a named set of build properties describing how targets should be built. Typically you'll want at least two separate variants: one for debugging, and one for your release code.

Built targets for distinct build variants and toolsets are generated in separate parts of the build directory tree, known as the variant directories. For example, a (sub)project with main targets foo and bar, compiled with both GCC and KAI for debug and release variants might generate the following structure (target directories in bold).

 bin
 +-foo  <--- foo's build root
 | +-gcc
 | | +-debug
 | | `-release
 | `-kai
 |   +-debug
 |   `-release
 `-bar  <--- bar's build root
   +-gcc
   | +-debug
   | `-release
   `-kai
     +-debug
     `-release

The properties constituting a variant may differ according to toolset, so debug may mean a slightly different set of properties for two different compilers.

Subvariants

When a target is built with simple properties that don't exactly match those specified in a build variant, the non-matching features are called subvariant features and the target is located in a subvariant directory beneath the directory of the base variant. This can occur for two reasons:

1. Some features are only relevant to certain compilers. When relevant simple features have no value specified in the build variant, a value must be chosen. Even when the default value is used, the target is generated into a subvariant directory. For example, the runtime-link feature may be unspecified in the debug variant, but relevant to MSVC. In that case, a fragment of the target tree might look like:

    bin
    +-foo  <--- foo's build root
    | +-msvc
    | | +-debug
    . . . `-runtime-link-dynamic
    . . .
   

   Because the default value of runtime-link is dynamic, when the debug variant is requested, the runtime-link-dynamic subvariant of foo is built.
   
   
2. It is possible to request (either on the command-line, or as part of a main target description) that particular subvariants be built. For example, it may be desirable to generate builds that link to the runtime both statically and dynamically. In that case, both subvariant directories in the example above would be generated:

    bin
    +-foo  <--- foo's build root
    | +-msvc
    | | +-debug
    . . . +-runtime-link-dynamic
    . . . `-runtime-link-static
    . . .
   

When a subvariant includes multiple subvariant features, targets are built into a subvariant directory whose path is determined by concatenating the properties sorted in order of their feature names. For example, the borland compiler, which uses different libraries depending on whether the target is a console or GUI program, might create the following structure for a DLL:

 bin
 +-foo  <--- foo's build root
 | +-msvc
 | | +-debug
 | | | +-runtime-link-dynamic
 | | | | +-user-interface-console
 | | | | `-user-interface-gui
 . . . `-runtime-link-static
 . . .   +-user-interface-console
 . . .   `user-interface-gui

Any configuration of properties for which a target is built, whether base variant or subvariant, is known as a build configuration, or simply a build.

Dependent Targets

When a main target depends on the product of a second main target (as when an executable depends on and links to a static library), each build configuration of the dependent target is depends on the corresponding build of the dependency. Because only simple features participate in build identity, the dependent and dependency targets may have completely different free features. This puts the onus on the user for ensuring link-compatibility when certain free properties are used. For example, when assert() is used in header files, the preprocessor symbol NDEBUG can impact link-compatibility of separate compilation units. This danger can be minimized by encapsulating such feature differences inside of build variants.

Usage

This section describes how to start a build from the command-line and how to write project and subproject Jamfiles. It also describes the other files written in the Jam language: build-tool specification files, feature descriptions files.

The Command Line

This section describes in detail how the build system can be invoked.

User Targets

The Jam command line ends with an optional list of target names; if no target names are supplied, the built-in pseudotarget all is built. In a large project, naming targets can be dicey because of collisions. Jam uses a mechanism called grist to distinguish targets that would otherwise have the same name. Fortunately, you won't often have to supply grist at the command-line. When you declare a main target, a Jam pseudotarget of the same name is created which depends on all of the subvariants requested for your invocation of the build system. For example, if your subproject declares:

exe my_target : my_source1.cpp my_source2.c ;

These simple, ungristed names are called user targets, and are only available for the subproject where Jam is invoked. That way, builds from the top level (which may include many Jamfiles through the subinclude rule) and builds of library dependencies (which may live in other subprojects), don't collide. If it is necessary to refer more explicitly to a particular target from the command-line, you will have to add ``grist''. Please see this section for a more complete description of how to name particular targets in a build.

Global Variables

This is a partial list of global variables that can be set on the command-line. Of course you are free to write your own Jam rules which interpret other variables from the command-line. This list just details some of the variables used by the build system itself. Note also that if you don't like the default values you can override them in your project's Jamrules file.

SubProject Jamfiles

The subproject rule

A subproject's Jamfile begins with an invocation of the subproject rule that specifies the subproject's location relative to the top of the project tree:

subproject path-from-top ;

The subproject rule tells the build system where to place built targets from the subproject in case ALL_LOCATE_TARGET is used to specify the build directory tree. If there is a Jamfile in the project root directory, you should use the project-root rule instead:

project-root ;

Describing Main Targets

A main target is described using the following syntax:

target-type name : sources
    [ : requirements [ : default-BUILD ] ] ;

• target-type may be one of exe, lib, dll, stage or template. These are actually names of Jam rules. Additional main target rules are possible; see status/Jamfile or libs/python/build/Jamfile for examples.
  
  
• name specifies the name of the main target, multiple targets with the same name are allowed but only if they are of different types. Normally this is not the name of the final target file generated. The target file name depends on the type of target which controls how the base target name is renamed to conform to platform conventions. For exes the name might be the same or *.exe. For libs the name might be *.lib or lib*.a. And for dlls the name might be *.dll or lib*.so. For platform specific naming consult the allyourbase.jam file in the build system.
  
  
• sources is a list of paths to source files and dependency targets. The syntax for dependency targets is described by the following grammar:

  dependency-target -> type-tag location target-name
  
  type-tag -> "<template>" | "<lib>" | "<dll>" | "<exe>"
  
  location -> ( @project-id/ )? relative-path
  
  relative-path -> ( path-element/ ) *
  

  The location specifies the location of a Jamfile in which a dependency target called target-name can be found, declared with the given type-tag. Other type-tags are possible; for example the python.jam module defines Python extensions with the "<pyd>" tag. If @project-id is specified, the relative-path is interpreted with respect to the root directory of the specified project. Otherwise, it is interpreted with respect to the directory of the current Jamfile.

  The dependency's type-tag is also used to decide how to link to it when needed. <lib> targets are linked statically and <dll> targets are linked dynamically. On Unix platforms dynamic linking will use (the appropriate platform equivalent of) LD_LIBRARY_PATH and the "-l" linker flag to avoid creating executables which expect to find dynamic libraries in particular locations in the filesystem.

  NOTE: It is important to match the type-tag dependency with the type of the dependency target. Trying to specify a type-tag of <lib> when the target is defined as a <dll> will cause an error.

  
  
• requirements specifies the build properties intrinsic to the target. Requirements are given as sets of optionally-qualified build properties:

  [[<compiler>]<variant>]<feature>value
  

  <compiler> and <variant>, if supplied, can be used to restrict the applicability of the requirement. Either one may be replaced by <*>, which is the same as omitting it.

  The system checks that simple feature requirements are not violated by explicit subvariant build requests, and will issue a warning otherwise. Free features specified as requirements are simply added to each corresponding build configuration.

  
  
• default-BUILD specifies the configurations that should be built if the BUILD variable is not otherwise specified. Any elements not beginning with ``<...>'' refer to build variants. Other elements use the same syntax as the requirements described above, except that multiple values may be specified for a simple feature by separating them with a slash, forming (qualified) multi-valued properties:

  [[<compiler>]<variant>]<feature>value1[/value2...]
  

  When multiple values are specified, it causes all the implied configurations to be built by default. It is also possible to prevent any default builds from occurring on this target by using <suppress>true . This suppresses any local targets, either implicit or explicit, from building. But, this does not prevent implied targets as required by a dependency by another target to this one from being built. This is useful, for example, for defining a set of libraries generically and having them built only when another target like an exe is built. Such use might look like:

  lib basic : basic.cpp : : <suppress>true ;
  
  
  
  exe test : test.cpp <lib>basic ;
  

  With that the basic library will only be built when the test executable is built, and only the variations required by the executable will be built.
  

NOTE: for simple features in both requirements and default-BUILD, more-specific qualification overrides less-specific.

Describing Template Targets

Template targets provide a way to handle commonalities between projects targets. They have the same form as main targets but do not initiate build requests. A target that lists a template as a dependency inherits all the settings from the template, i.e. the templates sources, requirements and default build settings will be added to the targets settings. Paths mentioned in a template definition are always relative to the subdirectory of the Jamfile containing the templates definition, regardless of the subdirectory of the dependent main target. Typically a project will have at least one template target that handles defines, include paths and additional compiler flags common to all targets in the project.

Describing Stage Targets

Stage targets are a special kind of target that don't build a single file but to a collection of files. The goal is to create a directory which is composed of the various files that other targets generate, or individual files. When built a stage target creates a directory with the same name as the target, and copies the dependent files to it. The form of the target is the same as that of main targets with some differences...

• target-type is stage. See libs/regex/build/Jamfile for an example.
  
  
• Name specifies the name of the stage and is the name of the directory created.
  
  
• sources is the same as main targets and one can list both generated targets like <exe>test_exe and individual files, but not template targets.
  
  
• Requirements the build properties specified are used as with main targets. But one additional type of requirement is possible: <tag>... A tag specifies how to "augment" the names of the copied files. This is needed to distinguish the various files if you're collecting different builds of the same targets. The syntax is:

  <tag><feature|variant>value
  

  
  If the feature or variant is present for the a target the file for that target is renamed to include the given value between the basename and the suffix. Two special tags, <tag><prefix> and <tag><postfix>, let one prepend and append a value to the "augmentation" respectively.
  
  
• default-BUILD acts in the same manner as a main target.
  

Example

This artificially complex example shows how two executables called "foo" and "fop" might be described in a Jamfile. All common settings are factored out in the templates "base" and "executable". Foo is composed of the sources ./foo.cpp and ./src/bar.cpp (specified relative to the directory in which the Jamfile resides). Fop only has one sourcefile ./fop.cpp. Both executables link against the built target which results from building the target baz as described in ../bazlib/Jamfile.

template base : 
    ## Requirements ##
    : <include>../bazlib/include 
      <define>BUILDING_FOO=1
      <release><define>FOO_RELEASE
      <msvc><*><define>FOO_MSVC
      <msvc><release><define>FOO_MSVC_RELEASE
      <gcc><*><optimization>off
      <gcc><release><optimization>space
      <threading>multi
      <sysinclude>/usr/local/foolib/include
    
    ## default-BUILD ##
    : debug release
      <debug><runtime-link>static/dynamic
    ;

template executable : <template>base <lib>../bazlib/baz ;

exe foo : <template>executable foo.cpp src/bar.cpp ;

exe fop : <template>executable fop.cpp ;

The requirements section:

• Adds ../bazlib/include to the #include path
• Sets the preprocessor symbol BUILDING_FOO to 1
• In the release builds, #defines FOO_RELEASE.
• When built with MSVC, #defines FOO_MSVC.
• In release variants built with MSVC, #defines FOO_MSVC_RELEASE.
• Most builds under GCC have optimization turned off, but...
• ...GCC release builds require optimization for space.
• Requires multithread support on compilers where it's relevant.
• Adds /usr/local/foolib/include to the #include <*> path

The default-BUILD section:

• specifies that debug and release base variants are built by default.
• on compilers where the feature is relevant, requests both statically- and dynamically-linked subvariants of the debug variant.

Using External Projects

project boost : /home/dave/boost-cvs ;

<dll>@boost/libs/thread/build/boost_thread

Requirement Rules

Target requirements support the use of auxiliary rules to allow for more complex decisions about the requirements. If specified, by using the name of a rule in the requirements, the rule is called with the signature: ( toolset variant : subvariant-path properties * ) and should return the modified set of properties. There are a number of built-in rules for some common tasks that Boost uses, and you can use:

Rule	Effects
std::locale-support	Ensures that locale support is available for the target. For example some toolsets, like CodeWarrior, locale support is only available on specific platforms using a static runtime.
std::facet-support	Ensures that facet support is available for the target.
common-variant-tag	Adds a constructed prefix tag to the target to conform to the Boost common naming conventions for libraries. The tag is constructed as: [-<toolset-tag>][-<thread-tag>][-<runtime-tag>][-<version-tag>] <toolset-tag> maps to an abbreviated name of the toolset and when possible, and applicable, the version of the toolset. <thread-tag> "mt" when multi-threading is enabled. <runtime-tag> adds these single letter tags:   "s" when static linking to runtime   "g" when linking to debug runtime   "y" when building debug-python variants   "d" when building debug variants   "p" when building with stlport libraries   "n" when building with stlport and using native iostreams <version-tag> adds "major_minor" from a <version> property. Defaults to using $(BOOST_VERSION) if no version property is present.

Install Descriptions

Installable files and targets are described with:

install name type : sources... : [options]... ;

Install descriptions define files and targets that can be installed by use of a stage target.

• name specifies the name to group the given files and targets as a collective entity. Multiple install descriptions can use the same name, in which case they are all collected into a single group.
  
  
• type indicates the type of files specified by the install. This is used to later install files from different groups but with the same type.
  
  
• sources can list both generated targets like <exe>test_exe and individual files, but not template targets.
  
  
• options additional options, currently none defined.
  

Install descriptions are meant to be used by stage targets to collect the various sources of many install descriptions into one or more destination directories. For this there are two rules that help in getting the sources specified:

• install-subinclude jamfiles... : [options]...
  
  Includes the listed Jamfiles to read in the install descriptions. Multiple <exclude>name options can be used to exclude the named groups of install descriptions from getting defined.
  
  
• install-source type
  
  Returns the list of sources and targets specified by the install for the given type. The returned list can be used as the sources for a stage target which would place all the sources into that stage.
  
  

Feature Descriptions

Features are described by stating the feature type (simple features are specified with "feature"), followed by the feature name. An optional second argument can be used to list the permissible values of the feature. Examples can be found in features.jam.

Variant Descriptions

Variants are described with the following syntax:

variant name [ : parent-name] : [<toolset-name>]<feature>value... ;

variant my-globals : <rtti>off ;

variant my-debug : my-globals debug ;

variant my-release : my-globals release ;

Toolset Description Files

Toolset descriptions are located in the project's root directory, or a directory specified by BOOST_BUILD_INSTALLATION, which may be set in a Jamfile or the project's Jamrules file. Each file is called toolset-name-tools.jam, where toolset-name is the name of the toolset. The toolset description file has two main jobs:

1. redefine the following rules:
   • Link-action - links an executable from objects and libraries
   • Archive-action - links a static library from object files
   • C++-action - compiles a 'C++' file into an object file
   • Cc-action - compiles a 'C' file into an object file
   These rules should simply invoke the action part of a rule whose name is uniquely defined for the toolset. For example,

   rule C++-action
   {
       msvc-C++-action $(<) : $(>) ;
   }
   
   actions msvc-C++-action
   {
       cl -nologo -GX -c -U$(UNDEFS) -D$(DEFINES) $(CFLAGS) $(C++FLAGS) -I$(HDRS) -I$(STDHDRS) -Fo$(<) -Tp$(>)
   }
   
   

   Note that Link-action may require special care: on platforms where the global variable gEXPORT_SUFFIX(DLL) is defined (e.g. Windows), the first argument may have two elements when linking a shared library. The first is the shared library target, and the second is the import library target, with suffix given by $(gEXPORT_SUFFIX(DLL)). It will always have a third argument which is either ``EXE'' or ``DLL''. This can be used to dispatch to different actions for linking DLLs and EXEs if necessary, but usually it will be easier to take advantage of the special <target-type> feature, which will have the same value using the flags rule described below.
2. Translate build settings given in the global gBUILD_PROPERTIES variable into something that can be used by the toolset. The build system provides the flags rule to help translate build properties into elements of global variables which are later attached to targets so that they can affect the build actions. The flags rule is used as follows:

   flags toolset variable condition [: value...]
   

   The parameters are:
   • toolset - the name of the toolset
   • variable - the name of a global variable which can be used to carry information to a command-line
   • condition - one one or more elements in the following forms:
     1. a property-set of the form: <feature>value[/<feature> value...]
     2. <feature>
   • values - anything

   Semantics only affect targets built with the specified toolset, and depend on the target's build configuration:

   1. if any specified property-set is a subset of the target's build properties, the values specified in $(3) will be appended once to variable.
   2. The value of each specified feature that participates in the target's build properties is appended to variable. In either case, the variable will be set "on" the target so it may be used in the build actions.

Example

The description of the flags rule above is actually more complicated than it sounds. For example, the following line might be used to specify how optimization can be turned off for MSVC:

flags msvc CFLAGS <optimization>off : /Od ;

Similarly, in the following example,

flags msvc CFLAGS <runtime-build>release/<runtime-link>dynamic : /MD ;

flags msvc HDRS <include> ;

The use of these variables should be apparent from the declaration of actions msvc-C++-action in the previous section.

Internals

Target Names

In addition to user targets, which correspond directly to the names the user writes in her subproject Jamfile, several additional targets are generated, regardless of the directory from which Jam was invoked:

• A main target has all the same dependencies as a user target (i.e. building it updates all requested subvariants). Its name is the same except for the addition of $(SOURCE_GRIST), which identifies the subproject. The identification looks like the names of the path components from the project root to the subproject, separated by exclamation points. Thus, if the project is rooted at foo, in the subproject at foo/bar/baz the target my_target is identified by <bar!baz>my_target.
• A subvariant target has additional grist identifying its main target and subvariant. This grist is joined to $(SOURCE_GRIST) with the platform's directory separator. Thus, on UNIX, a subvariant target of my_target above might be identified as <bar!baz/my_target/optimization-space/runtime-link-static>my_source.o. Note that the part of the grist following the first slash, known as the subvariant id, also corresponds to a fragment of the subvariant directory path where the corresponding target is generated. Most built targets will be identified this way.

Global Variables

This section describes some of the global variables used by the build system. Please note that some parts of the system (particularly those in allyourbase.jam) are heavily based on the Jambase file supplied with Jam, and as such do not follow the conventions described below.

Global variables used in the build system fall into three categories:

• Global variables intended to be set by the user on the command-line or in the environment use ALL_UPPER_CASE names.
• Internal global variables begin with a lower-case "g" and continue in upper-case: gSOME_GLOBAL
• Global variables of the form: gBASE_NAME(arguments), where arguments is a comma-separated argument list, are used internally to achieve a kind of indirection by concatenating variable values:

      ECHO $(gFUBAR($(x),$(y))) ;
  

Please note that the build system commonly takes advantage of Jam's Dynamic Scoping feature (see the local command in the "Flow of Control" section below the link target) to temporarily "change" a global variable by declaring a local of the same name.

Many of the variables that are used to configure how Boost.Build works internally are listed here with brief descriptions.

Variables Associated with SubProject Identity

• SUBDIR_TOKENS - a list of the path elements relative to the project root of the current subproject.
• SUBDIR - the path from the invocation directory to the current subproject directory.

Grist Variables

• TARGET_GRIST takes the form subproject!id/target/toolset/variant/subvariant-path.

Design Criteria

Assumptions

The requirements are driven by several basic assumptions:

• There is no single Boost developer or test facility with access to or knowledge of all the platforms and compilers Boost libraries are used with.
• Boost libraries are used across such a wide range of platforms and compilers that almost no other assumptions can be made.

Requirements

This build system was designed to satisfy the following requirements:

• A developer adding a new library or test program must only have to add simple entries naming the source files to a text file, and not have to know anything about platform specific files. The developer should not have to supply header dependency information.
• There should be a very high likelihood of builds succeeding on all platforms if a build succeeds on any platform. In other words, a developer must not be required to have access to many platforms or compilers to ensure correct builds
• A user or developer adding support for a new platform or compiler should only have to add to a single file describing how to do the build for that platform or compiler, and shouldn't have to identify the files that will need to be built.
• The build should rely only on tools native to the platform and compiler, or supplied via the boost download.
• The details of how the build is done for a particular platform or compiler should be appropriate for that platform.
• It should be possible to build multiple variants (e.g. debug/release) of a single target.
• It should be possible to build multiple variants of multiple targets with multiple compilers from a single build command.
• The build tools must be able to handle Boost growth issues such as identified in Directory Structure proposals and discussion.
• Support for dynamic and static linking should be included.
• It should be relatively straightforward to add support for a new compiler. In most cases, no modification of files used to describe existing targets should be required.
• Support for compiler- and variant-specific configuration for each target
• It should be possible to build targets into a directory unrelated to the source directories (they may be read-only)

Footnotes

[2] Note: right now, a dependency feature of a main target makes all resulting built targets dependent, including intermediate targets. That means that if an executable is dependent on an external library, and that library changes, all the sources comprising the executable will be recompiled as well. This behavior should probably be fixed.

Revised 8 September, 2003

Copyright © Dave Abrahams 2001.

Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at www.boost.org/LICENSE_1_0.txt)