跳到主要内容

kmpkg 在 MSBuild 项目中的使用

集成方式​

全局用户集成​

要在 MSBuild 项目中使用 kmpkg，执行以下命令：

kmpkg integrate install

首次启用 MSBuild 集成时，只需运行一次 kmpkg integrate install 命令。该操作会为你所有现有及未来的项目启用 MSBuild 集成。

若你有多个 kmpkg 实例，可通过 kmpkg integrate install 命令更新 MSBuild 中使用的 kmpkg 实例；使用 kmpkg integrate remove 可移除全局的 MSBuild 集成。

这种集成方式会自动将 kmpkg 安装的包添加到项目的以下属性中：包含目录（Include Directories）、链接目录（Link Directories）和链接库（Link Libraries）。此外，还会创建一个构建后操作，确保所有必需的 DLL 文件被复制到构建输出目录。该方式适用于 Visual Studio 2015 及更高版本的所有解决方案和项目。

对于绝大多数库而言，以上操作已足够。但部分库存在冲突行为（例如重定义 main() 函数），由于需要按项目选择所需的冲突选项，你必须手动将这些库添加到链接器输入中。

以下是需要手动链接的常见示例（非完整列表）：

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

要查看已安装包中所有需要手动链接的库，运行 kmpkg owns manual-link 命令。

导入 .props 和 .targets 文件​

也可通过在每个 .vcxproj 文件中显式导入 scripts/buildsystems/kmpkg.props 和 scripts/buildsystems/kmpkg.targets 文件，将 kmpkg 集成到 MSBuild 项目中。通过相对路径配置，可将 kmpkg 作为子模块引入，用户执行 git clone 时会自动获取相关文件。

为解决方案中所有项目添加这些配置的最简方式是：在代码仓库根目录创建 Directory.Build.props 和 Directory.Build.targets 文件。

以下示例假设代码仓库根目录包含 kmpkg 子模块（路径为 kmpkg，对应仓库 kumose/kmpkg）。

示例 Directory.Build.props​

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

示例 Directory.Build.targets​

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

进阶示例 Directory.Build.props​

<Project>
  <PropertyGroup>
    <KmpkgRoot>C:\dev\kmpkg\</KmpkgRoot>
    <MyProp Condition="'$(Platform)' == 'x64'">X64_VALUE</MyProp>
    <MyProp Condition="'$(Platform)' == 'x86'">X86_VALUE</MyProp>
  </PropertyGroup>
 <Import Project="$(KmpkgRoot)scripts\buildsystems\msbuild\kmpkg.props" />
</Project>

进阶示例 Directory.Build.targets​

<Project>
  <Import Project="$(KmpkgRoot)scripts\buildsystems\msbuild\kmpkg.targets" />
  <Target Name="_SetKmpkgEnvVars" BeforeTargets="KmpkgTripletSelection">
    <Message Text="Setting MY_PROP to $(MyProp)" />
    <SetEnv Name="MY_PROP" Value="$(MyProp)" Prefix="false" />
  </Target>
</Project>

示例三元组文件 x64-windows-custom.cmake​

set(KMPKG_TARGET_ARCHITECTURE x64)
set(KMPKG_CRT_LINKAGE dynamic)
set(KMPKG_LIBRARY_LINKAGE dynamic)

# 将环境变量传递到端口构建流程
set(KMPKG_ENV_PASSTHROUGH_UNTRACKED MY_PROP)

示例端口文件 portfile.cmake​

set(KMPKG_POLICY_EMPTY_PACKAGE enabled)

MESSAGE(STATUS "MY_PROP is $ENV{MY_PROP}")

链接 NuGet 包​

信息

不建议新项目使用此方式，因为会导致项目难以共享。如需可移植、自包含的 NuGet 包，参考 export 命令。

VS 项目也可通过 NuGet 包集成 kmpkg，但该方式会修改项目文件，因此不建议开源项目使用。

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

打开项目后，进入 工具->NuGet 包管理器->程序包管理器控制台，粘贴以下命令：
    Install-Package kmpkg.D.src.kmpkg -Source "D:/src/kmpkg/scripts/buildsystems"
信息

生成的 NuGet 包不包含实际库文件，仅作为 kmpkg 安装目录的“快捷方式（符号链接）”。对库的任何修改（安装/移除）都会自动同步，无需重新生成或更新 NuGet 包。

通用配置​

KmpkgEnabled（启用 Kmpkg）​

可设为 "false" 显式禁用项目的 kmpkg 集成。

KmpkgConfiguration（Kmpkg 配置）​

若项目配置名称过于复杂，导致 kmpkg 无法自动识别，可将此属性设为 Release 或 Debug，显式指定要使用的库变体。

KmpkgEnableManifest（使用 Kmpkg 清单）​

需将此属性设为 true，才能加载本地 kmpkg.json 清单文件。若设为 false，则忽略所有本地 kmpkg.json 文件。

该属性当前默认值为 false，未来会改为 true。

KmpkgTriplet（三元组）​

该属性控制要使用的库三元组（如 x64-windows-static、arm64-windows）。

若未显式设置，kmpkg 会根据 Visual Studio 项目设置自动推导三元组。自动推导仅支持动态库链接和动态 CRT 链接；若需静态依赖或静态 CRT（/MT），必须手动设置三元组。

将 MSBuild 详细程度设为“普通”或更高，可查看自动推导的三元组：

快捷方式：Ctrl+Q 输入“build and run”

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

更多信息参考 三元组。

KmpkgHostTriplet（主机三元组）​

可设为自定义三元组，用于解析主机依赖项。

若未设置，默认使用“原生”三元组（x64-windows）。

更多信息参考 主机依赖项。

KmpkgInstalledDir（安装目录）​

该属性定义 kmpkg 安装和查找库的路径。

  • 清单模式：默认值为 $(KmpkgManifestRoot)\kmpkg_installed\$(KmpkgTriplet)\
  • 经典模式：默认值为 $(KmpkgRoot)\installed\

KmpkgApplocalDeps（应用本地部署 DLL）​

该属性控制是否检测并将 kmpkg 安装目录中的依赖 DLL 复制到项目输出目录。

KmpkgXUseBuiltInApplocalDeps（使用内置应用本地部署）​

启用该属性时，kmpkg 会使用实验性的内置实现完成 DLL 的应用本地部署。当该实现不再是实验性特性后，此属性会被移除且失效。

若 $(KmpkgApplocalDeps) 为 false，该属性无作用。

清单模式配置​

要在 MSBuild 中使用清单文件（kmpkg.json），需先通过上述任一方式完成集成，然后：

  1. 在项目文件上级目录（如代码仓库根目录）添加 kmpkg.json 文件；
  2. 将 KmpkgEnableManifest 属性设为 true（可通过 IDE 设置：项目属性 → Kmpkg → 使用 Kmpkg 清单，可能需要重启 IDE 才能看到该属性页）。

项目构建时，kmpkg 会自动运行并将清单中列出的依赖安装到 kmpkg.json 同级目录的 kmpkg_installed/$(KmpkgTriplet)/ 路径下；这些库会自动被 MSBuild 项目包含并链接。

已知问题​

  • Visual Studio 2015 无法正确跟踪 kmpkg.json 和 kmpkg-configuration.json 文件的修改，除非编辑 .cpp 文件，否则不会响应清单变更。

KmpkgAdditionalInstallOptions（附加选项）​

使用清单模式时，该选项可指定传递给 kmpkg 工具的额外命令行参数，用于启用尚未通过其他选项暴露的功能。

KmpkgManifestInstall（安装 Kmpkg 依赖）​

该属性设为 false 时，会禁用构建过程中自动还原依赖的行为，需通过 kmpkg 命令行手动还原依赖。