跳到主要内容

kmpkg_msbuild_install

构建并安装基于 MSBuild 的项目。

该函数替代了旧的 kmpkg_install_msbuild。

kmpkg_msbuild_install 会自动生成包含 CMake 工具链构建标志的 .props 文件和 .target 文件，并通过 /p:ForceImportAfterCpp(Props|Targets) 参数将这些文件强制引入 MSBuild 构建流程。

用法​

kmpkg_msbuild_install(
    SOURCE_PATH <${SOURCE_PATH}>
    PROJECT_SUBPATH <port.sln>
    [ADD_BIN_TO_PATH]
    [NO_INSTALL]
    [NO_TOOLCHAIN_PROPS]
    [CLEAN]
    [RELEASE_CONFIGURATION <Release>]
    [DEBUG_CONFIGURATION <Debug>]
    [TARGET <Build>]
    [PLATFORM <Win32>]
    [OPTIONS </p:ZLIB_INCLUDE_PATH=X>...]
    [OPTIONS_RELEASE </p:ZLIB_LIB=X>...]
    [OPTIONS_DEBUG </p:ZLIB_LIB=X>...]
    [DEPENDENT_PKGCONFIG <zlib>]
    [ADDITIONAL_LIBS <getopt.lib>]
    [ADDITIONAL_LIBS_DEBUG <zlibd.lib>]
    [ADDITIONAL_LIBS_RELEASE <zlib.lib>]
)

使用该函数前，必须依赖辅助端口 kmpkg-msbuild（需配置为 host 依赖）：

"dependencies": [
  { 
    "name": "kmpkg-msbuild",
    "host": true
  }
]

参数​

SOURCE_PATH​

源码树的根目录路径。

由于 MSBuild 采用「源码内构建（in-source builds）」模式，源码树会被复制到临时目录中进行构建。该参数是复制操作的基准路径，同时也是所有 XYZ_SUBPATH 类参数的路径基准。

PROJECT_SUBPATH​

相对于 SOURCE_PATH 的解决方案文件（.sln）或项目文件（.vcxproj）的子路径。

ADD_BIN_TO_PATH​

构建前将「与当前配置相关的二进制路径」添加到 PATH 环境变量中。 若项目需要运行自身构建的工具（如自定义代码生成器），该选项是必需的。注意：当 KMPKG_CROSSCOMPILING 为 true（交叉编译）时，不会修改 PATH 环境变量。

NO_TOOLCHAIN_PROPS​

不通过 CMake 生成工具链属性文件（.props）。启用该参数后，所有 kmpkg 集成逻辑会自动禁用。

NO_INSTALL​

不自动检测并安装构建目录中生成的 .lib、.dll、.pdb、.exe 等文件。

CLEAN​

指定安装完成后，自动清理构建过程中生成的中间文件。

RELEASE_CONFIGURATION​

Release 构建使用的配置（对应 MSBuild 参数 /p:Configuration），默认值：Release。

DEBUG_CONFIGURATION​

Debug 构建使用的配置（对应 MSBuild 参数 /p:Configuration），默认值：Debug。

TARGET​

要构建的 MSBuild 目标（对应参数 /t:<TARGET>），默认值：Rebuild（先清理再全量构建）。

PLATFORM​

构建使用的平台（对应 MSBuild 参数 /p:Platform）。

该参数默认值会根据 KMPKG_TARGET_ARCHITECTURE 映射为 Visual Studio 创建 .vcxproj 时的默认值：

  • x86 → Win32
  • x64 → x64
  • arm → ARM
  • arm64 → arm64

若传入的是 .sln 解决方案文件（而非 .vcxproj 项目文件），可能需要将该参数设回 ${KMPKG_TARGET_ARCHITECTURE}，以匹配解决方案中定义的平台字符串。

OPTIONS​

传递给所有构建模式（Release/Debug）的额外 MSBuild 选项。

OPTIONS_RELEASE​

仅传递给 Release 构建的额外 MSBuild 选项（会追加到 OPTIONS 之后）。

OPTIONS_DEBUG​

仅传递给 Debug 构建的额外 MSBuild 选项（会追加到 OPTIONS 之后）。

DEPENDENT_PKGCONFIG​

需要添加到构建中的 pkg-config 依赖列表。该参数会自动将这些依赖的所有必需构建标志（包含路径、宏定义、库文件）注入到 MSBuild 构建属性中。

ADDITIONAL_LIBS​

要添加到项目中的额外库文件（对 Debug/Release 构建均生效）。

ADDITIONAL_LIBS_DEBUG​

仅添加到 Debug 构建的额外库文件（追加到 ADDITIONAL_LIBS 之后）。

ADDITIONAL_LIBS_RELEASE​

仅添加到 Release 构建的额外库文件（追加到 ADDITIONAL_LIBS 之后）。

完整示例​

# 1. 声明依赖（portfile.json 中）
/*
{
  "dependencies": [
    { "name": "kmpkg-msbuild", "host": true },
    { "name": "zlib" }
  ]
}
*/

# 2. 构建并安装 MSBuild 项目
kmpkg_msbuild_install(
    SOURCE_PATH ${SOURCE_PATH}
    PROJECT_SUBPATH "src/MyProject.sln"
    # 适配解决方案的平台字符串（若 sln 中用 x86 而非 Win32）
    PLATFORM ${KMPKG_TARGET_ARCHITECTURE}
    # 添加 zlib 作为 pkg-config 依赖
    DEPENDENT_PKGCONFIG zlib
    # 额外传递 MSBuild 选项
    OPTIONS "/p:WarningLevel=4"
    # Debug 构建用 zlibd.lib，Release 用 zlib.lib
    ADDITIONAL_LIBS_DEBUG "zlibd.lib"
    ADDITIONAL_LIBS_RELEASE "zlib.lib"
)

源码​

ports/kmpkg-msbuild/kmpkg_msbuild_install.cmake