Chapter 9. pkg-* | FreeBSD Documentation Portal
Description: Tricks about the pkg-* files
Keywords: pkg,pkg-message,UCL,pkg-install,pkg-deinstall

# Chapter 9. pkg-*

This translation may be out of date. To help with the translations please access the FreeBSD translations instance.

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`.

| 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.

| 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..

| 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 “]”.

例 1. UCL Short Strings

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

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

例 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 UCL Short Strings can be written as:

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

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

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

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.

## 9.2. pkg-install

If the port needs to execute commands when the binary package is installed with `pkg add` or `pkg install`, use pkg-install. This script will automatically be added to the package. It will be run twice by `pkg`, the first time as `${SH} pkg-install ${PKGNAME} PRE-INSTALL` before the package is installed, and the second time as `${SH} pkg-install ${PKGNAME} POST-INSTALL` after it has been installed. `$2` can be tested to determine which mode the script is being run in. The `PKG_PREFIX` environmental variable will be set to the package installation directory.

| This script is here to help you set up the package so that it is as ready to use as possible. It must not be abused to start services, stop services, or run any other commands that will modify the currently running system.

## 9.3. pkg-deinstall

This script executes when a package is removed.

This script will be run twice by `pkg delete`. The first time as `${SH} pkg-deinstall ${PKGNAME} DEINSTALL` before the port is de-installed and the second time as `${SH} pkg-deinstall ${PKGNAME} POST-DEINSTALL` after the port has been de-installed. `$2` can be tested to determine which mode the script is being run in. The `PKG_PREFIX` environmental variable will be set to the package installation directory

| This script is here to help you set up the package so that it is as ready to use as possible. It must not be abused to start services, stop services, or run any other commands that will modify the currently running system.

## 9.4. Changing the Names of pkg-*

All the names of pkg-* are defined using variables that can be changed in the Makefile if needed. This is especially useful when sharing the same pkg-* files among several ports or when it is necessary to write to one of these files. See writing to places other than `WRKDIR` for why it is a bad idea to write directly into the directory containing the pkg-* files.

Here is a list of variable names and their default values. (`PKGDIR` defaults to `${MASTERDIR}`.)

Variable | Default value
--- | ---
`DESCR` | `${PKGDIR}/pkg-descr`
`PLIST` | `${PKGDIR}/pkg-plist`
`PKGINSTALL` | `${PKGDIR}/pkg-install`
`PKGDEINSTALL` | `${PKGDIR}/pkg-deinstall`
`PKGMESSAGE` | `${PKGDIR}/pkg-message`

## 9.5. Making Use of `SUB_FILES` and `SUB_LIST`

`SUB_FILES` and `SUB_LIST` are useful for dynamic values in port files, such as the installation `PREFIX` in pkg-message.

`SUB_FILES` specifies a list of files to be automatically modified. Each file in the `SUB_FILES` list must have a corresponding file.in present in `FILESDIR`. A modified version will be created as ${WRKDIR}/file. Files defined as a value of `USE_RC_SUBR` are automatically added to `SUB_FILES`. For the files pkg-message, pkg-install, and pkg-deinstall, the corresponding Makefile variable is automatically set to point to the processed version.

`SUB_LIST` is a list of `VAR=VALUE` pairs. For each pair, `%%VAR%%` will be replaced with `VALUE` in each file listed in `SUB_FILES`. Several common pairs are automatically defined: `PREFIX`, `LOCALBASE`, `DATADIR`, `DOCSDIR`, `EXAMPLESDIR`, `WWWDIR`, and `ETCDIR`. Any line beginning with `@comment` followed by a space, will be deleted from resulting files after a variable substitution.

This example replaces `%%ARCH%%` with the system architecture in a pkg-message:

    SUB_FILES=	pkg-message
    SUB_LIST=	ARCH=${ARCH}

Note that for this example, pkg-message.in must exist in `FILESDIR`.

Example of a good pkg-message.in:

    Now it is time to configure this package.
    Copy %%PREFIX%%/shared/examples/putsy/%%ARCH%%.conf into your home directory
    as .putsy.conf and edit it.

最後修改於: February 18, 2025 由 Fernando Apesteguía

Prev
Home
Next