通过

安装目录布局约定

  • 项目

本文介绍 vcpkg 用于安装目录的布局约定。 安装目录保存每个包安装的文件。 端口作者应确保其包遵循本文中所述的约定。

在经典模式下，安装目录位于 $VCPKG_ROOT/installed（其中 $VCPKG_ROOT 表示 vcpkg 安装路径）。 在清单模式下，每个清单文件都有相应的 vcpkg_installed 目录。 可以使用 --x-install-root 选项更改安装目录的位置。 无论操作模式如何，安装目录的布局都保持不变。

安装目录是在首次安装包时创建的，如果未看到安装目录，请先尝试安装某些包。

安装目录的根级别包含：

  • vcpkg 目录，用于跟踪已安装的包和文件
  • 每个三元组的目录。 每个三元组目录都包含每个包安装的文件。

三元组目录

每个包安装的输出都包含在三元组特定的目录中。 例如，为 x64-windows 三元组安装的包位于 installed/x64-windows 目录中。

每个三元组目录内的子目录的布局相同：

注意

某些包可能会生成与本文所述的约定不匹配的文件。 端口作者应根据每个文件的服务目的确定所生成文件的最终位置。

子目录 文件类型
bin 发布 .dll 和 .pdb 文件
debug/bin 调试 .dll 和 .pdb 文件
debug/lib 调试 .lib、.so、.dylib 和 .a 文件
debug/lib/manual-link 可手动链接的调试 .lib、.so、.dylib 和 .a 文件
debug/plugins/<group> 运行时加载调试 .dll 文件
debug/lib/pkgconfig 调试 pkgconfig 文件 (.pc)
include 头文件（.h、.hpp、.hxx）
lib 发布 .lib、.so、.dylib 和 .a 文件
lib/manual-link 可手动链接的发布 .lib、.so、.dylib 和 .a 文件
lib/pkgconfig Pkgconfig 文件 (.pc)
plugins/<group> 运行时加载发布 .dll 文件
share/<port> 其他与配置无关的文件
share/<port>/copyright 包的许可证文本
share/<port>/usage 生成系统集成说明文件
share/<port>/vcpkg-port-config.cmake 端口定义的 CMake 函数和变量
share/<lowercase-package>/<package>Config.cmake find_package(package) 的 CMake 集成文件
share/<cmakepackagename>/vcpkg-cmake-wrapper.cmake CMake find_package(<cmakepackagename>) 替代
share/pkgconfig 与配置无关的 pkgconfig 文件 (.pc)
tools/<port> 可执行工具

bin 和 debug/bin 目录

在 Windows 上，这些目录分别包含用于发布和调试配置的 DLL 和 PDB 文件。 端口生成的任何可执行文件均应移动到 tools/<port> 目录。

include

包含头文件（.h、.hpp、.hxx）。 此目录下的布局应反映包的头文件的预期用途。 例如，打算使用 #include <contoso/contoso.h> 的 contoso 库应提供头文件 include/contoso/contoso.h。

vcpkg 禁止在 include 目录的根目录中安装一些保留的头文件名称，例如：err.h、user.h、time.h 等。 提供禁止使用的头文件名称的库应将其头文件放入 include/<port> 目录。 如果该库打算替换系统头文件，应在其 portfile.cmake 中设置 VCPKG_POLICY_ALLOW_RESTRICTED_HEADERS 策略。

lib 和 debug/lib 目录

包含静态库、导入库（Windows 上）和共享库（非 Windows 上）。

包含必须手动链接的库。

自动链接时可能导致问题的文件必须放入 lib/manual-link 文件夹，而不是 lib 目录。 例如，如果库旨在定义程序的 main() 函数。

lib/pkgconfig、debug/lib/pkgconfig 和 share/pkgconfig 目录

包含 pkgconfig 集成文件 (.pc)。 库不应同时提供依赖于配置的文件和与配置无关的文件。 例如：不安装 lib/pkgconfig/contoso.pc 和 share/pkgconfig/contoso.pc。

plugins/<group> 和 debug/plugins/<group>

包含要在运行时通过使用应用程序加载的共享库。

share/<port>

包含每个端口安装的其他文件。 例如，SPDX 文件、脚本等。

vcpkg 要求端口提供包含已安装包的许可证信息的 copyright 文件。 有关详细信息，请参阅维护人员指南。

share/<port>/usage

包含在项目中集成库的说明的文本文件。 有关详细信息，请参阅提供包的使用情况文档指南。

share/<lowercase-package>/<package>Config.cmake, share/<package>/<package>-config.cmake

CMake 集成文件应放入 share 文件夹，并遵循 find_package(package) 模式下 CMake 针对 CONFIG 的规则。

例如，如果端口需要提供 find_package(MyPackage REQUIRED)，则必须提供 share/mypackage/MyPackageConfig.cmake 或 share/mypackage/MyPackage-config.cmake。

如果包提供 CMake 集成文件，则应调用 vcpkg_cmake_config_fixup() 帮助程序函数来修复任何不可重定位的路径并合并生成配置。

tools/<port>

重要

首先也是最重要的，vcpkg 是 C++ 库依赖项管理器。 在决定是否在安装输出中包含工具时，端口作者应谨慎。 例如：考虑仅在不需要调试工具时安装发布可执行文件。

当可执行文件打算供运行时使用时，应同时提供发布和调试可执行文件。

包含端口生成的可执行工具。 强烈建议（但不强制要求）将每个已安装的可执行文件放入与生成它的端口名称匹配的子目录。 例如，contoso 端口可能会将 ContosoGenerator.exe 安装到 tools/contoso/ContosoGenerator.exe。

某些端口要求将其可执行文件放入 bin 子目录，在这种情况下，建议使用 tools/<port>/bin 模式。