Switch branches/tags
dev/alkarata/bootstrapOutDir dev/alkarata/cmake3.12.3 dev/alkarata/cmake3.12.4 dev/alkarata/cpprestsdk dev/alkarata/rangev3upstream dev/alkarata/rangev3 dev/alkarata/sha512sum dev/alkarata/test dev/alkarata/testbranch dev/alkarata/vcpkgbasesync dev/alkarata/2018.06.13/gl3w dev/alkarata/2018.06.19/cmake dev/alkarata/3450 dev/alkarata/4041/a dev/alkarata/4041/20180808_182535 dev/alkarata/4114/20180910_154915 dev/alkarata/4165/20180829_145334 dev/alkarata/4165/20180906_170752 dev/alkarata/4165/20180906_170813 dev/alkarata/4169/20180829_200808 dev/alkarata/4170/20180829_171434 dev/alkarata/4187/20180829_200822 dev/alkarata/4190/20180830_123136 dev/alkarata/4190/20180830_145314 dev/alkarata/4190/20180831_171631 dev/alkarata/4190/20180904_190259 dev/alkarata/4190/20180905_150623 dev/alkarata/4204/20180831_143301 dev/alkarata/4208/20180831_143338 dev/alkarata/4208/20180904_190545 dev/alkarata/4209/20180831_154524 dev/alkarata/4211/20180904_190613 dev/alkarata/4214/20180904_190636 dev/alkarata/4217/20180904_190650 dev/alkarata/4220/20180904_190759 dev/alkarata/4226/20180904_190834 dev/alkarata/4232/20180905_154003 dev/alkarata/4246/20180907_150045 dev/alkarata/4250/20180910_155201 dev/alkarata/4260/1 dev/alkarata/4260/20180910_234932 dev/alkarata/4260/20180911_020632 dev/alkarata/4260/20180911_125158 dev/alkarata/4260/20180911_125218 dev/alkarata/4280/20180924_164053 dev/alkarata/4283/20180924_164038 dev/alkarata/4293/20180924_163954 dev/alkarata/4321/20180924_161910 dev/alkarata/4321/20180924_163851 dev/alkarata/4325/20180926_235624_UTC dev/alkarata/4329/20180926_235716_UTC dev/alkarata/4346/20180926_221043_UTC dev/alkarata/4347/20180926_011833_UTC dev/alkarata/4385/20181004_043053_UTC dev/alkarata/4635 dev/philc/fix_regressions dev/philc/3425 dev/philc/4260 dev/philc/4617 dev/philc/4734 dev/philc/4759 dev/philc/4761 dev/philc/4831 dev/philc/4850 dev/philc/4853 dev/philc/4854 dev/philc/4855 dev/philc/4858 dev/philc/4860 dev/philc/4863 dev/philc/4867 dev/philc/4873 dev/philc/4874 dev/philc/4881 dev/philc/4889 dev/philc/4891 dev/philc/4894 dev/philc/4898 dev/philc/4900 dev/philc/4903 dev/philc/4912 dev/philc/4914 dev/roschuma/android dev/roschuma/bde dev/roschuma/boost-v120 dev/roschuma/cgal dev/roschuma/cpprestsdk dev/roschuma/date dev/roschuma/dependencies-rework dev/roschuma/enable-export-dot-cmake dev/roschuma/geos dev/roschuma/glad-egl dev/roschuma/glfw3 dev/roschuma/glib dev/roschuma/google-cloud-cpp dev/roschuma/ice dev/roschuma/improve-test-cmake dev/roschuma/itk dev/roschuma/libuv dev/roschuma/llvm6 dev/roschuma/openal-soft dev/roschuma/opencv-use-external-ffmpeg dev/roschuma/openssl-debug-suffix dev/roschuma/openssl-winsdk-2828 dev/roschuma/openssl dev/roschuma/optional dev/roschuma/opus dev/roschuma/osg-cleanup dev/roschuma/osgearth dev/roschuma/parser dev/roschuma/prs dev/roschuma/qca dev/roschuma/rapidjson dev/roschuma/realsense2 dev/roschuma/remove-where-exe dev/roschuma/ros2 dev/roschuma/sdl2-image dev/roschuma/sdl2pp dev/roschuma/sfml dev/roschuma/soci dev/roschuma/spdlog dev/roschuma/theia dev/roschuma/updates dev/roschuma/upgrades dev/roschuma/vcpkg-refactor dev/roschuma/x264 dev/roschuma/xerces-c dev/roschuma/zstd dev/roschuma/3464 dev/roschuma/3932 dev/roschuma/4005 dev/roschuma/4209 dev/roschuma/4312 dev/roschuma/4351 dev/roschuma/4385 dev/roschuma/4472 dev/roschuma/4488 dev/roschuma/4493 dev/roschuma/4547 dev/roschuma/4550 dev/roschuma/4574 dev/roschuma/4575 dev/roschuma/4601 dev/roschuma/4617 dev/roschuma/4624 dev/roschuma/4652 dev/roschuma/4661 dev/roschuma/4680 dev/roschuma/4684 dev/roschuma/4688-2 dev/roschuma/4722 dev/roschuma/4731 dev/roschuma/4774 dev/roschuma/4777-master dev/roschuma/4784 dev/roschuma/4794 dev/roschuma/4803 dev/roschuma/4810 dev/roschuma/4814 dev/roschuma/4822 dev/roschuma/4825 dev/roschuma/4832 dev/roschuma/4833 dev/roschuma/4838 dev/roschuma/4841 dev/roschuma/4842 dev/roschuma/4844 dev/roschuma/4845 dev/roschuma/4846 dev/roschuma/4847 dev/roschuma/4849 dev/roschuma/4854 dev/roschuma/4860 dev/roschuma/4861 dev/roschuma/4876 dev/roschuma/4880 dev/roschuma/4883 dev/roschuma/4884 dev/roschuma/4898 dev/roschuma/4905 dev/roschuma/4916 dev/roschuma/4917 dev/roschuma/4918 dev/roschuma/4920 dev/roschuma/4927 dev/roschuma/4938 dev/roschuma/4939 dev/roschuma/4941 dev/roschuma/4944 dev2/alkarata/llvm7 disable-release-paths-in-debug jumpinjackie-port-gdal-use-mariadb master
Nothing to show
Find file Copy path
56c94a8 Nov 15, 2018
3 contributors

Users who have contributed to this file

@ras0219-msft @GitYangYang @TartanLlama
144 lines (106 sloc) 7.04 KB

Buildsystem Integration

Vcpkg offers many ways to integrate into your build so you can do what's right for your project. There are two main categories of integration:

Each integration style has heuristics to deduce the correct triplet. This can be overridden using a common method based on your buildsystem.

Integrate Command

These link your project(s) to a specific copy of Vcpkg on your machine so any updates or new package installations will be instantly available for the next build of your project.

User-wide for MSBuild (Recommended for Open Source MSBuild projects)

vcpkg integrate install

This will implicitly add Include Directories, Link Directories, and Link Libraries for all packages installed with Vcpkg to all VS2015 and VS2017 MSBuild projects. We also add a post-build action for executable projects that will analyze and copy any DLLs you need to the output folder, enabling a seamless F5 experience.

For the vast majority of libraries, this is all you need to do -- just File -> New Project and write code! However, some libraries perform conflicting behaviors such as redefining main(). Since you need to choose per-project which of these conflicting options you want, you will need to add those libraries to your linker inputs manually.

Here are some examples, though this is not an exhaustive list:

  • Gtest provides gtest, gmock, gtest_main, and gmock_main
  • SDL2 provides SDL2main
  • SFML provides sfml-main
  • Boost.Test provides boost_test_exec_monitor

To get a full list for all your installed packages, run vcpkg owns manual-link.

CMake toolchain file (Recommended for Open Source CMake projects)

cmake ../my/project -DCMAKE_TOOLCHAIN_FILE=C:\vcpkg\scripts\buildsystems\vcpkg.cmake

Projects configured with the Vcpkg toolchain file will have the appropriate Vcpkg folders added to the cmake search paths. This makes all libraries available to be found through find_package(), find_path(), and find_library().

See Installing and Using Packages Example: sqlite for a fully worked example using our CMake toolchain.

Note that we do not automatically add ourselves to your compiler include paths. To use a header-only library, simply use find_path(), which will correctly work on all platforms:

# To find and use catch
find_path(CATCH_INCLUDE_DIR NAMES catch.hpp PATH_SUFFIXES catch2)
Using an environment variable instead of a command line option

The CMAKE_TOOLCHAIN_FILE setting simply must be set before the project() directive is first called. This means that you can easily read from an environment variable to avoid passing it on the configure line:

  set(CMAKE_TOOLCHAIN_FILE "${VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
      CACHE STRING "")

project(myproject CXX)
Using multiple toolchain files

To use an external toolchain file with a project using vcpkg, you can set the cmake variable VCPKG_CHAINLOAD_TOOLCHAIN_FILE on the configure line:

cmake ../my/project \
   -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake \

Linking NuGet file

We also provide individual VS project integration through a NuGet package. This will modify the project file, so we do not recommend this approach for open source projects.

PS D:\src\vcpkg> .\vcpkg integrate project
Created nupkg: D:\src\vcpkg\scripts\buildsystems\vcpkg.D.src.vcpkg.1.0.0.nupkg

With a project open, go to Tools->NuGet Package Manager->Package Manager Console and paste:
    Install-Package vcpkg.D.src.vcpkg -Source "D:/src/vcpkg/scripts/buildsystems"

Note: The generated NuGet package does not contain the actual libraries. It instead acts like a shortcut (or symlink) to the vcpkg install and will "automatically" update with any changes (install/remove) to the libraries. You do not need to regenerate or update the NuGet package.

Manual compiler settings

Libraries are installed into the installed\ subfolder, partitioned by architecture (e.g. x86-windows):

  • The header files are installed to installed\x86-windows\include
  • Release .lib files are installed to installed\x86-windows\lib or installed\x86-windows\lib\manual-link
  • Release .dll files are installed to installed\x86-windows\bin
  • Debug .lib files are installed to installed\x86-windows\debug\lib or installed\x86-windows\debug\lib\manual-link
  • Debug .dll files are installed to installed\x86-windows\debug\bin

See your build system specific documentation for how to use prebuilt binaries.

Generally, to run any produced executables you will also need to either copy the needed DLL files to the same folder as your executable or prepend the correct bin\ directory to your path.

Export Command

This command creates a shrinkwrapped archive containing a specific set of libraries (and their dependencies) that can be quickly and reliably shared with build servers or other users in your organization.

  • --nuget: NuGet package (Recommended for MSBuild projects)
  • --zip: Zip archive
  • --7zip: 7Zip archive (Recommended for CMake projects)
  • --raw: Raw, uncompressed folder

Each of these have the same layout, which mimics the layout of a full vcpkg:

  • installed\ contains the installed package files
  • scripts\buildsystems\vcpkg.cmake is a toolchain file suitable for use with CMake

Additionally, NuGet packages will contain a build\native\vcpkg.targets that integrates with MSBuild projects.

Please also see our blog post for additional examples.

Triplet selection

Every integration mechanism besides manually adding the folders will deduce a triplet for your project as one of:

  • x86-windows
  • x64-windows
  • x86-uwp
  • x64-uwp
  • arm-uwp

With MSBuild

You can see the automatically deduced triplet by setting your MSBuild verbosity to Normal or higher:

Shortcut: Ctrl+Q "build and run"

Tools -> Options -> Projects and Solutions -> Build and Run -> MSBuild project build output verbosity

To override the automatically chosen triplet, you can specify the MSBuild property VcpkgTriplet in your .vcxproj. We recommend adding this to the Globals PropertyGroup.

<PropertyGroup Label="Globals">
  <!-- .... -->
  <VcpkgTriplet Condition="'$(Platform)'=='Win32'">x86-windows-static</VcpkgTriplet>
  <VcpkgTriplet Condition="'$(Platform)'=='x64'">x64-windows-static</VcpkgTriplet>

With CMake

Simply set VCPKG_TARGET_TRIPLET on the configure line.

cmake ../my/project -DVCPKG_TARGET_TRIPLET=x64-windows-static -DCMAKE_TOOLCHAIN_FILE=...