C/C++使用vcpkg管理跨平台包的最佳实践

# 安装编译工具链
sudo apt update
sudo apt install -y git curl zip unzip tar pkg-config
# 安装 C/C++ 编译器
sudo apt install -y build-essential
# 安装 CMake
sudo apt install -y cmake

验证命令：
$ git --version
$ g++ --version
$ cmake --version

# 1. 克隆 vcpkg 仓库（建议放在用户目录下），如果克隆速度慢可以直接从github上面下载压缩包解压
git clone https://github.com/microsoft/vcpkg.git ~/vcpkg
# 2. 执行引导脚本——编译 vcpkg 自身
# Linux/macOS
~/vcpkg/bootstrap-vcpkg.sh
# Windows (PowerShell)
~/vcpkg/bootstrap-vcpkg.ps1
# 或 cmd
%USERPROFILE%\vcpkg\bootstrap-vcpkg.bat

# 编辑 shell 配置文件（以 bash 为例）
echo 'export PATH="$HOME/vcpkg:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 1. 查看当前 PowerShell Profile 文件路径
$PROFILE

# 2. 如果文件不存在，创建它
New-Item -Path $PROFILE -Type File -Force

# 3. 用记事本打开编辑
notepad $PROFILE

# 添加 vcpkg 到 PATH
$env:Path += ";$env:USERPROFILE\vcpkg"

# 可选：设置 vcpkg 默认三重（以 Windows 静态链接为例）
$env:VCPKG_DEFAULT_TRIPLET = "x64-windows"

. $PROFILE

vcpkg version

# 按名称搜索
vcpkg search fmt

# 搜索特定关键字（如 json 解析库）
vcpkg search json

# 安装默认三重（triplet）的包
vcpkg install fmt

# Windows 静态链接
vcpkg install fmt:x64-windows-static

# Linux 静态链接
vcpkg install fmt:x64-linux-static

# 安装多个包
vcpkg install fmt spdlog jsoncpp

# 列出所有已安装包
vcpkg list

# 卸载指定包
vcpkg remove fmt

# 卸载并清理依赖（不清理其他包所需的依赖）
vcpkg remove --recurse fmt

# 查看包的详细信息和可用特征（features）
vcpkg search fmt

# 更详细的包信息
vcpkg depend-info fmt

# 使 vcpkg 对系统上所有 CMake 项目可见
vcpkg integrate install

cmake_minimum_required(VERSION 3.16)
project(MyProject LANGUAGES CXX)

# vcpkg 会自动注入 CMAKE_TOOLCHAIN_FILE
# 因此可以直接 find_package
find_package(fmt REQUIRED)

add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE fmt::fmt)

# Linux
cmake -B build -S . \
    -DCMAKE_TOOLCHAIN_FILE=~/vcpkg/scripts/buildsystems/vcpkg.cmake

# Windows (PowerShell)
cmake -B build -S . `
    -DCMAKE_TOOLCHAIN_FILE=$HOME/vcpkg/scripts/buildsystems/vcpkg.cmake

# 指定 vcpkg 工具链文件（不建议提交到版本控制）
set(CMAKE_TOOLCHAIN_FILE "$ENV{HOME}/vcpkg/scripts/buildsystems/vcpkg.cmake"
    CACHE STRING "vcpkg toolchain file")

{
  "name": "my-project",
  "version": "1.0.0",
  "dependencies": [
    "fmt",
    "spdlog",
    "jsoncpp"
  ]
}

# 在项目根目录运行（自动读取 vcpkg.json）
vcpkg install

# CMakeLists.txt - 无需显式 find_package 所有依赖
# 如果启用了 manifest 模式，vcpkg 会自动设置

add_executable(my_app main.cpp)
# 通过 vcpkg 的 cmake 集成自动链接

# 全局 MSBuild 集成
vcpkg integrate install

vcpkg integrate remove

my_project/
├── CMakeLists.txt
├── vcpkg.json              # 依赖声明（manifest）
├── vcpkg-configuration.json # 版本锁定配置（可选）
├── src/
│   └── main.cpp
└── build/                  # 构建输出目录

{
  "name": "my-cross-platform-app",
  "version": "0.1.0",
  "dependencies": [
    "fmt",
    "spdlog",
    "nlohmann-json",
    "cxxopts"
  ]
}

cmake_minimum_required(VERSION 3.20)
project(MyCrossPlatformApp LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# find_package 的包必须与 vcpkg.json 中的依赖一一对应
find_package(fmt REQUIRED)
find_package(spdlog REQUIRED)
find_package(nlohmann_json REQUIRED)
find_package(cxxopts REQUIRED)

add_executable(my_app src/main.cpp)

target_link_libraries(my_app PRIVATE
    fmt::fmt
    spdlog::spdlog
    nlohmann_json::nlohmann_json
    cxxopts::cxxopts
)

#include <fmt/core.h>
#include <spdlog/spdlog.h>
#include <nlohmann/json.hpp>
#include <cxxopts.hpp>
using json = nlohmann::json;
int main(int argc, char** argv) {
    cxxopts::Options options("my_app", "A cross-platform C++ app");
    options.add_options()
        ("n,name", "Your name", cxxopts::value<std::string>());
    auto result = options.parse(argc, argv);
    std::string name = result["name"].as<std::string>();
    json j = {{"name", name}, {"platform", VCPKG_TARGET_TRIPLET}};
    spdlog::info("Hello, {}! Input: {}", name, j.dump());
    return 0;
}

# Linux
cmake -B build -S . \
    -DCMAKE_TOOLCHAIN_FILE=~/vcpkg/scripts/buildsystems/vcpkg.cmake
cmake --build build
./build/my_app --name World

# Windows (PowerShell)
cmake -B build -S . `
    -DCMAKE_TOOLCHAIN_FILE=$HOME/vcpkg/scripts/buildsystems/vcpkg.cmake
cmake --build build
.\build\Release\my_app.exe --name World

# 查看当前使用的基线
vcpkg x-history

{
  "registries": [
    {
      "kind": "artifact",
      "location": "https://github.com/microsoft/vcpkg-ce-catalog/archive/refs/heads/main.zip",
      "name": "microsoft"
    }
  ],
  "default-registry": {
    "kind": "git",
    "repository": "https://github.com/microsoft/vcpkg",
    "baseline": "abcdef1234567890abcdef1234567890abcdef12"
  }
}

# 创建 overlay 目录
mkdir -p my-overlay-ports/fmt

# 将自定义版本的 fmt 放到此处即可覆盖默认

{
  "name": "my-project",
  "version": "1.0.0",
  "dependencies": ["fmt"],
  "overlay-ports": [ "./my-overlay-ports" ]
}

# 查看包的可用特征
vcpkg search fmt

# 安装带有特征版本的包
vcpkg install fmt[core,header-only]

# 在 manifest 中使用特征

{
  "name": "my-project",
  "version": "1.0.0",
  "dependencies": [
    {
      "name": "fmt",
      "features": ["header-only"]
    },
    {
      "name": "spdlog",
      "features": ["fmt"]
    }
  ]
}

set(VCPKG_TARGET_ARCHITECTURE x64)
set(VCPKG_CRT_LINKAGE dynamic)
set(VCPKG_LIBRARY_LINKAGE static)

set(VCPKG_CMAKE_SYSTEM_NAME Linux)

vcpkg install fmt:x64-linux-static-md

~/vcpkg/
├── vcpkg                     # vcpkg 可执行文件
├── bootstrap-vcpkg.sh        # Linux 引导脚本
├── bootstrap-vcpkg.bat       # Windows 引导脚本
├── ports/                    # 包构建脚本仓库
│   ├── fmt/                  # fmt 库的 port 定义
│   │   ├── portfile.cmake    # 构建脚本
│   │   └── vcpkg.json        # 包元数据
│   ├── spdlog/
│   └── ...
├── triplets/                 # 三重定义文件
│   ├── x64-windows.cmake
│   ├── x64-linux.cmake
│   └── ...
├── packages/                 # 已安装的二进制文件
│   ├── fmt_x64-linux/
│   │   ├── include/          # 头文件
│   │   ├── lib/              # 库文件 (.a / .lib)
│   │   └── debug/lib/        # Debug 版本库文件
│   └── ...
├── downloads/                # 下载的源码压缩包缓存
├── buildtrees/               # 编译中间产物
├── installed/                # 符号链接到 packages/ 的内容
└── scripts/                  # 辅助脚本
    └── buildsystems/
        ├── vcpkg.cmake       # CMake 工具链文件（核心）
        └── msbuild/          # MSBuild 集成

# 1. 查看详细的错误日志
# 错误信息会显示 logs 路径，形如：
#   vcpkg/fmt: error: building fmt failed with: ...
#   详细信息在：~/vcpkg/buildtrees/fmt/install-x64-linux-dbg-out.log

# 2. 尝试清理后重新安装
vcpkg remove fmt
vcpkg clean
vcpkg install fmt

# 3. 尝试不同版本
vcpkg install fmt@10.0.0

# 1. 忘记指定工具链文件
# 解决方法：cmake 时添加 -DCMAKE_TOOLCHAIN_FILE=...

# 2. 三重不匹配——安装了 x64-linux 但 CMake 没传对应参数
# 解决方法：确保 CMake 生成时使用了正确的三重

# 3. 包名与 CMake 目标名不一致
# 查看已安装包提供的 CMake targets
~/vcpkg/packages/fmt_x64-linux/share/fmt/fmtConfig.cmake

# Linux / macOS
export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890

# 如果要持久化，加入 shell 配置文件
echo 'export http_proxy=http://127.0.0.1:7890' >> ~/.bashrc
echo 'export https_proxy=http://127.0.0.1:7890' >> ~/.bashrc

# Windows PowerShell（当前会话）
$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"

# 持久化：将上述两行添加到 PowerShell Profile
notepad $PROFILE
# 添加后执行 . $PROFILE 生效

# Linux
git clone https://github.com.cnpmjs.org/microsoft/vcpkg.git ~/vcpkg
# 或使用 gitee 镜像
git clone https://gitee.com/mirrors/vcpkg.git ~/vcpkg

# Windows (PowerShell)
git clone https://github.com.cnpmjs.org/microsoft/vcpkg.git $env:USERPROFILE\vcpkg
git clone https://gitee.com/mirrors/vcpkg.git $env:USERPROFILE\vcpkg

# Linux
export X_VCPKG_ASSET_SOURCES=x-azurl,https://mirrors.tencent.com/vcpkg/,proxy

# 持久化到 shell 配置
echo 'export X_VCPKG_ASSET_SOURCES=x-azurl,https://mirrors.tencent.com/vcpkg/,proxy' >> ~/.bashrc

# Windows PowerShell
$env:X_VCPKG_ASSET_SOURCES = "x-azurl,https://mirrors.tencent.com/vcpkg/,proxy"

# 持久化到 PowerShell Profile
notepad $PROFILE
# 添加: $env:X_VCPKG_ASSET_SOURCES = "x-azurl,https://mirrors.tencent.com/vcpkg/,proxy"

{
  "default-registry": {
    "kind": "git",
    "repository": "https://github.com/microsoft/vcpkg",
    "baseline": "abcdef1234567890abcdef1234567890abcdef12"
  },
  "registries": [
    {
      "kind": "artifact",
      "location": "https://github.com/microsoft/vcpkg-ce-catalog/archive/refs/heads/main.zip",
      "name": "microsoft"
    }
  ]
}

# ===== vcpkg 环境配置 =====

# 1. PATH
$env:Path += ";$env:USERPROFILE\vcpkg"

# 2. 默认三重
$env:VCPKG_DEFAULT_TRIPLET = "x64-windows"

# 3. 资产缓存镜像（腾讯云公众镜像，下载源码加速）
$env:X_VCPKG_ASSET_SOURCES = "x-azurl,https://mirrors.tencent.com/vcpkg/,proxy"

# 4. 代理（按需取消注释）
# $env:HTTP_PROXY = "http://127.0.0.1:7890"
# $env:HTTPS_PROXY = "http://127.0.0.1:7890"

# 验证环境变量是否生效
echo $env:X_VCPKG_ASSET_SOURCES

# 更新 vcpkg 自身
cd ~/vcpkg
git pull
./bootstrap-vcpkg.sh        # Linux
./bootstrap-vcpkg.bat        # Windows

# 更新所有已安装包到最新
vcpkg upgrade

# 清理编译中间文件（不删除已安装的二进制）
vcpkg clean

# 清理下载缓存
# 直接删除 downloads/ 目录即可
rm -rf ~/vcpkg/downloads/*

# 查看已安装包占用的磁盘空间
du -sh ~/vcpkg/packages/*