The definitive guide on compiling and linking Boost C++ libraries for Visual Studio projects

Recently, a requirement came up to migrate a legacy C++ codebase, containing quite a few of custom implemented functionalities, into a more robust architecture. After spending some time at searching, we decided to include the Boost libraries, due to the large set of utilities they offer. 

Most of the C++ Boost libraries are header-only; they consist entirely of header files, and require no separately-compiled library binaries. However, there are some libraries that need to be built separately. The "Getting Started" guide on Boost website is quite informative, but do not provide clear guidance on how to build for multiple architectures and targets (debug/release). We're using Visual Studio as our IDE and finding the best way to build those binaries was quite tiresome. 

For that reason, we dedicated this guide on how to build and link the C++ Boost libraries in Visual Studio projects.

Downloading the Boost libraries

To get the latest version of Boost (or any other version for that matter), go to the official download page. We are targeting Windows platforms, so we need to choose the respective version. The "Getting Started" guide recommends downloading the 7-Zip archive.

We no longer recommend .zip files for Boost because they are twice as large as the equivalent .7z files. We don't recommend using Windows' built-in decompression as it can be painfully slow for large archives. - "Getting Started on Windows", www.boost.org

The current release, as of this day, is version 1.76.0, but the methodology we are going to follow works (and will continue to work in the future) for any release.

After we successfully downloaded the archive, we need to extract the containing folder into the desired location. 

The documentation assumes that the path for any library version is inside C:\Program Files\boost, so we're going to respect that. Create a directory called boost inside C:\Program Files\ and extract the archive there.

Building the binaries

The Boost libraries includes a really nice build system, which we are definitely going to use it. The build system is triggered from the command line. First we have to open the cmd window and navigate into the root folder of the Boost library.

Then we have to initialize the build system by running the bootstrap.bat file.

After bootstraping is done, it's time to build the actual binaries. Remember what we said earlier: We have to build

• artifacts for x64 architecture
• artifacts for x86 architecture
• artifacts for static linking (i.e. .lib files)
• artifacts for dynamic linking (i.e. .dll files)
• release artifacts
• debug artifacts

In general, we need to trigger 8 builds. Fortunately for us, the build command allow us to specify multiple targets in one build. In the end, we'll only trigger two builds, one for each architecture type.

Building for x86 architecture

Run the following command in you terminal:

b2 --build-dir=build\x86 address-model=32 threading=multi --stagedir=.\bin\x86 --toolset=msvc -j 16 link=static,shared runtime-link=static,shared --variant=debug,release

This command will build and place the binaries into C:\Program Files\boost\boost_1_76_0\bin\x86\lib\. The output will contain all the required files we might need for most of our projects.

Building Debug for x64 architecture

Execute the following command on you terminal:

b2 --build-dir=build\x64 address-model=64 threading=multi --stagedir=.\bin\x64 --toolset=msvc -j 8 link=static,shared runtime-link=static,shared --variant=debug,release

This command will build and place the binaries into C:\Program Files\boost\boost_1_76_0\bin\x64\lib\. As before, the output will contain all the required files we might need for most of our projects.

Explaining the build command arguments

Let's take a quick look on the arguments used in the previous two commands.

• --build-dir: Specify the directory to place all the intermediate files while building.
• address-model: Specify the targeting address model.
• threading: Compile Boost to be thread aware. (see this question on stackoverflow for more info.)
• --stage-dir: the directory where the binaries will be placed.
• --toolset: The compiler and linker that will be used to build the artifacts. We chose msvc; this should be the default on Windows, but in case we have more compilers installed on the system, it's better to explicitly define it.
• -j: how many threads to use for building. This can drastically improve the build times on multi-threading environments, i.e. most modern machines.
• link: declare a library target.
• runtime-link: linking statically/dynamically to the C++ standard library and compiler runtime support libraries.
• --variant: Build debug or release version of the binaries.

Including the Boost libraries on Visual Studio

To be able to work with the Boost libraries in Visual Studio, we have to define the root path, that is C:\Program Files\boost\boost_1_76_0, into each individual project properties. In this guide, we use Visual Studio 2019, but this process can be applied to older versions as well. To include the libraries, do the following:

On a Visual Studio solution → Select the project you want to add the library into → Right Click → "Properties"

The properties window should now be open. An example is attached bellow:

Before we proceed take a moment to ensure that both "Configuration" and "Platform" values are selected as shown in the following screenshot. This will apply the changes we're going to make into all the platforms.

We're going to modify the "Additional Include Directories" option of "C/C++" → "General" property.

Select the drop-down button and then click < Edit.. >.

Now we have to add the library path and hit OK.

The option value should be updated as shown in the following screenshot.

Note that %(AdditionalIncludeDirectories) macro was automatically included in the value. This is expected and includes some default values specified by the system.

We are ready to work with most of the Boost libraries. We can include them in our source code without any issues. However, if we use libraries that require linking (like boost/chrono, boost/thread, etc) we have to link the binaries we built earlier to the linker.

Linking the Boost libraries on Visual Studio

This is the final step to our journey. The only think we have to do, is to tell the linker to include our binaries. Like before, open the properties window:

On a Visual Studio solution → Select the project you want to add the library → Right Click → "Properties"

Before we proceed take a moment to ensure that the "Configuration" and "Platform" values are selected as shown in the following screenshot. This will apply the changes we're going to make into all the platforms.

We're going to modify the "Additional Library Directories" option of "Linker" → "General" property.

(Note: In case your project builds a static library, the "Linker" menu will be shown as "Librarian".)

Select the drop-down button and then click < Edit.. >.

Add the following value: C:\Program Files\boost\boost_1_76_0\bin\$(PlatformTarget)\lib, and hit OK.

The property value should be updated as shown in the following screenshot.

Take a quick note on $(PlatformTarget) macro. Recall when we built our targets and created two directories, one for each architecture. This macro defines the correct folder for use depending on the selected build platform.

Note that %(AdditionalLibraryDirectories) macro was automatically included in the value. This is expected and includes some default values specified by the system.

Testing the boost libraries

We should now be able to build and run our projects in both x86 and x64 architectures, targeting both debug and release versions. In case you want a quick, test program, we provide the following example from boost/chrono library.

Bellow is a running example screenshot using Debug and x64:

Conclusion

In this guide we described how we can set up Boost C++ libraries in Windows and link them into Visual Studio projects. We tried to be as detailed as possible in our explanation. We wanted to provide a unified reference for future readers who might encounter the same problems we did.

As a final note, we inform the readers that we tested all the steps provided in this article, on multiple projects, without any issues. However, if you have a different set-up, that might or might not cause problems. If this is the case, feel free to comment your question or point any ambiguity you have encountered. 

I have plans to write more articles regarding project organization and software development in the future. Feel free to post suggestions and articles ideas you might want to read about.