Chapter 9. `pkg-*`
Prev		Next

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 only displayed on install.
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 three values:

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:

[
{ type: install
  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:

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

Example 9.3. Display a Message on Install/Deinstall

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

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

Example 9.4. Display a Message on Upgrade

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

[
{
  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."
}
]

Important:

When displaying a message on upgrade, it is important to limit when it is being shown to the user. Most of the time it is by using maximum_version to limit its usage to upgrades from before a certain version when something specific needs to be done.

Prev		Next
8.6. Expanding Package List with Keywords	Home	9.2. `pkg-install`

Chapter 9. pkg-*

9.1. pkg-message

Important:

Note:

9.1.1. UCL in pkg-message

Important:

Important:

Chapter 9. `pkg-*`

9.1. `pkg-message`

9.1.1. UCL in `pkg-message`