Vcpkg: A tool to build open source libraries on Windows

In this post we describe Vcpkg, a tool created by Microsoft that helps acquire and build open source C and C++ libraries.

On Windows, downloading, building, and installing the libraries that a project requires can be difficult and time-consuming. First, you must locate and download each library from its own server or repository. Next, you must configure and build the libraries, each of which may use its own build system. Finally, you must set up your project to be able to find each library’s headers and to link to each library.

Vcpkg attempts to simplify the process of installing libraries on Windows to a single command line. Furthermore, by setting up the build environment using a CMake toolchain file, Vcpkg eliminates the need to manually define paths to libraries when configuring CMake-based projects.

We experimented using Vcpkg while developing a commercial project. The project relies on gRPC, an open source RPC framework, which proved difficult to build manually on Windows.

At the time of this writing, over 600 libraries are available in the Vcpkg ecosystem, including popular ones such as Boost, OpenCV, OpenSSL, and zlib. Vcpkg requires Visual Studio 2015 Update 3 or Visual Studio 2017.

Example: Install and use zlib

Vcpkg is best demonstrated by an example. Follow the steps below to install zlib and build a project that uses the installed zlib.

Install Visual Studio

Download and install Visual Studio from https://www.visualstudio.com/.

Set up Vcpkg:

The bootstrap script builds vcpkg.exe and vcpkgmetricsuploader.exe and copies them into C:\dev\vcpkg and C:\dev\vcpkg\scripts, respectively. vcpkgmetricsuploader.exe sends usage information about vcpkg.exe to Microsoft.

Install 64-bit zlib:

Total elapsed time: 29.85 s

The package zlib is compatible with built-in CMake targets:

Build the project:

CMakeLists.txt:

example.cpp:

Configure and build:

Run CMake, specifying the Vcpkg toolchain file:

For reference, the configuration can be seen in the CMake GUI:

CMake GUI showing zlib variables configured by Vcpkg.

Build the project:

Note that the required DLLs, zlibd1.dll in this example, are automatically copied to the output directory.

Run the program:

How it works

  • Each library in the Vcpkg ecosystem contains a portfile—a CMake script—that is responsible for fetching sources or binaries, configuring builds, and installing headers and libraries into the correct locations. See zlib/portfile.cmake for an example.
  • Because portfiles are CMake scripts, there’s no inherent restriction on which build system libraries can use.
  • Vcpkg’s CMake toolchain file and Visual Studio integration configure the environment so that the installed headers and libraries are available when building projects.
  • Based on the specified CMake generator, the vcpkg.cmake toolchain file determines the target architecture and platform and updates CMAKE_PREFIX_PATH and CMAKE_LIBRARY_PATH so that the find_package and find_library CMake commands locate the appropriate config files and libraries. Additionally, it overrides add_executable to add a POST_BUILD step that copies dependent shared libraries to the output directory alongside the executable.

Building static libraries

By default, Vcpkg builds dynamic libraries. To build static libraries, specify the --triplet x64-windows-static  option when running vcpkg install. Alternatively, you can set this value in the VCPKG_DEFAULT_TRIPLET environment variable.

When configuring a project to use static libraries, it’s currently necessary to explicitly specify the static triplet, like: -DVCPKG_TARGET_TRIPLET:STRING=x64-windows-static. Additionally, your project should be configured to use the static C runtime library.

Kitware packages

The Visualization Toolkit (VTK) and the Insight Toolkit (ITK) are already available through Vcpkg.

Conclusion

In this post we introduced Vcpkg and showed how to install libraries using Vcpkg. Additionally, we provided an example of a CMake-based project that uses a library installed through Vcpkg.

Vcpkg provides a convenient way to install and use open source C and C++ libraries on Windows. If you’re building a project that depends on more than a few libraries, using Vcpkg might save you some time.

4 Responses to Vcpkg: A tool to build open source libraries on Windows

  1. Anton says:

    Hi! Thank you for such a great article. One small detail could be fixed though: “U+2013 : EN DASH”(–) is used instead of double “U+002D : HYPHEN-MINUS”(–), which prevents code from executed properly (when copy-pasted).

  2. Jean-Christophe Fillion-Robin says:

    Thanks Anton, we converted the examples and references to variables and command line arguments to be in fixed font. Let us know if that works better.

    It also look like there is an issue with the rendering of “greater than” and “smaller than” in the examples, this will fix fixed shortly.

  3. Jean-Christophe Fillion-Robin says:

    Formatting issues have been addressed.

Questions or comments are always welcome!

X