跳到主要内容

kmpkg install

命令概要​

  • 经典模式
kmpkg install [options] <package>...
  • 清单模式
kmpkg install [options]

命令描述​

构建并安装端口包。

经典模式​

在经典模式下，该命令会将端口包添加到已安装目录（默认是 kmpkg 根目录下的 installed/）中已有的包集合里。此操作可能需要移除并重新构建现有包，过程中可能失败。

包规格语法​

端口名[功能1,功能2]:三元组

未指定三元组的包引用会自动使用默认目标三元组进行限定。未显式列出 core 功能的包引用，默认视为包含所有默认功能。

清单模式​

在清单模式下，该命令会将已安装目录的状态调整为 kmpkg.json 清单文件指定的状态，按需添加、移除或重新构建包。

命令选项​

所有 kmpkg 命令均支持一组通用选项。

--allow-unsupported​

遇到不支持的端口时不终止操作，仅发出警告并继续执行。

默认情况下，若安装计划中包含的端口安装目标三元组不在其 "supports" 字段范围内，kmpkg 会拒绝执行。包的 "supports" 字段描述了该包预期可构建的完整平台集合。此参数会让 kmpkg 仅发出“构建可能失败”的警告，而非直接终止操作。

--clean-after-build​

每个包构建完成后，清理 buildtrees、packages 和 downloads 目录。

该选项等效于同时指定 --clean-buildtrees-after-build、--clean-downloads-after-build 和 --clean-packages-after-build。

--clean-buildtrees-after-build​

每个包构建完成后，清理 buildtrees 临时子目录下的所有子文件夹。

buildtrees 子目录下的所有顶层文件（如 buildtrees/zlib/config-x64-windows-out.log）会被保留，所有子目录会被删除。

--clean-downloads-after-build​

每个包构建完成后，清理 downloads/ 目录下所有未解压的资源文件。

downloads/ 目录下的所有顶层文件会被删除，已解压的工具会被保留。

--clean-packages-after-build​

每个包构建完成后，清理该包对应的 packages 临时子目录。

已构建包对应的 packages 子目录（例如 packages/zlib_x64-windows）会在安装完成后被删除。

--dry-run​

打印安装计划，但不执行任何包的移除或安装操作。

安装计划会列出所有待安装的包和功能，以及需要移除并重新构建的其他包。

--editable​

  • 仅经典模式支持

对命令行中直接引用的所有包执行可编辑构建。

kmpkg 构建端口时，默认每次都会清空并重新解压源代码，以确保输入内容的准确性。这对于清单模式准确更新已安装内容、以及二进制缓存确保缓存内容正确至关重要。

指定 --editable 参数会禁用此行为，保留对 buildtrees/ 目录中已解压源代码的修改。这有助于快速开发补丁，无需每次修改都编写补丁文件。

可编辑构建过程中解压的源代码目录名称不会带有 .clean/ 后缀，且后续非可编辑构建不会清理这些目录。

--enforce-port-checks​

若端口检测到问题或尝试使用已弃用功能，则终止安装并报错。

默认情况下，kmpkg 会对已构建的包执行多项检查，若检测到问题仅发出警告。此参数会将这些警告升级为错误，直接终止安装。

--x-feature=<feature>​

本节介绍的是实验性功能，可能随时发生变更或被移除。

  • 仅清单模式支持

指定从 kmpkg.json 中额外安装的功能对应的依赖项。

默认情况下，仅会安装 "dependencies" 以及 "default-features" 所依赖的包。

--head​

  • 仅经典模式支持

要求命令行中显式引用的所有包在构建时拉取最新可用的源代码。

该参数仅用于临时测试，不建议在生产环境或长期使用场景下使用。它会禁用二进制缓存对所有显式引用包及其依赖项的支持，因为 kmpkg 无法准确追踪所有输入内容。

--keep-going​

首次构建失败后，继续执行剩余的安装计划。

默认情况下，kmpkg 会在首个包构建失败时立即终止操作。此参数会让 kmpkg 继续构建和安装安装计划中不依赖于失败包的其他部分。

--x-no-default-features​

本节介绍的是实验性功能，可能随时发生变更或被移除。

  • 仅清单模式支持

不安装顶层清单文件中指定的默认功能。

清单模式下执行 install 命令时，默认会安装 "default-features" 中列出的所有功能对应的依赖项。此参数会禁用该行为，仅安装通过 --x-feature 显式启用的功能对应的依赖项。

--no-downloads​

构建包时，禁止端口在构建过程中下载新的资源文件。

默认情况下，端口会根据需要从互联网获取源代码和工具（受资源缓存规则约束）。此参数会阻止下载操作，仅允许端口使用此前已下载并缓存在本地的资源。

--only-downloads​

尝试下载安装计划所需的所有资源，但不执行任何构建操作。

指定该选项后，kmpkg 会运行安装计划中的每个构建流程，直到执行首次非下载类的外部进程调用。大多数端口会在首次外部进程调用（通常是调用构建系统）前完成所有下载操作，因此该操作可下载所有必需资源。未遵循此流程的端口，其资源将无法被预下载。

--only-binarycaching​

拒绝执行任何构建操作，仅从二进制缓存恢复包。

该参数会阻止 kmpkg 按需执行构建，若在所有二进制缓存中均未找到目标包，则操作会失败。

--recurse​

  • 仅经典模式支持

批准需要重新构建包的安装计划。

若要修改已安装包的功能集合，kmpkg 必须先移除该包并重新构建。由于此操作可能失败，导致安装目录中的包数量少于操作前，因此用户需通过指定该参数来批准包含包重建的安装计划。

--x-write-nuget-packages-config​

本节介绍的是实验性功能，可能随时发生变更或被移除。

生成 NuGet packages.config 格式的文件，供二进制缓存使用。

该选项可与 --dry-run 配合使用，在不构建或安装任何包的情况下，获取二进制缓存所需的 NuGet 包列表。这允许单独调用 NuGet 命令行工具以实现高级场景，例如使用替代协议获取 .nupkg 文件。

--no-print-usage​

禁止在安装完成后生成并打印使用说明文本。