Chapter 9. pkg-*

Table of Contents
9.1. pkg-message
9.2. pkg-install
9.3. pkg-deinstall
9.4. Changing the Names of pkg-*
9.5. Making Use of SUB_FILES and SUB_LIST

There are some tricks we have not mentioned yet about the pkg-* files that come in handy sometimes.

9.1. pkg-message

To display a message when the package is installed, place the message in pkg-message. This capability is often useful to display additional installation steps to be taken after a pkg install or pkg upgrade.

Important:

  • pkg-message must contain only information that is vital to setup and operation on FreeBSD, and that is unique to the port in question.

  • Setup information should only be shown on initial install. Upgrade instructions should be shown only when upgrading from the relevant version.

  • Do not surround the messages with either whitespace or lines of symbols (like ----------, **********, or ==========). Leave the formatting to pkg(8).

  • Committers have blanket approval to constrain existing messages to install or upgrade ranges using the UCL format specifications.

pkg-message supports two formats:

raw

A regular plain text file. Its message is always displayed, on install, and on upgrade.

UCL

If the file starts with [ then it is considered to be a UCL file. The UCL format is described on libucl's GitHub page.

Note:

Do not add an entry for pkg-message in pkg-plist.

9.1.1. UCL in pkg-message

The format is the following. It should be an array of objects. The objects themselves can have these keywords:

message

The actual message to be displayed. This keyword is mandatory.

type

When the message should be displayed.

maximum_version

Only if type is upgrade. Display if upgrading from a version strictly lower than the version specified.

minimum_version

Only if type is upgrade. Display if upgrading from a version stictly greater than the version specified.

The maximum_version and minimum_version keywords can be combined.

The type keyword can have four values:

(no type specified)

The message is always displayed.

install

The message should only be displayed when the package is installed.

remove

The message should only be displayed when the package is removed.

upgrade

the message should only be displayed during an upgrade of the package..

Important:

To preserve the compatibility with non UCL pkg-message files, the first line of a UCL pkg-message MUST be a single [, and the last line MUST be a single ].

Example 9.1. UCL Short Strings

The message is delimited by double quotes ", this is used for simple single line strings:

[
{
  message: "Simple message"
}
]

Example 9.2. UCL Multiline Strings

Multiline strings use the standard here document notation. The multiline delimiter must start just after << symbols without any whitespace and it must consist of capital letters only. To finish a multiline string, add the delimiter string on a line of its own without any whitespace. The message from Example 9.1, “UCL Short Strings” can be written as:

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

Example 9.3. Always Display a Message

If a port has a pkg-message containing simple text, it can be transformed into UCL easily. Given this pkg-message:

*   BIND requires configuration of rndc, including a "secret" key.   *
*    The easiest, and most secure way to configure rndc is to run    *
*   'rndc-confgen -a' to generate the proper conf file, with a new   *
*            random key, and appropriate file permissions.           *
[
{
  message: <<EOD
*   BIND requires configuration of rndc, including a "secret" key.   *
*    The easiest, and most secure way to configure rndc is to run    *
*   'rndc-confgen -a' to generate the proper conf file, with a new   *
*            random key, and appropriate file permissions.           *
EOD
}
]

Example 9.4. Display a Message on Install/Deinstall

When a message only needs to be displayed on installation or uninstallation, set the type:

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

Example 9.5. Display a Message on Upgrade

When a port is upgraded, the message displayed can be even more tailored to the port's needs.

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

All FreeBSD documents are available for download at https://download.freebsd.org/ftp/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.