vcpkg for C++ | Microsoft Package Manager, Manifest & CMake Toolchain

What is vcpkg? why you need it

Problem Scenario: The Pain of Installing Libraries

Problem: To install a C++ library on Windows, you need to download the source from the official site, build it with Visual Studio, and add the header/library path to your project. On Linux it’s easy to install with apt, but on Windows it’s a manual process every time.

Solution: vcpkg is a C++ package manager by Microsoft that installs libraries in one line, like ./vcpkg install boost, and automatically integrates with CMake. Windows, Linux, and macOS can all be used with the same command.

flowchart LR
    subgraph install["vcpkg install"]
        cmd["./vcpkg install fmt"]
    end
    subgraph build["Build"]
        download["Download source"]
        compile["compile"]
        install_lib["installation"]
    end
    subgraph cmake["CMake Integration"]
        toolchain["vcpkg.cmake"]
        find["find_package(fmt)"]
    end
    cmd --> download
    download --> compile
    compile --> install_lib
    install_lib --> toolchain
    toolchain --> find

---

index

1. vcpkg installation and basic use
2. Manifest mode (vcpkg.json)
3. CMake integration
4. Version management
5. Frequently occurring problems and solutions
6. Production Patterns
7. Complete example: multi-library project

---

1. vcpkg installation and basic use

installation

# clone
git clone https://github.com/microsoft/vcpkg
cd vcpkg

# bootstrap
./bootstrap-vcpkg.sh  # Linux/macOS
./bootstrap-vcpkg.bat # Windows

# Add PATH (optional)
export PATH=$PATH:$(pwd)

Basic commands

# Package search
./vcpkg search boost

# Install package
./vcpkg install fmt
./vcpkg install boost-filesystem

# List of installed packages
./vcpkg list

# Remove package
./vcpkg remove fmt

# update
git pull
./bootstrap-vcpkg.sh

Triplet (Build Settings)

# x64 Windows (dynamic link)
./vcpkg install fmt:x64-windows

# x64 Windows (static link)
./vcpkg install fmt:x64-windows-static

# Linux
./vcpkg install fmt:x64-linux

# macOS
./vcpkg install fmt:x64-osx

---

2. Manifest mode (vcpkg.json)

Create vcpkg.json

{
  "name": "myproject",
  "version": "1.0.0",
  "dependencies": [
    "fmt",
    "boost-filesystem",
    "spdlog",
    "openssl"
  ]
}

Conditional dependencies

{
  "name": "myproject",
  "version": "1.0.0",
  "dependencies": [
    "fmt",
    {
      "name": "openssl",
      "platform": "!windows"
    }
  ]
}

features

{
  "name": "myproject",
  "version": "1.0.0",
  "dependencies": [
    {
      "name": "boost",
      "features": ["filesystem", "system"]
    }
  ]
}

---

3. CMake integration

Method 1: CMAKE_TOOLCHAIN_FILE

# build
cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake
cmake --build build

Method 2: Environment variables

export VCPKG_ROOT=/path/to/vcpkg
cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake

Method 3: Include in CMakeLists.txt

# CMakeLists.txt
set(CMAKE_TOOLCHAIN_FILE "${CMAKE_SOURCE_DIR}/vcpkg/scripts/buildsystems/vcpkg.cmake"
    CACHE STRING "Vcpkg toolchain file")

cmake_minimum_required(VERSION 3.20)
project(MyProject)

find_package(fmt REQUIRED)
find_package(Boost REQUIRED COMPONENTS filesystem)

add_executable(myapp main.cpp)
target_link_libraries(myapp PRIVATE fmt::fmt Boost::filesystem)

---

4. version control

Specify version in vcpkg.json

{
  "name": "myproject",
  "version": "1.0.0",
  "dependencies": [
    {
      "name": "fmt",
      "version>=": "9.0.0"
    },
    {
      "name": "boost",
      "version>=": "1.78.0"
    }
  ],
  "builtin-baseline": "2023-11-20"
}

vcpkg-configuration.json

{
  "default-registry": {
    "kind": "git",
    "repository": "https://github.com/microsoft/vcpkg",
    "baseline": "2023-11-20"
  }
}

---

5. Frequently occurring problems and solutions

Issue 1: Package build failure

Symptom: Error: Building package boost:x64-windows failed.

Cause: Build tools (Visual Studio, GCC, etc.) are missing or have incorrect versions.

# Solution 1: Check build tools
# Windows: Install Visual Studio 2019+
# Linux: Install g++
sudo apt install build-essential

# Solution 2: Check logs
./vcpkg install boost --debug

Issue 2: CMake not finding package

Symptom: find_package(fmt) failed.

Cause: CMAKE_TOOLCHAIN_FILE is not specified.

# ❌ Incorrect use
cmake ..

# ✅ Correct use
cmake .. -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake

Problem 3: Triplet mismatch

Symptom: Link error (LNK2019, undefined reference).

Cause: When installing vcpkg, the triplet and CMake build settings are different.

# Match
./vcpkg install fmt:x64-windows-static
cmake .. -DCMAKE_TOOLCHAIN_FILE=... -DVCPKG_TARGET_TRIPLET=x64-windows-static

Issue 4: Manifest mode not enabled

Symptom: There is vcpkg.json, but it is not automatically installed.

Cause: vcpkg does not recognize the manifest when building CMake.

# Solution: Manual installation
./vcpkg install --manifest-root=. --x-install-root=build/vcpkg_installed

---

6. production pattern

Pattern 1: Include vcpkg as a Git submodule

# Add vcpkg as a submodule
git submodule add https://github.com/microsoft/vcpkg external/vcpkg
git submodule update --init --recursive

# bootstrap
cd external/vcpkg
./bootstrap-vcpkg.sh

# CMakeLists.txt
set(CMAKE_TOOLCHAIN_FILE "${CMAKE_SOURCE_DIR}/external/vcpkg/scripts/buildsystems/vcpkg.cmake")

Pattern 2: CI/CD integration

# .github/workflows/build.yml
name: Build

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: recursive
      
      - name: Bootstrap vcpkg
        run: |
          cd external/vcpkg
          ./bootstrap-vcpkg.sh
      
      - name: Install dependencies
        run: |
          ./external/vcpkg/vcpkg install --manifest-root=.
      
      - name: Build
        run: |
          cmake -B build -DCMAKE_TOOLCHAIN_FILE=external/vcpkg/scripts/buildsystems/vcpkg.cmake
          cmake --build build

Pattern 3: Binary caching

# Enable binary cache (reduce build time)
export VCPKG_BINARY_SOURCES="clear;files,/path/to/cache,readwrite"

# or NuGet cache
export VCPKG_BINARY_SOURCES="clear;nuget,https://nuget.company.com,readwrite"

---

7. Complete example: web server

vcpkg.json

{
  "name": "webserver",
  "version": "1.0.0",
  "dependencies": [
    "boost-asio",
    "boost-beast",
    "fmt",
    "spdlog",
    "nlohmann-json"
  ]
}

CMakeLists.txt

cmake_minimum_required(VERSION 3.20)
project(WebServer VERSION 1.0.0)

set(CMAKE_CXX_STANDARD 20)

find_package(Boost REQUIRED COMPONENTS system)
find_package(fmt REQUIRED)
find_package(spdlog REQUIRED)
find_package(nlohmann_json REQUIRED)

add_executable(webserver
    src/main.cpp
    src/server.cpp
    src/request_handler.cpp
)

target_link_libraries(webserver PRIVATE
    Boost::system
    fmt::fmt
    spdlog::spdlog
    nlohmann_json::nlohmann_json
)

Build

# vcpkg bootstrap (only the first time)
cd vcpkg
./bootstrap-vcpkg.sh

# Build the project
cd ..
cmake -B build -DCMAKE_TOOLCHAIN_FILE=vcpkg/scripts/buildsystems/vcpkg.cmake
cmake --build build -j$(nproc)

---

organize

concept	Description
vcpkg	Microsoft C++ Package Manager
Manifest Mode	Specify dependencies with vcpkg.json
Triplet	Build settings (x64-windows, x64-linux, etc.)
CMAKE_TOOLCHAIN_FILE	CMake integration
Binary Caching	Reduce build time

vcpkg installs C++ libraries with simple commands and automatically integrates with CMake, making cross-platform development easy.

---

FAQ

Q1: vcpkg vs Conan?

A: vcpkg is simple to use and has good Windows integration. Conan is flexible and easy to build a private server. Choose one that suits your team environment.

Q2: What is manifest mode?

A: If you specify dependencies in vcpkg.json, vcpkg will automatically install them when building CMake. Team members only need to install vcpkg and do not need to run the vcpkg install command separately.

Q3: Why are triplets needed?

A: The same package has different build settings, such as Dynamic/Static Link and Debug/Release. This is specified as a triplet. x64-windows is dynamic linking, x64-windows-static is static linking.

Q4: Where is the vcpkg cache?

A: There are installed packages in vcpkg/installed/ and build intermediate files in vcpkg/buildtrees/. You can clean up old packages with ./vcpkg remove --outdated.

Q5: How about binary caching?

A: By specifying the cache location with the VCPKG_BINARY_SOURCES environment variable, you can significantly reduce build time by reusing built packages. Placing a team shared cache on NuGet or a file server allows all team members to build quickly.

Q6: What are vcpkg learning resources?

A:

• vcpkg official document
• vcpkg GitHub
• vcpkg package list

One-line summary: vcpkg makes it easy to install C++ libraries and integrate them into CMake. Next, it would be a good idea to read CMake Guide.

---

Good article to read together (internal link)

Here’s another article related to this topic.

• C++ Conan Complete Guide | Modern C++ package management
• C++ CMake Complete Guide | Cross-platform build·latest CMake 3.28+ features·presets·modules
• C++ CMake find_package complete guide | External library integration

Practical tips

These are tips that can be applied right away in practice.

Debugging tips

• If you run into a problem, check the compiler warnings first.
• Reproduce the problem with a simple test case

Performance Tips

• Don’t optimize without profiling
• Set measurable indicators first

Code review tips

• Check in advance for areas that are frequently pointed out in code reviews.
• Follow your team’s coding conventions

---

Practical checklist

This is what you need to check when applying this concept in practice.

Before writing code

• Is this technique the best way to solve the current problem?
• Can team members understand and maintain this code?
• Does it meet the performance requirements?

Writing code

• Have you resolved all compiler warnings?
• Have you considered edge cases?
• Is error handling appropriate?

When reviewing code

• Is the intent of the code clear?
• Are there enough test cases?
• Is it documented?

Use this checklist to reduce mistakes and improve code quality.

---

Keywords covered in this article (related search terms)

This article will be helpful if you search for C++, vcpkg, package, library, tools, microsoft, etc.

---

Related articles

• C++ Conan Complete Guide | Modern C++ package management
• C++ Benchmarking |
• C++ CMake find_package complete guide | External library integration
• C++ CMake Targets Complete Guide | Target-based build system
• C++ CMake Complete Guide | Cross-platform build·latest CMake 3.28+ features·presets·modules