Bauen der Boost Bibliotheken

für das Visual Studio 2008 - 2012 unter Windows

Die meisten Boost Bibliotheken sind sogenannte Header-Only Bibliotheken: Sie bestehen aus einem Satz aus Header-Dateien, die Templates und inline-Funktionen enthalten. Diese können durch Hinzufügen des Inclucde-Verzeichnis verwendet werden.

Leider gilt das nicht für alle Boost Bibliotheken. Einige wenige Bibliotheken (System, Filesystem, Program options, Date Time, Regex und andere) bestehen zusätzlich aus cpp-Dateien, die erst übersetzt werden müssen, um sie dann in Form einer statischen- (.lib) oder dynamischen Bibliothek (.dll) nutzen zu können.

Das Bauen der Bibliotheken ist dank des Boost Build Systems (Boost.Build) nicht schwierig. Jedoch ist die Syntax der Kommandozeilenparameter für das Build-Programm eher "ungewöhnlich".

Wer nicht den ganzen Artikel lesen will kann meine Lieblingskonfiguration ausprobieren:

Öffnen einer (fast) beliebigen Cmd-Shell (jedoch nicht den Visual Studio Command Prompt!):

cd boost_1_52_0
bootstrap
b2 -j4 --toolset=msvc-10.0 address-model=64 architecture=x86 debug-symbols=on --stagedir=./stageVC10x64   --build-dir=D:\tmp\buildVC10x64 --build-type=complete stage

die wichtigsten Parameter

Paramter Beschreibung Beispiel
--toolset=<toolset[-version]> Compiler --toolset=msvc-10.0
address-model 32 oder 64 bit address-model=64
install target for build install and install b2 install --prefix=C:\boost
--prefix target directory for install --prefix=C:\boost
stage target for build only (and copy libs to stagedir) b2 stage --stagedir=./stage --build-dir=D:\tmp\build
--stagedir target directory for libs (static and dynamic) --stagedir=./stage
--build-dir directory for builded stuff (*.obj, ...) --build-dir=D:\tmp\build
--build-type build a set of variants. complete or minimal. For specific variants, specify the variant and don't use --build-type. --build-type=complete
architecture Processor family x86, ia64 or combined for "fat" binaries (not for windows) architecture=x86

defaults

Eigendlich wäre alles ganz einfach...

Wenn man nur einen C++-Compiler auf seinem System installiert hätte und mit den voreingestellten Werten zufrieden wäre, wäre es ganz einfach die boost-Bibliotheken zu bauen:

  • Öffnen eines Command Prompts,
  • Bauen von bjam (bootstrap.bat)
  • starten von bjam (b2.exe install)

Dabei wählt bjam einen beliebigen C++-Compiler im System (meistens das neuste installierte Visual Studio) und baut die Bibliotheken in einer 32-Bit-Version ohne Debuginformationen in der release Version. Für den Einstieg mag das genügen, aber sobald man die boost Bibliotheken in einem bestehenden Programm, mit bestimmten Randbedingungen verwenden möchte, muss man sich tiefer mit dem Boost Build System beschäftigen.

Boost.build (aka. Boost Build System)

Das Boost Build System ( Boost.Build) besteht aus einem angepassten jam Programm (b2.exe) und den zugehörenden Jamfiles (*.jam).

Die Sourcen für das build-Programm (bjam.exe bzw. b2.exe) und die zugehörenden build scripte / Jamfiles (*jam) sind in der Boost Distributation enthalten. Mit dem bootstrap.bat-Script aus dem root Verzeichnis kann das Build-Programm gebaut werden. Dazu sollte ein beliebiger Commando Prompt verwendet werden. Die Verwendung eines Visual Studio Command Prompt kann zu Konflikten mit der automatischen Compiler-Versions-Erkennung führen.

Das fertige Programm befindet sich nach dem bauen 2x im Root Verzeichnis. (bjam.exe und b2.exe.) Dabei sollte es keinen Unterschied machen, ob man b2.exe oder bjam verwendet.

Boost verwendet Boost.Build zum bauen der Bibliotheken, der Dokumentation, Tests und Beispielen.

Kommandozeilenparameter

Die Syntax für die Verwendung vom Boost.Build lautet:

bjam [options] [properties] [install|stage]

Leider sind die Konvensionen für die Kommandozeilen etwas unübersichtlich:

bjam verwendet Optionen für die Kommandozeilen:

  • ohne - : z.B. "Targets": stage, install,
  • mit einfachem -: z.B. -j4 oder
  • mit doppel---: z.B.: --help, `--without-<library>

sowie Properties:

  • ohne prefix: variant=release oder
  • mit prefix: --toolset=msvc-10.0

Manche Properties können kombiniert werden, andere nicht. So kann man mit variant=debug,release die Bibliotheke in der debug-Version, als auch in der release-Version bauen. Da für die einzelnen Varianten Bibliotheken mit unterschiedlichen Namen erzeugt werden (mit und ohne g), können der Varianten zusammen gebaut werden.

Das Properties address-model spiegelt sich nicht im Dateiname der erzeugten Bibliothek nieder. Daher müssen 32- und 64-bit built in unterschiedliche Verzeichnisse erzeugt werden und müssen daher seperat gebaut werden.

targets

Boost.Build unterstützt 3 Targets:

Target Actions
install build and install
stage build
clean cleanup

install

b2 install baut die boost Bibliotheken und installiert sie in ein vorgegebenes Verzeichnis.

Es werden dabei das include-Verzeichnis und die lib-Verzeichnisse in getrennte Unterverzeichnisse kopiert. Dies ist hilfreich, wenn mehrere Adressmodelle oder Prozessor Architekturen unterstützt werden sollen.

Parameter Beschreibung default
--prefix=<PREFIX> Install architecture independent files here. C:\Boost on Win32
--exec-prefix=<EPREFIX> Install architecture dependent files here. <PREFIX>
--libdir=<DIR> Install library files here. <EPREFIX>/lib
--includedir=<HDRDIR> Install header files here. <PREFIX>/include

Anmerkungen: - Der Parameter --exec-prefix kann ignoriert werden, wenn statt dessen der Parameter --libdir=<DIR> verwendet wird. - bjam fügt zum includedir ein versionsspezifischen Unterverzeichnis hinzu. z.B.: c:\Boost\include\boost-1_52\boost for --prefix=C:\Boost. - Da install auch baut, können alle Parameter von stage auch für install verwendet werden.

stage

Parameter Beschreibung default
--stagedir=<STAGEDIR> Copy the libraries here ./stage

Mit dem Target stage kann man die boost Bibliotheken bauen und innerhalb des boost Verzeichnis verwenden. Dies kann sinnvoll sein, wenn man z.B. mit dem Funkionsumfang des install Target nicht zufrieden ist, da z.B. die Dokumentation nicht mit kopiert wird.

clean

Das target clean ist nicht wirklich dokumentiert und funktioniert nicht vollständig. So bleiben nach dem Aufruf von bjam clean die Verzeichnisstruktur des build-Verzeichnis stehen und die *.rsp Dateien werden nicht gelöscht.

Parameter für alle Targets

Parameter Beschreibung default
--build-type=<type> Build the specified pre-defined set of variations of the libraries. Note, that which variants get built depends on what each library supports. minimal
--build-type=minimal Builds a minimal set of variants. On Windows, these are static multithreaded libraries in debug and release modes, using shared runtime. -
--build-type=complete Build all possible variations. -
--build-dir=DIR Build in this location instead of building within the distribution tree. Recommended! -
--show-libraries Displays the list of Boost libraries that require build and installation steps, then exit. -
--layout=<layout> Determines whether to choose library names and header locations such that multiple versions of Boost or multiple compilers can be used on the same system. [versioned,tagged,system] -
--layout=versioned Names of boost binaries include the Boost version number, name and version of the compiler and encoded build properties. Boost headers are installed in a subdirectory of whose name contains the Boost version number. default on Windows
--layout=tagged Names of boost binaries include the encoded build properties such as variant and threading, but do not including compiler name and version, or Boost version. This option is useful if you build several variants of Boost, using the same compiler. -
--layout=system Binaries names do not include the Boost version number or the name and version number of the compiler. Boost headers are installed directly into . This option is intended for system integrators who are building distribution packages. default on Linux
--buildid=ID Adds the specified ID to the name of built libraries. The default is to not add anything. -
--python-buildid=ID Adds the specified ID to the name of built libraries that depend on Python. The default is to not add anything. This ID is added in addition to --buildid. -
--help Prints a help message -
--with-<library> Build and install the specified If this option is used, only libraries specified using this option will be built. -
--without-<library> Do not build, stage, or install the specified . By default, all libraries are built. -
--show-libraries Displays the list of Boost libraries that require build and installation steps, then exit. -

Properties

Parameter Beschreibung
toolset=toolset Indicates the toolset to build with.
variant=debug,release Select the build variant
link=static,shared Whether to build static or shared libraries
threading=single,multi Whether to build single or multithreaded binaries
runtime-link=static,shared Whether to link to static or shared C and C++ runtime.

Parameter

Allgemeine Parameter für bjam unabhängig von Boost.Build.

Parameter Beschreibung default
--version Prints information on the Boost.Build and Boost.Jam versions
-a Causes all files to be rebuilt.
-n Do no execute the commands, only print them.
-q Stop at the first error, as opposed to continuing to build targets that don't depend on the failed ones.
-j N Run up to N commands in parallel.
--clean Cleans all targets in the current directory and in any subprojects. Note that unlike the clean target in make, you can use --clean together with target names to clean specific targets.
--clean-all Cleans all targets, no matter where they are defined. In particular, it will clean targets in parent Jamfiles, and targets defined under other project roots.

Feature

Feature Allowed values Notes
variant debug,release -
link shared,static Determines if Boost.Build creates shared or static libraries
threading single,multi Cause the produced binaries to be thread-safe. This requires proper support in the source code itself.
address-model 32,64 Explicitly request either 32-bit or 64-bit code generation. This typically requires that your compiler is appropriately configured. Please refer to the section called "C++ Compilers" and your compiler documentation in case of problems.
toolset (Depends on configuration) The C++ compiler to use. See the section called "C++ Compilers" for a detailed list.
include (Arbitrary string) Additional include paths for C and C++ compilers.
define (Arbitrary string) Additional macro definitions for C and C++ compilers. The string should be either SYMBOL or SYMBOL=VALUE
cxxflags (Arbitrary string) Custom options to pass to the C++ compiler.
cflags (Arbitrary string) Custom options to pass to the C compiler.
linkflags (Arbitrary string) Custom options to pass to the C++ linker.
runtime-link shared,static Determines if shared or static version of C and C++ runtimes should be used.

List of toolsets

toolset Beschreibung
msvc irgendein installierter Microsoft Compiler (üblicherweiser die neuste installierte Version)
msvc-9.0 Visual Studio 2008
msvc-10.0 Visual Studio 2010
msvc-11.0 Visual Studio 2012

Die Boost Bibliothek kann automatisch den verwendeten Compiler erkennen und linkt automatisch die verwendeten Bibliotheken hinzu.

Weiteres

Weitere Konfigurationsmöglichkeiten:

  • Pfad zu Python
  • MPI
  • ICU
  • gzip, bzip2 filter für boost::iostreams
  • ...