跳到主要内容

清单模式

kmpkg 支持两种操作模式：经典模式和清单模式。对于大多数用户，我们推荐使用清单模式。

清单模式通过声明式 JSON 文件描述项目或包的元数据，清单文件必须命名为 kmpkg.json。

当工作目录中存在清单文件（kmpkg.json）时，运行 kmpkg install 命令即可启用清单模式。下文将详细介绍如何在清单模式下安装包。

清单模式是使用高级功能的前提，例如版本控制和自定义注册表。

端口中的清单文件​

所有 kmpkg 端口都必须包含 kmpkg.json 文件，用于描述其安装包的元数据。

kmpkg 会利用包清单中的元数据完成多种操作，例如计算依赖树、按名称或描述搜索包、解析功能等。

包清单示例​

{
  "name": "fmt",
  "version": "10.1.1",
  "description": "C++ 格式化库，可作为 printf 的安全替代方案或 IOStreams 的高效替代方案。",
  "homepage": "https://github.com/fmtlib/fmt",
  "license": "MIT",
  "dependencies": [
    {
      "name": "kmpkg-cmake",
      "host": true
    },
    {
      "name": "kmpkg-cmake-config",
      "host": true
    }
  ]
}

项目中的清单文件​

项目中使用清单文件的核心目的是声明依赖项。通过项目清单，你可以指定版本约束和覆盖规则，以锁定依赖项的特定版本——这一特性在经典模式中不可用。

项目清单示例​

{
  "dependencies": [ "fmt", "zlib" ],
  "builtin-baseline": "3426db05b996481ca31e95fff3734cf23e0f51bc",
  "overrides": [
    { "name": "zlib", "version": "1.2.8" }
  ]
}

配置文件​

kmpkg 可通过 kmpkg-configuration.json 文件进行配置，例如添加更多包注册表或覆盖端口和三元组的路径。

配置文件示例​

{
  "default-registry": {
    "kind": "git",
    "baseline": "7476f0d4e77d3333fbb249657df8251c28c4faae",
    "repository": "https://github.com/kumose/kmpkg"
  },
  "registries": [
    {
      "kind": "git",
      "repository": "https://github.com/MicrosoftDocs/kmpkg-docs",
      "reference": "kmpkg-registry",
      "baseline": "768f6a3ad9f9b6c4c2ff390137690cf26e3c3453",
      "packages": [ "beicode", "beison" ]
    }
  ],
  "overlay-ports": [
    "C:\\dev\\my_kmpkg_ports"
  ]
}

在清单模式下安装包​

要通过清单文件安装包，需执行 kmpkg install 命令（无需指定包参数）。该命令必须在包含清单文件 kmpkg.json 的目录中运行，或通过 --x-manifest-root=<path> 选项指定清单文件路径。

与经典模式不同，清单模式下安装的包不会放入全局 installed 目录，而是为每个清单创建独立的安装目录 kmpkg_installed（位于清单文件所在目录）。

每个清单拥有独立的安装目录，可实现不同项目间的依赖隔离——这解决了经典模式的核心限制（同一端口只能安装一个版本），清单模式会为每个项目单独维护端口版本。

在项目清单中使用功能​

清单文件可通过 "features" 字段定义累加性的功能集、行为及依赖项。

在项目中，你可以通过功能启用或禁用特定于项目部分的依赖项。例如，若项目包含多个组件，可将公共依赖项放在 "dependencies" 列表中，而将组件专属依赖项限制在对应功能中。

启用项目功能的方式有以下几种：

示例：项目清单中的功能​

{
  "name": "my-game",
  "dependencies": [ "grpc" ],
  "features": {
    "client": {
      "description": "客户端游戏可执行文件",
      "dependencies": [ "sdl2", "bullet3" ]
    },
    "server": {
      "description": "多人服务器可执行文件",
      "dependencies": [ "proxygen" ]
    },
    "tests": {
      "description": "开发测试",
      "dependencies": [ "gtest" ]
    }
  }
}

仅安装“client”组件的依赖项，执行以下命令：

kmpkg install --x-feature=client

后续操作​

你可尝试完成以下任务：