Comprehensive Guide to Vcpkg for C++ Package Management

vcpkg.md

📌 Comprehensive Guide to Vcpkg for C++ Package Management

Disclaimer: ChatGPT generated document.

Vcpkg is a C++ package manager that simplifies dependency management across different platforms and compilers. It integrates well with CMake, MSBuild, and Visual Studio, making it an excellent choice for both Windows and cross-platform development.

---

🔹 1. What is Vcpkg?

✔ Package Manager for C++/C → Simplifies dependency installation
✔ Cross-Platform → Works on Windows, Linux, macOS
✔ Integrates with CMake & MSBuild → Automates library linking
✔ Supports Hundreds of Libraries → OpenSSL, Boost, SDL2, etc.
✔ Uses Prebuilt Binaries → Faster builds

📌 Vcpkg vs Conan

Feature	Vcpkg	Conan
Focus	C++ dependencies	C++ package management
Platforms	Windows, Linux, macOS	Windows, Linux, macOS, embedded
Integration	MSBuild, CMake	CMake, Make, Ninja
Binary Storage	Per-project	Centralized storage (Artifactory)
Use Case	Small to medium projects	Large-scale dependency management

📌 Best For: Windows-based projects, small-to-medium C++ applications.

---

🔹 2. Installing Vcpkg

✅ Windows Installation

git clone https://github.com/microsoft/vcpkg.git
cd vcpkg
.\bootstrap-vcpkg.bat

✅ Linux/macOS Installation

git clone https://github.com/microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh

✔ This installs Vcpkg and sets it up.

📌 Ensure CMake and a compiler (GCC/Clang/MSVC) are installed!

---

🔹 3. Installing a C++ Library

Vcpkg provides precompiled libraries that integrate with CMake and MSBuild.

✅ Install a Single Package

vcpkg install boost

✔ Downloads and installs Boost with all dependencies.

✅ Install Multiple Packages

vcpkg install boost openssl fmt

✅ Install Debug + Release Versions

vcpkg install boost:x64-windows

✔ :x64-windows → Installs both Debug & Release libraries
✔ :x64-windows-static → Installs static libraries
✔ :x64-linux → Installs Linux versions

✅ List Installed Packages

vcpkg list

---

🔹 4. Integrating Vcpkg with CMake

To use Vcpkg in a CMake project, add:

cmake_minimum_required(VERSION 3.10)
project(MyApp)

find_package(Boost REQUIRED)
add_executable(myapp main.cpp)
target_link_libraries(myapp PRIVATE Boost::Boost)

✅ Using the Vcpkg Toolchain

Vcpkg provides a CMake toolchain file for automatic integration.

📌 CMake Build Command:

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

✔ Automatically finds installed libraries!

📌 Example: Installing SDL2 and Using in CMake

vcpkg install sdl2:x64-windows
find_package(SDL2 REQUIRED)
target_link_libraries(myapp PRIVATE SDL2::SDL2)

---

🔹 5. Using Vcpkg in MSBuild (Visual Studio)

To integrate Vcpkg with MSBuild and Visual Studio:

vcpkg integrate install

✔ Automatically links Vcpkg libraries in Visual Studio projects.
✔ Works with .sln and .vcxproj files.

📌 Enable in Visual Studio:

• Open Project Settings → VC++ Directories
• Add $(VCPKG_ROOT)\installed\x64-windows\include

---

🔹 6. Searching for Packages

✅ Find Available Libraries

vcpkg search json

✔ Lists available JSON libraries (e.g., nlohmann-json).

✅ Get Package Information

vcpkg info boost

✔ Shows version, dependencies, and supported platforms.

---

🔹 7. Removing and Updating Packages

✅ Uninstall a Library

vcpkg remove boost

✅ Remove All Installed Packages

vcpkg remove --all

✅ Update Vcpkg and All Packages

git pull
vcpkg update
vcpkg upgrade

✔ Keeps dependencies up to date!

---

🔹 8. Using Vcpkg in CI/CD (GitHub Actions)

To use Vcpkg in GitHub Actions:

📌 .github/workflows/build.yml

name: Build C++ App

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Install Vcpkg
        run: |
          git clone https://github.com/microsoft/vcpkg.git
          cd vcpkg
          ./bootstrap-vcpkg.sh
          ./vcpkg install fmt

      - name: Configure CMake
        run: cmake -B build -DCMAKE_TOOLCHAIN_FILE=$GITHUB_WORKSPACE/vcpkg/scripts/buildsystems/vcpkg.cmake

      - name: Build Project
        run: cmake --build build

✔ Automates Vcpkg setup in CI/CD
✔ Ensures dependencies are installed before building

---

🔹 9. Creating Custom Packages in Vcpkg

If a library is not available in Vcpkg, you can create a custom package.

📌 Steps to Create a Custom Vcpkg Package 1️⃣ Navigate to Vcpkg ports/

cd vcpkg/ports
mkdir mylib

2️⃣ Create CONTROL File:

Source: mylib
Version: 1.0
Description: My custom C++ library

3️⃣ Create portfile.cmake:

vcpkg_from_github(
    OUT_SOURCE_PATH SOURCE_PATH
    REPO myuser/mylib
    REF v1.0
    SHA512 123456...
    HEAD_REF master
)

vcpkg_install_cmake()
vcpkg_fixup_cmake_targets()

4️⃣ Install Custom Package:

vcpkg install mylib

✔ Now mylib can be used like any other Vcpkg package!

---

🔹 10. Optimizing Vcpkg for Large C++ Projects

✅ Enable Binary Caching

To avoid rebuilding packages, enable caching:

vcpkg x-set-binarycache C:/vcpkg_cache

✔ Saves prebuilt libraries for faster installations.

✅ Use a Custom Vcpkg Registry

For private/internal packages, set up a registry:

vcpkg registry add myregistry https://myserver.com/vcpkg

✔ Helps manage in-house libraries.

---

📌 Summary

Feature	Details
What is Vcpkg?	A package manager for C++ dependencies
Best For?	Windows, small-to-medium projects
Installation?	vcpkg install <package>
Integration?	Works with CMake, MSBuild, CI/CD
Binary Caching?	Available for faster builds
Custom Packages?	Can create & host private packages

---

🚀 Next Steps

Would you like:

1️⃣ A real-world project setup using Vcpkg and CMake?
2️⃣ A guide on optimizing Vcpkg for CI/CD pipelines?
3️⃣ A comparison of Vcpkg vs Conan for dependency management?