Step 1: Download boost

You'll find boost here.

Extract the archive to some directory where you want it. For the sake of this guide, let's assume you extract the package to c:\boost_1_55_0 (I'm using a windows path in this example since if you're on linux/unix you're more likely to use the autotools). You'll need at least version 1.49 of the boost library in order to build libtorrent.

Step 2: Setup BBv2

First you need to build bjam. You do this by opening a terminal (In windows, run cmd). Change directory to c:\boost_1_55_0\tools\jam\src. Then run the script called build.bat or build.sh on a unix system. This will build bjam and place it in a directory starting with bin. and then have the name of your platform. Copy the bjam.exe (or bjam on a unix system) to a place that's in you shell's PATH. On linux systems a place commonly used may be /usr/local/bin or on windows c:\windows (you can also add directories to the search paths by modifying the environment variable called PATH).

Now you have bjam installed. bjam can be considered an interpreter that the boost-build system is implemented on. So boost-build uses bjam. So, to complete the installation you need to make two more things. You need to set the environment variable BOOST_BUILD_PATH. This is the path that tells bjam where it can find boost-build, your configuration file and all the toolsets (descriptions used by boost-build to know how to use different compilers on different platforms). Assuming the boost install path above, set it to c:\boost_1_55_0\tools\build\v2.

To set an environment variable in windows, type for example:

set BOOST_BUILD_PATH=c:\boost_1_55_0\tools\build\v2

In a terminal window.

The last thing to do to complete the setup of BBv2 is to modify your user-config.jam file. It is located in c:\boost_1_55_0\tools\build\v2. Depending on your platform and which compiler you're using, you should add a line for each compiler and compiler version you have installed on your system that you want to be able to use with BBv2. For example, if you're using Microsoft Visual Studio 12 (2013), just add a line:

using msvc : 12.0 ;

If you use GCC, add the line:

using gcc ;

If you have more than one version of GCC installed, you can add the commandline used to invoke g++ after the version number, like this:

using gcc : 3.3 : g++-3.3 ;
using gcc : 4.0 : g++-4.0 ;

Another toolset worth mentioning is the darwin toolset (For MacOS X). From Tiger (10.4) MacOS X comes with both GCC 3.3 and GCC 4.0. Then you can use the following toolsets:

using darwin : 3.3 : g++-3.3 ;
using darwin : 4.0 : g++-4.0 ;

Note that the spaces around the semi-colons and colons are important!

Also see the official installation instructions.

Step 3: Building libtorrent

When building libtorrent, the Jamfile expects the environment variable BOOST_ROOT to be set to the boost installation directory. It uses this to find the boost libraries it depends on, so they can be built and their headers files found. So, set this to c:\boost_1_55_0. You only need this if you're building against a source distribution of boost.

Then the only thing left is simply to invoke bjam. If you want to specify a specific toolset to use (compiler) you can just add that to the commandline. For example:

bjam msvc-7.1 boost=source
bjam gcc-3.3 boost=source
bjam darwin-4.0 boost=source

If you're building against a system installed boost, specify boost=system.

To build different versions you can also just add the name of the build variant. Some default build variants in BBv2 are release, debug, profile.

You can build libtorrent as a dll too, by typing link=shared, or link=static to build a static library.

If you want to explicitly say how to link against the runtime library, you can set the runtime-link feature on the commandline, either to shared or static. Most operating systems will only allow linking shared against the runtime, but on windows you can do both. Example:

bjam msvc-7.1 link=static runtime-link=static boost=source

The build targets are put in a directory called bin, and under it they are sorted in directories depending on the toolset and build variant used.

To build the examples, just change directory to the examples directory and invoke bjam from there. To build and run the tests, go to the test directory and run bjam.

Note that if you're building on windows using the msvc toolset, you cannot run it from a cygwin terminal, you'll have to run it from a cmd terminal. The same goes for cygwin, if you're building with gcc in cygwin you'll have to run it from a cygwin terminal. Also, make sure the paths are correct in the different environments. In cygwin, the paths (BOOST_BUILD_PATH and BOOST_ROOT) should be in the typical unix-format (e.g. /cygdrive/c/boost_1_55_0). In the windows environment, they should have the typical windows format (c:/boost_1_55_0).

The Jamfile will define NDEBUG when it's building a release build. For more build configuration flags see Build configurations.

Build features:

boost build feature	values
boost	system - default. Tells the Jamfile that boost is installed and should be linked against the system libraries. source - Specifies that boost is to be built from source. The environment variable BOOST_ROOT must be defined to point to the boost directory.
boost-link	static - links statically against the boost libraries. shared - links dynamically against the boost libraries.
logging	none - no logging. default - basic session logging. verbose - verbose peer wire logging. errors - like verbose, but limited to errors.
dht	on - build with support for tracker less torrents and DHT support. logging - build with DHT support and verbose logging of the DHT protocol traffic. off - build without DHT support.
need-librt	no - this platform does not need to link against librt to have POSIX time functions. yes - specify this if your linux system requires you to link against librt.a. This is typically the case on x86 64 bit systems.
asserts	auto - asserts are on if in debug mode on - asserts are on, even in release mode off - asserts are disabled production - assertion failures are logged to asserts.log in the current working directory, but won't abort the process.
upnp-logging	off - default. Does not log UPnP traffic. on - creates "upnp.log" with the messages sent to and received from UPnP devices.
encryption	openssl - links against openssl and libcrypto to enable https and encrypted bittorrent connections. gcrypt - links against libgcrypt to enable encrypted bittorrent connections. tommath - uses a shipped version of libtommath and a custom rc4 implementation (based on libtomcrypt). This is the default option. off - turns off support for encrypted connections. The shipped public domain SHA-1 implementation is used.
allocator	pool - default, uses pool allocators for send buffers. system - uses malloc() and free() instead. Might be useful to debug buffer issues with tools like electric fence or libgmalloc. debug - instruments buffer usage to catch bugs in libtorrent.
link	static - builds libtorrent as a static library (.a / .lib) shared - builds libtorrent as a shared library (.so / .dll).
runtime-link	static - links statically against the run-time library (if available on your platform). shared - link dynamically against the run-time library (default).
variant	debug - builds libtorrent with debug information and invariant checks. release - builds libtorrent in release mode without invariant checks and with optimization. profile - builds libtorrent with profile information.
character-set	This setting will only have an affect on windows. Other platforms are expected to support UTF-8. unicode - The unicode version of the win32 API is used. This is default. ansi - The ansi version of the win32 API is used.
invariant-checks	This setting only affects debug builds (where NDEBUG is not defined). It defaults to on. on - internal invariant checks are enabled. off - internal invariant checks are disabled. The resulting executable will run faster than a regular debug build. full - turns on extra expensive invariant checks.
debug-symbols	on - default for debug builds. This setting is useful for building release builds with symbols. off - default for release builds.
deprecated-functions	on - default. Includes deprecated functions of the API (might produce warnings during build when deprecated functions are used). off - excludes deprecated functions from the API. Generates build errors when deprecated functions are used.
full-stats	on - default, collects stats for IP overhead and DHT and trackers. This uses a little bit extra memory for each peer and torrent. off - only collects the standard stats for upload and download rate.
iconv	auto - use iconv for string conversions for linux and mingw and other posix platforms. on - force use of iconv off - force not using iconv (disables locale awareness except on windows).
asserts	off - disable all asserts production - enable asserts in release builds, but don't abort, just log them to extern char const* libtorrent_assert_log. on - enable asserts in debug builds (this is the default). On GNU systems, print a stack trace of the assert and some more information. system use the libc assert macro
i2p	on - build with I2P support off - build without I2P support
boost-date-time	off - don't build asio types that depend on boost.date_time. libtorrent doesn't use them but if the client does, you need these to be built. on - build asio types that depend on boost.date_time.
statistics	off - default. No logging of additional stats. on - log session statistics in current working directory session_stats<pid>. The log is rotated every hour. It can be parsed by the parse_session_stats.py script (requires gnuplot)
profile-calls	off - default. No additional call profiling. on - Enable logging of stack traces of calls into libtorrent that are blocking. On session shutdown, a file blocking_calls.txt is written with stack traces of blocking calls ordered by the number of them.

The variant feature is implicit, which means you don't need to specify the name of the feature, just the value.

The logs created when building vlog or log mode are put in a directory called libtorrent_logs in the current working directory.

When building the example client on windows, you need to build with link=static otherwise you may get unresolved external symbols for some boost.program-options symbols.

For more information, see the Boost build v2 documentation, or more specifically the section on builtin features.

Step 1: Generating the build system

No build system is present if libtorrent is checked out from CVS - it needs to be generated first. If you're building from a released tarball, you may skip directly to Step 2: Running configure.

Execute the following command to generate the build system:

./autotool.sh

Step 2: Running configure

In your shell, change directory to the libtorrent directory and run ./configure. This will look for libraries and C++ features that libtorrent is dependent on. If something is missing or can't be found it will print an error telling you what failed.

The most likely problem you may encounter is that the configure script won't find the boost libraries. Make sure you have boost installed on your system. The easiest way to install boost is usually to use the preferred package system on your platform. Usually libraries and headers are installed in standard directories where the compiler will find them, but sometimes that may not be the case. For example when installing boost on darwin using darwinports (the package system based on BSD ports) all libraries are installed to /opt/local/lib and headers are installed to /opt/local/include. By default the compiler will not look in these directories. You have to set the enviornment variables LDFLAGS and CXXFLAGS in order to make the compiler find those libs. In this example you'd set them like this:

export LDFLAGS=-L/opt/local/lib
export CXXFLAGS=-I/opt/local/include

It was observed on FreeBSD (release 6.0) that one needs to add '-lpthread' to LDFLAGS, as Boost::Thread detection will fail without it, even if Boost::Thread is installed.

If you need to set these variables, it may be a good idea to add those lines to your ~/.profile or ~/.tcshrc depending on your shell.

If the boost libraries are named with a suffix on your platform, you may use the --with-boost-thread= option to specify the suffix used for the thread library in this case. For more information about these options, run:

./configure --help

On gentoo the boost libraries that are built with multi-threading support have the suffix mt.

You know that the boost libraries were found if you see the following output from the configure script:

checking whether the Boost::DateTime library is available... yes
checking for main in -lboost_date_time... yes
checking whether the Boost::Filesystem library is available... yes
checking for main in -lboost_filesystem... yes
checking whether the Boost::Thread library is available... yes
checking for main in -lboost_thread... yes

Another possible source of problems may be if the path to your libtorrent directory contains spaces. Make sure you either rename the directories with spaces in their names to remove the spaces or move the libtorrent directory.

Creating a debug build

To tell configure to build a debug version (with debug info, asserts and invariant checks enabled), you have to run the configure script with the following option:

./configure --enable-debug=yes

Creating a release build

To tell the configure to build a release version (without debug info, asserts and invariant checks), you have to run the configure script with the following option:

./configure --enable-debug=no

The above option make use of -DNDEBUG, which is used throughout libtorrent.

Step 3: Building libtorrent

Once the configure script is run successfully, you just type make and libtorrent, the examples and the tests will be built.

When libtorrent is built it may be a good idea to run the tests, you do this by running make check.

If you want to build a release version (without debug info, asserts and invariant checks), you have to rerun the configure script and rebuild, like this:

./configure --disable-debug
make clean
make