How to Use vcpkg With CMake On Windows

4 minute read

Introduction

If you do any sort of C++ development on Windows, then you know that library/package management can be quite a pain at times (ever built OpenCV from source? How about boost?). There has never really been a good package manager on windows like what you would find on linux (i.e. pacman); but now there is vcpkg!

So what makes vcpkg great? Well it’s basically a low key package manager for Windows and best of all, it’s built by Microsoft and is open source. In fact Microsoft has pushed themselves to the forefront of open source software and it is great. You can even now look at and contribute to the Calculator application that ships with Windows 10.

How to Use It?

Follow the instructions in the readme of the vcpkg Github repo to get started. You basically just clone the repo and then run a .bat file that installs and builds the vcpkg executable. You can now install packages which will be automatically downloaded and built for you using Visual Studio 2017 (assuming you have it installed). You can also specify what version of visual studio you want to use to build the packages.

Installing a Package

  • Open a PowerShell window and navigate to the directory that contains vcpkg.
  • Find the package you want to install using ./vcpkg search <package name>.
  • If your package is listed, install it with ./vcpkg install <package name>.

And that’s pretty much it. But there are a few things to be aware of. One in particular is that the default build type is x86 (32 bit). To change this you can set an environment variable or use what Microsoft calls triplets. If you do want to change the default triplet, you will need to change the VCPKG_DEFAULT_TRIPLET environment variable. I have mine set to x64-windows.

To use the triplets, when intalling a package you just need to append another argument to your command:

./vcpkg install <package name>:x64-windows

or

./vcpkg install <package name> --triplet x64-windows.

To see the available triplets, go to the base vcpkg directory and open the folder appropriately named triplets. In there you’ll find a bunch of .cmake files that specify different build types. If you open one up, you can see the names of the variables that vcpkg uses. One of interest is VCPKG_TARGET_ARCHITECTURE. If you wnat to change your default build architecture, this is the variable name you want to use in your environment variables.

Custom Triplet

If you open up the x64-windows.cmake triplet, you should see the following:

set(VCPKG_TARGET_ARCHITECTURE x64)
set(VCPKG_CRT_LINKAGE dynamic)
set(VCPKG_LIBRARY_LINKAGE dynamic)

So by default, CRT linkage is dynamic (i.e. via *.dll files) and so is the library linkage. To build static libs you would use the x64-windows-static triplet which will change the linkage to static. The cool thing about vcpkg is that you can create your own, custom triplets. So let’s say you wanted to use Visual Studio 2013 instead of 2017. You could make a new cmake file called x64-vs2013-dynamic.cmake and put the following into it:

set(VCPKG_TARGET_ARCHITECTURE x64)
set(VCPKG_CRT_LINKAGE dynamic)
set(VCPKG_LIBRARY_LINKAGE dynamic)
set(VCPKG_PLATFORM_TOOLSET v120)

If you have Visual Studio 2013 properly installed on your machine, you can now install packages with vcpkg using Visual Studio 2013. To do so you just install packages as before, but use your custom triplet instead: ./vcpkg install <package name>:x64-vs2013-dynamic.

Using Packages Installed with vcpkg

One thing I struggled with is how to use vcpkg installs in my own projects. vcpkg thankfully integrates seamlessly with CMake. To use vcpkg all you have to do is pass in the CMAKE_TOOLCHAIN_FILE variable and point it to the cmake file that is found at <vcpkg directory>/scripts/buildsystems/vcpkg.cmake. All together you’d have something like: cmake "-DCMAKE_TOOLCHAIN_FILE=<path to toolchain file>".

If you use the CMake gui, then you can still specify the toolchain file; you just have to do it when you first configure the project. To do so, open the CMake gui and select your source and build directories. As an example, I’m going to configure the delaunaypp project I’ve been working on. Then click Configure. When you do, you should get a window like the one below:

cmake-gui-create-build-dir

Click yes and then you’ll be prompted with the following window:

cmake-gui-select-generator

In the radio button options under the generator selector, be sure to select Specify toolchain file for cross-compiling and then hit Next.

You’ll be presented with another window where you can specify the full path to the toolchain file (i.e. the same vcpkg.cmake file specified above).

cmake-gui-specify-toolchain

And that’s it! Now you can use find_package() in cmake like you normally would, but now the installed package locations from vcpkg will also be searched and packages that you have installed should be found automatically.

Conclusion

I hope this short article helped you get started quickly with using vcpkg and hopefully you learned something! I definitely recommend using vcpkg since it has the potential to standardize your package management for larger projects that have a lot of dependencies. Feel free to check out my other blog posts and follow so you don’t miss one!

Leave a Comment

Your email address will not be published. Required fields are marked *

Loading...