# 9.1.pkg-message（安装二进制包时显示的消息文件）

为了在安装包时显示一条消息，可以将消息放在 **pkg-message** 文件中。此功能通常用于在执行 `pkg install` 或 `pkg upgrade` 后显示安装过程中需要采取的额外步骤。

***

> **重要**
>
> * **pkg-message** 必须只包含对 FreeBSD 设置和操作至关重要的信息，并且该信息必须是特定于该 Port 的。
> * 设置信息应仅在首次安装时显示。升级说明应仅在从相关版本升级时显示。
> * 请勿在消息中添加空格或符号行（如 `----------`、\`\` 或 `==========`）。将格式设置交给 [pkg(8)](https://man.freebsd.org/cgi/man.cgi?query=pkg\&sektion=8\&format=html)。
> * 提交者有权使用 UCL 格式规范将现有消息限制为安装或升级范围。
> * 请务必使用正确的工具来处理服务。
> * 使用 `service name start` 启动服务，而不是使用 `/usr/local/etc/rc.d/name start`。
> * 使用 `sysrc name_enable=YES` 修改 rc.conf 中的选项。

pkg-message 支持两种格式：

* **raw**\
  普通的纯文本文件。其消息仅在安装时显示。
* **UCL**\
  如果文件以“\[”开头，则它会被视为 UCL 文件。UCL 格式的详细说明请参见 [libucl 的 GitHub 页面](https://github.com/vstakhov/libucl)。

> **注意**
>
> 请不要在 **pkg-plist** 中添加 **pkg-message** 的条目。

## 9.1.1. **pkg-message UCL**

该格式如下。它应为对象的数组。每个对象可以包含以下关键字：

* `message`\
  要显示的实际消息。此关键字是强制性的。
* `type`\
  消息应显示的时机。
* `maximum_version`\
  仅在 `type` 为 `upgrade` 时使用。仅在升级自严格低于指定版本的情况下显示。
* `minimum_version`\
  仅在 `type` 为 `upgrade` 时使用。仅在升级自严格高于指定版本的情况下显示。

`maximum_version` 和 `minimum_version` 可以组合使用。

`type` 关键字可以有三种值：

* `install`\
  仅在安装包时显示该消息。
* `remove`\
  仅在删除包时显示该消息。
* `upgrade`\
  仅在升级包时显示该消息。

> **重要**
>
> 为了与非 UCL 格式的 **pkg-message** 文件保持兼容，UCL **pkg-message** 的第一行 *必须是* 一个单独的“\[”，最后一行 *必须是* 一个单独的“]”。

**示例 1. UCL 短字符串**

消息由双引号 `" "` 分隔，用于简单的单行字符串：

```ini
[
{ type: install
  message: "Simple message"
}
]
```

**示例 2. UCL 多行字符串**

多行字符串使用标准的 here 文档语法。多行定界符 *必须* 紧跟在 `<<` 符号后，没有任何空格，并且 *必须* 只包含大写字母。要结束多行字符串，在单独的一行中添加定界符字符串，不带任何空格。来自 [UCL 短字符串](https://docs.freebsd.org/en/books/porters-handbook/pkg-files/#porting-message-ucl-short-ex) 的消息可以写成：

```ini
[
{ type: install
  message: <<EOM
Simple message
EOM
}
]
```

**示例 3. 在安装/卸载时显示消息**

当消息仅需要在安装或卸载时显示时，设置 `type`：

```ini
[
{
  type: remove
  message: "package being removed."
}
{ type: install, message: "package being installed."}
]
```

**示例 4. 显示升级时的消息**

当升级 Port 时，显示的消息可以更加符合 Port 的需要。

```
[
{
  type: upgrade
  message: "Package is being upgraded."
}
{
  type: upgrade
  maximum_version: "1.0"
  message: "Upgrading from before 1.0 need to do this."
}
{
  type: upgrade
  minimum_version: "1.0"
  message: "Upgrading from after 1.0 should do that."
}
{
  type: upgrade
  maximum_version: "3.0"
  minimum_version: "1.0"
  message: "Upgrading from > 1.0 and < 3.0 remove that file."
}
]
```

当显示升级时的消息时，限制显示给用户的时机非常重要。大多数时候，这是通过使用 `maximum_version` 来限制消息的使用，以确保它仅在从某个特定版本之前的版本进行升级时显示。