Share via

MSBuild 项目中的 vcpkg

  • 项目

集成方法

用户范围的集成

要在 MSBuild 项目中使用 vcpkg，请运行以下命令：

vcpkg integrate install

只需在首次要启用 MSBuild 集成时运行 vcpkg integrate install 命令。 这将为所有现有和未来项目启用 MSBuild 集成。

如果有多个 vcpkg 实例，则可以使用 vcpkg integrate install 命令更新 MSBuild 中使用的 vcpkg 实例。 使用 vcpkg integrate remove 可移除 MSBuild 用户范围的集成。

此集成方法自动将已安装 vcpkg 的包添加到以下项目属性：包括目录、链接目录和链接库。 此外，这会创建一个生成后操作，该操作可确保将任何所需的 DLL 复制到生成输出文件夹中。 这适用于使用 Visual Studio 2015 或更高版本的所有解决方案和项目。

对于大多数库而言，你只需要进行此操作。 但是，一些库会执行冲突行为，例如重新定义 main()。 由于需要选择每个项目所需的这些冲突选项之一，因此必须将这些库手动添加到链接器输入。

下面是一些需要手动链接的示例（并非详尽的列表）：

  • Gtest 提供 gtest、gmock、gtest_main 和 gmock_main
  • SDL2 提供 SDL2main
  • SFML 提供 sfml-main
  • Boost.Test 提供 boost_test_exec_monitor

若要获取所有已安装包的完整列表，请运行 vcpkg owns manual-link。

导入 .props 和 .targets

还可以通过明确将 scripts/buildsystems/vcpkg.props 和 scripts/buildsystems/vcpkg.targets 文件导入每个 .vcxproj，将 vcpkg 集成到 MSBuild 项目中。 可以使用相对路径让子模块能够使用 vcpkg，并在用户运行 git clone 时自动获取。

将这些内容添加到解决方案中的每个项目的最简单方法是在存储库的根目录中创建 Directory.Build.props 和 Directory.Build.targets 文件。

以下示例假定它们位于存储库的根目录中，microsoft/vcpkg 的子模块位于 vcpkg。

示例 Directory.Build.props

<Project>
 <Import Project="$(MSBuildThisFileDirectory)vcpkg\scripts\buildsystems\msbuild\vcpkg.props" />
</Project>

示例 Directory.Build.targets

<Project>
 <Import Project="$(MSBuildThisFileDirectory)vcpkg\scripts\buildsystems\msbuild\vcpkg.targets" />
</Project>

有关 Directory.Build.targets 和 Directory.Build.props 的详细信息，请参阅 MSBuild 官方文档中的自定义版本部分。

关联的 NuGet 包

注意

新项目不建议采用此方法，因为这样会很难与其他人共享新项目。 有关可移植的自包含 NuGet 包的相关信息，请参阅 export command。

VS 项目也可以通过 NuGet 包集成。 这会修改项目文件，因此开放源代码项目不建议采用此方法。

PS D:\src\vcpkg> .\vcpkg integrate project
Created nupkg: D:\src\vcpkg\scripts\buildsystems\vcpkg.D.src.vcpkg.1.0.0.nupkg

With a project open, go to Tools->NuGet Package Manager->Package Manager Console and paste:
    Install-Package vcpkg.D.src.vcpkg -Source "D:/src/vcpkg/scripts/buildsystems"

注意

生成的 NuGet 包不包含实际库。 而是像 vcpkg 安装的快捷方式（或符号链接）一样，并使用对库的任何更改（安装/删除）进行“自动更新”。 无需重新生成或更新 NuGet 包。

常见配置

VcpkgEnabled（使用 Vcpkg）

可以设置为“false”以明确为项目禁用 vcpkg 集成。

VcpkgConfiguration（Vcpkg 配置）

如果配置名称过于复杂，vcpkg 无法正确猜出来，则可以将此属性明确分配给 Release 或 Debug，从而明确告诉 vcpkg 你想要使用哪些库的变体。

VcpkgEnableManifest（使用 Vcpkg 清单）

必须将此属性设置为 true 才能从本地 vcpkg.json 文件使用。 如果设置为 false，则会忽略任何本地 vcpkg.json 文件。

此属性目前默认为 false，不过未来将会默认为 true。

VcpkgTriplet（三联密码）

此属性控制要使用库的三联密码，例如 x64-windows-static 或 arm64-windows。

如未明确设置，vcpkg 将根据 Visual Studio 设置推断出正确的三联密码。 vcpkg 将仅推断使用动态库链接和动态 CRT 链接的三联密码数据库;如果希望静态依赖项或使用静态 CRT (/MT)，则需要手动设置三联密码。

通过将 MSBuild 详细程度设置为“正常”或更高，可以看到自动推断的三联密码：

快捷方式：Ctrl+Q“生成并运行”

“工具”>>“选项”>>“属性和解决方案”>>“生成并运行”>>“MSBuild 项目生成输出详细程度”

另请参阅三联密码

VcpkgHostTriplet（主机三联密码）

可以将此设置为用于解析主机依赖项的自定义三联密码。

如未设置，则默认为“本机”三联密码 (x64-windows)。

另请参阅主机依赖项。

VcpkgInstalledDir（已安装目录）

此属性定义 vcpkg 将从中安装和使用库的位置。

在清单模式下，此属性默认为 $(VcpkgManifestRoot)\vcpkg_installed\$(VcpkgTriplet)\。 在经典模式下，此属性默认为 $(VcpkgRoot)\installed\。

VcpkgApplocalDeps（应用本地部署 DLL）

此属性启用或停用从 vcpkg 安装树到项目输出目录的依赖项 DLL 的检测和复制。

VcpkgXUseBuiltInApplocalDeps（使用内置应用本地部署）

启用此属性后，在应用本地部署 DLL 时，会使用 vcpkg 的实验性内置应用本地 DLL 部署实现。 当内置实现不再是实验性实现时，此属性将被删除并不再起作用。

此属性在 $(VcpkgApplocalDeps) 为 false 时不起作用。

清单模式配置

若要将清单 (vcpkg.json) 与 MSBuild 配合使用，则首先需要使用上述的其中一种集成方法。 然后，在项目文件（如源存储库的根目录中）上添加 vcpkg.json，并将属性 VcpkgEnableManifest 设置为 true。 可以通过“项目属性”>“Vcpkg”>“使用Vcpkg 清单”中的 IDE 来设置此属性。 可能需要重新加载 IDE 才能查看 vcpkg 属性页。

vcpkg 将在项目的生成过程中运行，并安装与 vcpkg_installed/$(VcpkgTriplet)/ 文件相邻 vcpkg.json 的任何列出的依赖项；然后，这些库将自动包含在 MSBuild 项目中并链接到你的 MSBuild 项目。

已知问题

  • Visual Studio 2015 无法正确跟踪对 vcpkg.json 和 vcpkg-configuration.json 文件的编辑，并且不会响应更改，除非编辑 .cpp。

VcpkgAdditionalInstallOptions（其他选项）

使用清单时，此选项指定要传递给基础 vcpkg 工具调用的其他命令行标志。 这可用于访问尚未通过另一个选项公开的功能。

VcpkgManifestInstall（安装 Vcpkg 依赖项）

此属性可以设置为 false 在项目生成期间禁用自动依赖项还原。 必须单独通过 vcpkg 命令行手动还原依赖项。