build boost
(Visual Studio 200x/201x unter Windows)
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.-j4oder - mit doppel-
--: z.B.:--help,`--without-<library>
sowie Properties:
- ohne prefix:
variant=releaseoder - 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 |
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 |
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 |
- |
--without-<library> |
Do not build, stage, or install the specified |
- |
--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
- ...