Edit

Tutorial: Install a dependency from the command line

  • Article

Tip

See "Install a dependency from a manifest file" for the recommended method of installing your dependencies.

Warning

Some vcpkg features are not available in classic mode.

vcpkg has two operation modes: classic mode, and manifest mode. This article describes how to install packages using classic mode. For most users we recommend using manifest mode instead.

In classic mode, you use vcpkg as a command-line interface to install your dependencies in a common installation directory. Usually, located in %VCPKG_ROOT%/installed, where %VCPKG_ROOT% is the vcpkg's installation directory.

In this tutorial, you will learn to:

Prerequisites

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

1 - Create a project

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.

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

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

To install these packages use the vcpkg install command.

vcpkg install cxxopts fmt range-v3

$ ./vcpkg install cxxopts fmt range-v3
Computing installation plan...
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.
(omitted)
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)

4 - Build the project

Important

Make sure that the triplet of your installed packages matches your project's configuration. Use x64-windows or x64-windows-static for your 64-bit projects and x86-windows or x86-windows-static for your 32-bit projects.

With system-wide integration enabled, just run msbuild to build the project:

PS D:\projects\manifest-example> msbuild
MSBuild version 17.7.0-preview-23319-02+6829506b8 for .NET Framework
Build started 8/13/2023 3:07:36 PM.

Project "D:\projects\manifest-example\manifest-example.sln" on node 1 (default targets).
ValidateSolutionConfiguration:
  (omitted)
PrepareForBuild:
  (omitted)
InitializeBuildStatus:
  (omitted)
ComputeStdModulesCompileInputs:
  (omitted)
SetModuleDependencies:
VcpkgTripletSelection:
  Using triplet "x64-windows" from "D:\vcpkg\installed\x64-windows\"
  Using normalized configuration "Debug"
ClCompile:
  (omitted)
Link:
  (omitted)
AppLocalFromInstalled:
  pwsh.exe -ExecutionPolicy Bypass -noprofile -File "D:\vcpkg\scripts\buildsystems\msbuild\applocal.ps1" "D:\projects\manifest-example\x64\Debug\manifest-example.exe"
   "D:\vcpkg\installed\x64-windows\debug\bin" "x64\Debug\manifest-example.tlog\manifest-example.write.1u.tlog" "x64\Debug\vcpkg.applocal.log"
  D:\projects\manifest-example\x64\Debug\fmtd.dll
FinalizeBuildStatus:
  Deleting file "x64\Debug\manifest-example.tlog\unsuccessfulbuild".
  Touching "x64\Debug\manifest-example.tlog\manifest-example.lastbuildstate".
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 tutorial, you installed dependencies for a simple project using vcpkg as a command-line interface.

Here are some additional tasks to try next: