Edit

Tutorial: Install a dependency from a manifest file

  • Article

vcpkg has two operation modes: classic mode and manifest mode. This article describes how to install packages using manifest mode, which is the recommended workflow for most users.

In manifest mode, you declare your project's direct dependencies in a manifest file named vcpkg.json.

Manifest files have their own vcpkg_installed directory where they install dependencies, unlike classic mode, where all packages are installed in a common %VCPKG_ROOT%/installed directory. Therefore, each project can have its own manifest and its own set of dependencies that do not conflict with other projects' dependencies.

Manifest mode is also required to use advanced features like versioning and custom registries.

In this tutorial, you will learn how to:

Prerequisites

  • vcpkg
  • A terminal
  • A code editor
  • A C++ compiler
  • (Optional) CMake or MSBuild

1 - Create a project with a manifest

In a new folder, create a source file named main.cxx with these contents:

#include <cxxopts.hpp>
#include <fmt/format.h>
#include <range/v3/view.hpp>

namespace view = ranges::views;

int fib(int x)
{
  int a = 0, b = 1;

  for (int it : view::repeat(0) | view::take(x))
  {
    (void)it;
    int tmp = a;
    a += b;
    b = tmp;
  }

  return a;
}

int main(int argc, char **argv)
{
  cxxopts::Options options("fibo", "Print the fibonacci sequence up to a value 'n'");
  options.add_options()("n,value", "The value to print to", cxxopts::value<int>()->default_value("10"));

  auto result = options.parse(argc, argv);
  auto n = result["value"].as<int>();

  for (int x : view::iota(1) | view::take(n))
  {
    fmt::print("fib({}) = {}\n", x, fib(x));
  }
}

The code references the open-source libraries: cxxopts, fmt, and range-v3; which are all available in the vcpkg public registry at https://github.com/Microsoft/vcpkg.

To declare these dependencies, create a file named vcpkg.json in the same directory as your project:

vcpkg.json:

{
  "dependencies": [
    "cxxopts",
    "fmt",
    "range-v3"
  ]
}

You only need to specify your direct dependencies in the "dependencies" list. When it runs, vcpkg resolves and installs any required transitive dependencies.

2 - Integrate vcpkg with your build system

In this step we show you how to integrate vcpkg with CMake or MSBuild, so that your project dependencies get automatically installed or restored whenever you build the project.

If you're using a different build system, skip to the next step: Install dependencies.

Learn more about using vcpkg from MSBuild

To use vcpkg in your MSBuild projects, run the following command:

vcpkg integrate install

You only need to run the vcpkg integrate install command the first time you want to enable MSBuild integration. This enables MSBuild integration for all your existing and future projects. Use vcpkg integrate remove to remove MSBuild system-wide integration.

This integration method automatically adds vcpkg-installed packages to the following project properties: Include Directories, Link Directories, and Link Libraries. Additionally, this creates a post-build action that ensures that any required DLLs are copied into the build output folder. This works for all solutions and projects using Visual Studio 2015 or newer.

3 - Install dependencies

If you're using CMake or MSBuild and followed the previous step, you can skip ahead to the next step: Build the project.

If you're using a different build system or want to install the dependencies manually, all you need to do is run vcpkg install in the directory containing your manifest file.

PS D:\projects\manifest-example> vcpkg install
Detecting compiler hash for triplet x64-windows...
The following packages will be built and installed:
    cxxopts:x64-windows -> 3.1.1
    fmt:x64-windows -> 10.0.0
    range-v3:x64-windows -> 0.12.0#1
  * vcpkg-cmake:x64-windows -> 2023-05-04
  * vcpkg-cmake-config:x64-windows -> 2022-02-06#1
Additional packages (*) will be modified to complete this operation.
Installing 1/5 vcpkg-cmake-config:x64-windows...
Installing 2/5 vcpkg-cmake:x64-windows...
Installing 3/5 cxxopts:x64-windows...
Installing 4/5 fmt:x64-windows...
Installing 5/5 range-v3:x64-windows...
Total install time: 48 s
cxxopts provides CMake targets:

    # this is heuristically generated, and may not be correct
    find_package(cxxopts CONFIG REQUIRED)
    target_link_libraries(main PRIVATE cxxopts::cxxopts)

The package fmt provides CMake targets:

    find_package(fmt CONFIG REQUIRED)
    target_link_libraries(main PRIVATE fmt::fmt)

    # Or use the header-only version
    find_package(fmt CONFIG REQUIRED)
    target_link_libraries(main PRIVATE fmt::fmt-header-only)

range-v3 provides CMake targets:

    # this is heuristically generated, and may not be correct
    find_package(range-v3 CONFIG REQUIRED)
    target_link_libraries(main PRIVATE range-v3::meta range-v3::concepts range-v3::range-v3)

When the command finishes, all built packages will be present in a vcpkg_installed directory. The specific location of this directory depends on your build system; usually, inside the build system's default output folder, or next to your vcpkg.json file.

4 - Build the project

By default, manifest mode is disabled in MSBuild projects.

To enable manifests in your project, set the VcpkgEnableManifest property in your .vcxproj file:

<PropertyGroup Label="Vcpkg">
  <VcpkgEnableManifest>true</VcpkgEnableManifest>
</PropertyGroup>

Alternatively, you can enable manifest mode in your MSBuild call by passing msbuild /p:VcpkgEnableManifest=true as a parameter.

PS D:\projects\manifest-example> msbuild /p:VcpkgEnableManifest=true
MSBuild version 17.7.0-preview-23319-02+6829506b8 for .NET Framework
Build started 8/11/2023 11:29:50 AM.

Project "D:\projects\manifest-example\manifest-example.sln" on node 1 (default targets).
ValidateSolutionConfiguration:
  Building solution configuration "Debug|x64".
Project "D:\projects\manifest-example\manifest-example.sln" (1) is building "D:\projects\manifest-example\manifest-example.vcxproj" (2) on node 1 (default targets).
PrepareForBuild:
  (omitted)
InitializeBuildStatus:
  (omitted)
ComputeStdModulesCompileInputs:
  (omitted)
SetModuleDependencies:
  Creating directory "x64\Debug\manifest.ceffc6eb_MD.tlog\".
VcpkgTripletSelection:
  Using triplet "x64-windows" from "D:\projects\manifest-example\vcpkg_installed\x64-windows\x64-windows\"
  Using normalized configuration "Debug"
VcpkgInstallManifestDependencies:
  Installing vcpkg dependencies to D:\projects\manifest-example\vcpkg_installed\x64-windows\
  Creating directory "D:\projects\manifest-example\vcpkg_installed\x64-windows\".
  "D:\vcpkg\vcpkg.exe" install  --x-wait-for-lock --triplet "x64-windows" --vcpkg-root "D:\vcpkg\" "--x-manifest-root=D:\projects\manifest-example\" "--x-install-root=D:\projects\manifest-example\vcpkg_installed\x64-windows\"
  "D:\vcpkg\vcpkg.exe" install  --x-wait-for-lock --triplet "x64-windows" --vcpkg-root "D:\vcpkg\" "--x-manifest-root=D:\projects\manifest-example\" "--x-install-root=D:\projects\manifest-example\vcpkg_installed\x64-windows\"
  Detecting compiler hash for triplet x64-windows...
  The following packages will be built and installed:
      cxxopts:x64-windows -> 3.1.1
      fmt:x64-windows -> 10.0.0
      range-v3:x64-windows -> 0.12.0#1
    * vcpkg-cmake:x64-windows -> 2023-05-04
    * vcpkg-cmake-config:x64-windows -> 2022-02-06#1
  (omitted)
ClCompile:
  (omitted)
Link:
  (omitted)
AppLocalFromInstalled:
  pwsh.exe -ExecutionPolicy Bypass -noprofile -File "D:\vcpkg\scripts\buildsystems\msbuild\applocal.ps1" "D:\projects\manif
  est-mode-msbuild\x64\Debug\manifest-example.exe" "D:\projects\manifest-example\vcpkg_installed\x64-windows\x64-windows\debug\bin"
  "x64\Debug\manifest.ceffc6eb.tlog\manifest-example.write.1u.tlog" "x64\Debug\vcpkg.applocal.log"
  D:\projects\manifest-example\x64\Debug\fmtd.dll
FinalizeBuildStatus:
  (omitted)
Done Building Project "D:\projects\manifest-example\manifest-example.vcxproj" (default targets).

Done Building Project "D:\projects\manifest-example\manifest-example.sln" (default targets).

Build succeeded.

Next Steps

In this guide, you installed dependencies for a simple project using a manifest file.

Here are some additional tasks to try next:

  • Install packages for custom platforms, compilers, or build architectures using triplets
  • Lock down your versions for repeatable builds using versioning
  • Reuse binaries across local or continuous integration runs using binary caching
  • Manage your private libraries using custom registries