downloading and building

Step 1: Download boost

If you want to build against boost installed on your system, you can skip this strep. Just make sure to have BOOST_ROOT unset for the b2 invocation.

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_69_0. You'll need at least version 1.58 of the boost library in order to build libtorrent.

Step 2: Setup BBv2

If you have installed boost-build via a package manager, you can skip this step. If not, you need to build boost build from the boost source package.

First you need to build b2. You do this by opening a terminal (In windows, run cmd). Change directory to c:\boost_1_68_0\tools\build. Then run the script called bootstrap.bat or bootstrap.sh on a Unix system. This will build b2 and place it in a directory src/engine/bin.<architecture>. Copy the b2.exe (or b2 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 b2 installed. b2 can be considered an interpreter that the boost-build system is implemented on. So boost-build uses b2. 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 b2 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_68_0\tools\build.

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

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

In a terminal window.

The last thing to do is to configure which compiler(s) to use. Create a file user-config.jam in your home directory. 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 : 14.0 ;

If you use GCC, add the line:

using gcc ;

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

using gcc : 6.0 : g++-6 ;
using gcc : 7.0 : g++-7 ;

Another toolset worth mentioning is the darwin toolset (for macOS). From Tiger (10.4) macOS 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 boost-build documentation.

Step 3: Building libtorrent

When building libtorrent, boost is either picked up from system installed locations or from a boost source package, if the BOOST_ROOT environment variable is set pointing to one. If you're building boost from source, set BOOST_ROOT to your boost directory, e.g. c:\boost_1_68_0.

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

b2 msvc-14.0
b2 gcc-7.0
b2 darwin-4.0

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 command line, either to shared or static. Most operating systems will only allow linking shared against the runtime, but on windows you can do both. Example:

b2 msvc-14.0 link=static runtime-link=static

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 b2 from there. To build and run the tests, go to the test directory and run b2.

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_68_0). In the windows environment, they should have the typical windows format (c:/boost_1_68_0).

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

When enabling linking against openssl (by setting the crypto feature to openssl) the Jamfile will look in some default directory for the openssl headers and libraries. On macOS, it will look for the homebrew openssl package. On Windows, it will look in C:\OpenSSL-Win32, or C:\OpenSSL-Win64 if compiling in 64-bit.

To customize the library path and include path for openssl, set the features openssl-lib and openssl-include respectively.

Build features

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

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 built-in features.

Step 4: Installing libtorrent

To install libtorrent run b2 with the install target:

b2 install --prefix=/usr/local

Change the value of the --prefix argument to install it in a different location.

Step 1: Generating the build system

Create a build directory for out-of-source build inside the libtorrent root directory:

mkdir build

and cd there:

cd build

Run cmake in the build directory, like this:

cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_STANDARD=11 -G Ninja ..

The CMAKE_CXX_STANDARD has to be at least 11, but you may want to raise it to 14 or 17 if your project use a newer version of the C++ standard.

Other build options are:

Options are set on the cmake command line with the -D option or later on using ccmake or cmake-gui applications. cmake run outputs a summary of all available options and their current values.

Step 2: Building libtorrent

In the terminal, run:

ninja -j8

in the build directory the number after -j specifies the number of parallel jobs to build in; you may omit this option to let ninja use all your cores).

If you enabled test in the configuration step, to run them, run:

ctest -j8