跳到主要内容

kmpkg端口构建失败排查

本指南适用于使用kmpkg 安装端口 时遇到问题的用户。

查找失败日志​

构建失败的原因多种多样。当kmpkg构建端口失败时，诊断问题的第一步是查看日志文件。

kmpkg会为构建端口过程中调用的每个外部进程生成日志文件。发生错误时，kmpkg会打印最后一个运行进程的日志文件位置。在kmpkg输出中查找“See logs for more information:”行。

示例：日志文件位置输出

    有关详细信息，请查看日志：
      C:\Users\viromer\work\kmpkg\buildtrees\detect_compiler\config-x64-linux-rel-CMakeCache.txt.log
      C:\Users\viromer\work\kmpkg\buildtrees\detect_compiler\config-x64-linux-out.log

你可以通过检查端口的 buildtrees 目录找到所有生成的日志文件，该目录位于 $KMPKG_ROOT/buildtrees/<port>/（将 <port> 替换为对应的端口名称）。

端口资产下载失败​

信息

使用 资产缓存 可缓解此类问题，确保缓存资产的持续可用性。

安装端口时，从网络下载资产失败：

CMake Error at scripts/cmake/kmpkg_download_distfile.cmake:32 (message):

  下载文件失败，错误码：1

原因1：下载URL失效​

由于kmpkg无法控制的原因，URL可能会失效。可通过浏览器访问下载URL诊断失效链接，失效链接会返回404状态码。

解决步骤：

  1. 修改端口，为资产使用替代下载URL。

原因2：文件哈希与预期SHA512不匹配​

error: 无法从镜像集下载
error: 文件哈希与预期不符：
url: https://github.com/OpenImageIO/oiio/archive/v2.4.13.0.tar.gz
文件：/home/user/kmpkg/downloads/OpenImageIO-oiio-v2-9325beef.4.13.0.tar.gz.1925416.part
预期哈希：9325beefce55b66a58fcfc2ce93e1406558ed5f6cc37cb1e8e04aee470c4f30a14483bebfb311c329f7868afb6c508a052661c6b12d819a69f707c1a30cd9549
实际哈希：9e887c7039995ce7c41556e09a7eed940863260a522ecf7d9bec300189026ed507da560620dfa4a619deeb679be7adf42fe3a7020ff3094df777c7934c771227

当服务器修改了上游文件但未更改下载URL时，会出现此错误。作为安全措施，kmpkg会拒绝SHA512与资产预期值不匹配的文件。

解决步骤：

  1. 验证下载文件的安全性；
  2. 修改端口，使用新文件的SHA512。

未找到Visual Studio工具链​

安装端口时，kmpkg无法找到合适的工具链：

error: 在三元组 arm-windows 中：无法为请求的目标架构 arm 找到有效的工具链。
选中的Visual Studio实例位于：C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools
可用的工具链组合：x86、amd64、x86_amd64、amd64_x86

原因1：未安装目标架构对应的工具链​

如果Visual Studio实例版本与你的kmpkg版本匹配，但仍出现此错误，最可能的原因是未安装对应的工具链。

解决步骤：

  1. 打开Visual Studio Installer，安装对应的工具链。

原因2：选中的Visual Studio版本不正确​

如果已安装所需工具链，但仍出现错误，可能是kmpkg选中了未安装该工具链的Visual Studio版本。更多信息请参考 Visual Studio选择算法文档。

解决步骤：

  1. 设置 KMPKG_PLATFORM_TOOLSET 为合适的版本；
  2. 或设置 KMPKG_VISUAL_STUDIO_PATH 为你期望的Visual Studio实例安装路径。

缺少系统依赖​

环境中未安装必需的构建工具或系统依赖。

示例：端口需要系统依赖

alsa 当前需要从系统包管理器安装以下程序：
    autoconf autoheader aclocal automake libtoolize
在Debian和Ubuntu衍生版上：
    sudo apt install autoconf libtool
在最新的Red Hat和Fedora衍生版上：
    sudo dnf install autoconf libtool
在Arch Linux和衍生版上：
    sudo pacman -S autoconf automake libtool
在Alpine上：
    apk add autoconf automake libtool

大多数需要系统依赖的kmpkg端口会在安装过程中打印提示信息。在某些情况下，所需系统依赖的列表可能不完整。此类问题的诊断取决于底层构建系统，请 查看错误日志 确定失败原因。

解决步骤：

  1. 按照对应系统的步骤安装缺少的系统依赖。

构建过程中未找到FetchContent依赖​

构建失败，因为通过 FetchContent 获取的依赖在构建过程中不可用。

CMake代码示例：

include(FetchContent)

FetchContent_Declare(fmt
  GIT_REPOSITORY https://github.com/fmtlib/fmt.git
  GIT_TAG master
)
FetchContent_MakeAvailable(fmt)

错误输出：

CMake Error at CMakeLists.txt:23 (target_link_libraries):
  目标 "my_sample_lib" 链接到：

    fmt::fmt

  但未找到该目标。可能的原因包括：

    * 目标名称拼写错误。
    * 缺少针对 IMPORTED 目标的 find_package 调用。
    * 缺少 ALIAS 目标。

kmpkg通过CMake变量 FETCHCONTENT_FULLY_DISCONNECTED 禁用了 FetchContent。禁用此功能的原因包括：

  • FetchContent 可能隐藏端口的嵌入式依赖；
  • FetchContent 在完全离线场景下兼容性不佳；
  • 通过 FetchContent 获取的依赖可能在不参与ABI哈希计算的情况下改变构建结果。

对于端口维护者，建议将所有通过 FetchContent 获取的包转换为kmpkg依赖。但对于普通使用场景，有以下启用 FetchContent 的变通方法：

解决步骤：

  1. 使用 KMPKG_CMAKE_CONFIGURE_OPTIONS 设置 FETCHCONTENT_FULLY_DISCONNECTED=FALSE。

项目构建时未链接kmpkg安装的依赖​

使用清单模式或经典模式构建项目时，kmpkg依赖未被加载和链接到项目，导致构建失败。

kmpkg为 CMake 和 MSBuild 项目提供库和包含目录的自动链接功能。通过kmpkg安装的依赖应能在项目中自动使用。

原因1：未安装所需依赖​

解决步骤：

  1. 确保项目的依赖已准备就绪：
    • 若使用 清单文件（kmpkg.json），确保该文件与 CMakeList.txt 位于同一目录，且所有依赖都列在清单的 "dependencies" 字段中。构建项目时，kmpkg会自动安装清单中的依赖；
    • 若使用kmpkg CLI在 经典模式 下 安装包，确保在运行项目构建前已预安装所有必需的依赖。经典模式下，kmpkg不会自动安装项目所需的包。

原因2：未启用构建系统集成​

CMake​

解决步骤：

  1. 设置 CMAKE_TOOLCHAIN_FILE 变量 指向kmpkg工具链文件。

CMAKE_TOOLCHAIN_FILE 必须设置为 {KMPKG_ROOT}/scripts/buildsystems/kmpkg.cmake（将 {KMPKG_ROOT} 替换为你的kmpkg安装目录的正确路径）。可通过以下任一方式设置工具链文件：

  • 使用 CMakePresets.json 文件：
    • 若使用3.x及以上版本，设置 toolchainFile；
    • 若使用2.x及以下版本，将 CMAKE_TOOLCHAIN_FILE 作为 cacheVariable 设置；
  • 在CMake调用时传递命令行参数：-DCMAKE_TOOLCHAIN_FILE={KMPKG_ROOT}/scripts/buildsystems/kmpkg.cmake；
  • 在 CMakeList.txt 文件中设置 CMAKE_TOOLCHAIN_FILE，确保在 project() 调用前设置该变量。

若已通过 CMAKE_TOOLCHAIN_FILE 使用自定义工具链文件，可通过 自定义三元组 设置 KMPKG_CHAINLOAD_TOOLCHAIN_FILE，指向你的自定义工具链。

MSBuild​

kmpkg通过 kmpkg integrate install 命令提供全局集成机制。

执行该命令后，kmpkg集成将对所有使用MSBuild的项目启用（支持 清单模式 和 经典模式）。

此集成特定于执行命令的kmpkg实例，因此若有多个kmpkg实例，仅该实例的工具版本和安装的包可在项目中使用。

更多关于如何为单个项目或解决方案启用kmpkg集成的信息，请参考 MSBuild集成 文档。

解决步骤：

  1. 对要使用的kmpkg实例运行 kmpkg integrate install。

只需执行一次该命令，即可为所有项目启用该kmpkg实例的全局集成。

无法使用经典模式安装包​

使用 kmpkg install 命令失败，出现以下信息：

error: 无法在当前工作目录上方找到清单文件（kmpkg.json）。
此kmpkg分发版没有经典模式实例。

原因1：使用Visual Studio内置的kmpkg副本​

Visual Studio 2022包含一个可通过C++工作流安装的kmpkg副本。该捆绑版kmpkg安装在只读位置，因此无法用于 经典模式。

你可能正在使用Visual Studio嵌入式终端或VS Developer PowerShell，其PATH中包含该捆绑版kmpkg。

解决步骤：

  1. 创建清单文件（kmpkg.json）安装项目依赖；
  2. 若有独立的kmpkg实例，可通过设置 KMPKG_ROOT 变量并将安装路径添加到 PATH 变量来使用：
$env:KMPKG_ROOT="path/to/standalone/kmpkg"
$env:PATH="$env:PATH;$env:KMPKG_ROOT"

问题未列出？​

若你的问题未在本文中列出，请访问 我们的仓库 创建新问题。