# 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` 来限制消息的使用，以确保它仅在从某个特定版本之前的版本进行升级时显示。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://porters-handbook.bsdcn.org/di-9-zhang-pkg/9.1.pkgmessage-an-zhuang-er-jin-zhi-bao-shi-xian-shi-de-xiao-xi-wen-jian.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.