覆盖端口（Overlay Ports）

通常，kmpkg 端口来自于注册表。你安装的大多数端口很可能都来自官方 kmpkg 注册表（地址：https://github.com/kumose/kmpkg）。kmpkg 允许你通过文件系统安装端口，这类端口被称为覆盖端口。

覆盖端口可作为现有端口的无缝替代，或作为注册表中未提供的新端口。在包名解析过程中，覆盖端口具有优先级。

覆盖端口的优先级顺序

覆盖端口按以下顺序进行解析（优先级从高到低）：

1. 命令行通过 --overlay-ports 指定的目录；若该目录没有 CONTROL 或 kmpkg.json 文件，则检查其命名子目录。
2. kmpkg-configuration.json 文件中通过 overlay-ports 指定的目录；若该目录没有 CONTROL 或 kmpkg.json 文件，则检查其命名子目录。
3. 环境变量 KMPKG_OVERLAY_PORTS 中指定的目录列表；若某个目录没有 CONTROL 或 kmpkg.json 文件，则检查其命名子目录。

解析包名时，会选择第一个包含匹配覆盖端口的位置。

使用覆盖端口

若指定了覆盖端口目录，kmpkg 会首先尝试将该目录作为端口加载：

• 若加载成功，该目录直接被视为一个端口，端口名称从 CONTROL 或 kmpkg.json 文件中提取。
• 若加载失败，则会检查该目录下与端口名匹配的子目录。

有效端口需包含 portfile.cmake 文件，且需同时包含 kmpkg.json 或 CONTROL 文件。

目录结构示例

假设有以下目录结构：

• x/kmpkg.json："name" 字段设为 "a"
• x/portfile.cmake：a 的相关构建指令
• x/b/kmpkg.json："name" 字段设为 "b"
• x/b/portfile.cmake：b 的相关构建指令
• y/c/kmpkg.json："name" 字段设为 "c"
• y/c/portfile.cmake：c 的相关构建指令
• y/d/kmpkg.json："name" 字段设为 "d"
• y/d/portfile.cmake：d 的相关构建指令

不同配置下 kmpkg 识别的端口如下：

• --overlay-ports=x：该覆盖包含 1 个端口（a），名称来自 x/kmpkg.json，子目录 b 不被考虑。
• --overlay-ports=x/b：该覆盖包含 1 个端口（b），名称来自 x/b/kmpkg.json。
• --overlay-ports=y：该覆盖包含 2 个端口（c 和 d），名称来自 y 的子目录名；且其子目录中 kmpkg.json 声明的名称必须与子目录名一致，否则在请求安装 c 或 d 时会报错。

配置覆盖端口的方式

可通过以下多种方式配置覆盖端口：

1. 命令行：添加一个或多个 --overlay-ports=<directory> 选项。
2. 配置文件：在 kmpkg-configuration.json 中填充 "overlay-ports" 数组。
3. 环境变量：将 KMPKG_OVERLAY_PORTS 设置为路径字符分隔列表（Windows 用分号 ;，Linux/macOS 用冒号 :）。

覆盖端口使用示例

Given this directory structure:

Run:

kmpkg install sqlite3 --overlay-ports=my-ports --overlay-ports=team-ports

To install:

• sqlite3 from my-ports

Run:

kmpkg install sqlite3 rapidjson curl \
    --overlay-ports=my-ports/rapidjson \
    --overlay-ports=kmpkg/ports/curl \
    --overlay-ports=team-ports

To install:

• sqlite3 from team-ports
• rapidjson from my-ports
• curl from kmpkg/ports

Example: Using overlay ports to use a system package manager dependency

To use a system package manager dependency over a kmpkg one, refer to our blog post.