Boost

This page is about a set of C++ libraries collectively named Boost .

How to build and install Boost

BJam overview

BJam, or Boost.Jam, is the build system used by Boost. From the Boost.Jam documentation :

Boost.Jam (BJam) is the low-level build engine tool for Boost.Build. Historically, Boost.Jam is based on on FTJam and on Perforce Jam but has grown a number of significant features and is now developed independently, with no merge back expected to happen, and little use outside Boost.Build.

Also important as a reference is the Boost.Jam Manual .

site-config.jam and user-config.bjam

From the BJam manual:

On startup, Boost.Build searches and reads two configuration files: site-config.jam and user-config.jam. The first one is usually installed and maintained by system administrator, and the second is for user to modify.

Usually I modify user-config.jam in the location BOOST_SRC/tools/build/v2/user-config.jam. Example:

using darwin : 4.2.1~iphoneos
   : $IPHONE_OS_COMPILER -arch armv7 -mthumb -fvisibility=hidden -fvisibility-inlines-hidden $EXTRA_CPPFLAGS
   : <striper> <root>$IPHONEOS_PLATFORMDIR/Developer
   : <architecture>arm <target-os>iphone
   ;

Discussion:

• "using darwin" tells the build system that the tool "darwin" is available (see http://www.boost.org/boost-build2/doc/html/bbv2/overview/configuration.html and http://www.boost.org/boost-build2/doc/html/bbv2/reference/tools.html)
• "4.2.1~iphone" names the set of configuration options being used here. Apparently this can be any string. The string will be used to form part of the build directory hierarchy. More importantly, the string can be used later on during a build to tell bjam which configuration options it should use.
• The next field specifies the compiler executable to run. On iOS this file should be determined via xcrun. Apparently it is possible to specify additional flags here.
• The next field specifies compiler options, the syntax is <option-name>option-value.
  • I don't know what the meaning of "<striper>" is.
  • The <root> option instructs the tool "darwin" where to look when it validates the value of the <macosx-version> feature. Without <root>, or with <root> pointing to the wrong folder, the build will fail with an error message like this:

error: "iphone-6.1" is not a known value of feature <macosx-version>

• The last field specifies conditions

Selecting an architecture on Mac OS X

On Mac OS X, it is not possible to specify multiple -arch flags to gcc, in case one wants to build "fat" binaries. At least this is true for Mac OS X 10.6 and Boost 1.45. If -arch is specified more than once, BJam includes a few compiler flags which are not recognized by Apple's gcc, which then causes the build to abort with the following errors.

cc1plus: error: unrecognized command line option "-Wno-long-double"
cc1plus: error: unrecognized command line option "-fcoalesce-templates"
cc1plus: error: unrecognized command line option "-Wno-long-double"
cc1plus: error: unrecognized command line option "-fcoalesce-templates"

Note: For an iPhoneOS build, specifying -arch armv7 generates 2 architectures nonetheless (armv6, armv7). For a Mac OS X build, only either i386 or ppc can be generated.

BJam command line

# Select build configurations
./bjam debug release

# Build a target
./bjam aTarget

# Cleaning
./bjam --clean aTarget

# Specifying a feature works with the key=value scheme
# see http://www.boost.org/boost-build2/doc/html/bbv2/reference/definitions.html#bbv2.reference.features
#     http://www.boost.org/boost-build2/doc/html/bbv2/overview/builtins/features.html
./bjam debug-symbols=on aTarget

# Configurations are actually features, omitting "variant=" is merely a special
# case supported by BJam because specifying a configuration is such a common thing to do
./bjam variant=release aTarget

# Build static/shared libs via the "link" feature
./bjam link=static aTarget
./bjam link=shared aTarget     # this is the default

# "macosx-version" is a feature. Valid values are "iphone-*" and "iphonesim-*". The allowed version numbers
# are determined by examining the SDKs present in the iPhoneOS and iPhoneSimulator platform directories.
#
# "target-os" is a feature. "iphone" is a predefined value
#
# "darwin" tool stuff is in BOOST_SRC/tools/build/v2/tools/darwin.jam
./bjam toolset=darwin architecture=arm target-os=iphone macosx-version=iphone-4.2 link=static release

Bootstrapping and building

Using the knowledge from the previous section about BJam, the following example shows how to build and install a set of Boost libraries:

cd /path/to/boost
BOOST_LIBS="thread signals filesystem regex program_options system test date_time"
BOOST_LIBS_COMMA=$(echo $BOOST_LIBS | sed -e "s/ /,/g")
./bootstrap.sh --with-libraries="$BOOST_LIBS_COMMA"
# Modify user-config.bjam so that the "darwin" tool is available
./bjam --prefix="/usr/local" toolset=darwin install

Notes:

• Bootstrapping can be repeated without cleaning previous build results. Boost will simply re-configure its build configuration in project-config.jam, which will be picked up next time a build is started.
• Also, bootstrapping can be repeated with a different value for --with-libraries

Using Boost

I have not yet used Boost in any project of mine.