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

还有一些关于 pkg-* 文件的技巧尚未提及，它们有时会派上用场。

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

---

重要

• pkg-message 必须只包含对 FreeBSD 设置和操作至关重要的信息，并且该信息必须是特定于该 Port 的。
• 设置信息应仅在首次安装时显示。升级说明应仅在从相关版本升级时显示。
• 请勿用空格或符号行（如 ----------、********** 或 ==========）包围消息。将格式设置交给 pkg(8)。
• 提交者有权使用 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 页面。

注意

请不要在 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 短字符串

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

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

示例 2. UCL 多行字符串

多行字符串使用标准的 here 文档语法。多行定界符 必须 紧跟在 << 符号后，没有任何空格，并且 必须 只包含大写字母。要结束多行字符串，在单独的一行中添加定界符字符串，不带任何空格。来自 UCL 短字符串 的消息可以写成：

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

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

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

[
{
  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 将消息限制为仅在从特定版本之前的版本升级时显示。