Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

Click here to view the latest version of this page.
PrevUpHomeNext

Build

Building the Boost.Thread Libraries
Testing the Boost.Thread Libraries

How you build the Boost.Thread libraries, and how you build your own applications that use those libraries, are some of the most frequently asked questions. Build processes are difficult to deal with in a portable manner. That's one reason why Boost.Thread makes use of Boost.Build. In general you should refer to the documentation for Boost.Build. This document will only supply you with some simple usage examples for how to use bjam to build and test Boost.Thread. In addition, this document will try to explain the build requirements so that users may create their own build processes (for instance, create an IDE specific project), both for building and testing Boost.Thread, as well as for building their own projects using Boost.Thread.

Building the Boost.Thread Libraries

Building the Boost.Thread Library depends on how you intend to use it. You have several options:

  • Using as a precompiled library, possibly with auto-linking, or for use from within an IDE.
  • Use from a Boost.Build project.
  • Using in source form.

Precompiled

Using the Boost.Thread library in precompiled form is the way to go if you want to install the library to a standard place, from where your linker is able to resolve code in binary form. You also will want this option if compile time is a concern. Multiple variants are available, for different toolsets and build variants (debug/release). The library files are named {lead}boost_thread{build-specific-tags}.{extension}, where the build-specific-tags indicate the toolset used to build the library, whether it's a debug or release build, what version of Boost was used, etc.; and the lead and extension are the appropriate extensions for a dynamic link library or static library for the platform for which Boost.Thread is being built. For instance, a debug build of the dynamic library built for Win32 with VC++ 7.1 using Boost 1.34 would be named boost_thread-vc71-mt-gd-1_34.dll. More information on this should be available from the Boost.Build documentation.

Building should be possible with the default configuration. If you are running into problems, it might be wise to adjust your local settings of Boost.Build though. Typically you will need to get your user-config.jam file to reflect your environment, i.e. used toolsets. Please refer to the Boost.Build documentation to learn how to do this.

To create the libraries you need to open a command shell and change to the boost_root directory. From there you give the command

bjam --toolset=mytoolset stage --with-thread

Replace mytoolset with the name of your toolset, e.g. msvc-7.1 . This will compile and put the libraries into the stage directory which is just below the boost_root directory. Boost.Build by default will generate static and dynamic variants for debug and release.

[Note] Note
Invoking the above command without the --with-thread switch Boost.Build will build all of the Boost distribution, including Boost.Thread.

The next step is to copy your libraries to a place where your linker is able to pick them up. It is also quite possible to leave them in the stage directory and instruct your IDE to take them from there.

In your IDE you then need to add boost_root/boost to the paths where the compiler expects to find files to be included. For toolsets that support auto-linking it is not necessary to explicitly specify the name of the library to link against, it is sufficient to specify the path of the stage directory. Typically this is true on Windows. For gcc you need to specify the exact library name (including all the tags). Please don't forget that threading support must be turned on to be able to use the library. You should be able now to build your project from the IDE.

Boost.Build Project

If you have decided to use Boost.Build as a build environment for your application, you simply need to add a single line to your Jamroot file:

use-project /boost : {path-to-boost-root} ;

where {path-to-boost-root} needs to be replaced with the location of your copy of the boost tree. Later when you specify a component that needs to link against Boost.Thread you specify this as e.g.:

exe myapp : {myappsources} /boost//thread ;

and you are done.

Source Form

Of course it is also possible to use the Boost.Thread library in source form. First you need to specify the boost_root/boost directory as a path where your compiler expects to find files to include. It is not easy to isolate the Boost.Thread include files from the rest of the boost library though. You would also need to isolate every include file that the thread library depends on. Next you need to copy the files from boost_root/libs/thread/src to your project and instruct your build system to compile them together with your project. Please look into the Jamfile in boost_root/libs/thread/build to find out which compiler options and defines you will need to get a clean compile. Using the boost library in this way is the least recommended, and should only be considered if avoiding dependency on Boost.Build is a requirement. Even if so it might be a better option to use the library in it's precompiled form. Precompiled downloads are available from the boost consulting web site, or as part of most linux distributions.

Testing the Boost.Thread Libraries

To test the Boost.Thread libraries using Boost.Build, simply change to the directory boost_root/libs/thread/test and execute the command:

bjam --toolset=mytoolset test

Last revised: January 18, 2007 at 17:33:50 GMT

Copyright 2001-2003 William E. Kempf

PrevUpHomeNext