mports porting guide - MidnightBSD/src GitHub Wiki

(based on FreeBSD documentation: https://docs.freebsd.org/en/books/porters-handbook/pkg-files/#porting-message)

To display a message when the package is installed, place it in the pkg-message file. This capability is often useful for displaying additional installation steps after a mport install or mport update.

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

Setup information should only be displayed during the 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 mport(8)

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

Please be sure to refer to the proper tools for handling services.

Use service name start to start a service rather than using /usr/local/etc/rc.d/name start

Use sysrc name_enable=YES to change options in rc.conf

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.

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

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

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

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
}
]

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

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.

If the port needs to execute commands when the binary package is installed with mport add or mport install use pkg-install. It is run twice by mport, 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 environment variable is set to the package installation directory.

If using pkg-pre-install or pkg-post-install instead, the script is run only once (before or after installing the package), with the single argument ${PKGNAME}. Using pkg-pre-install.lua or pkg-post-install.lua will run a lua script instead of a shell script. Lua scripts run by mport provide some extensions and a few restrictions

Using pkg-pre-install (or pkg-pre-install.lua) and pkg-post-install (or pkg-post-install.lua) is preferred to using pkg-install.

These scripts are automatically added to the packing list.

These scripts are here to simplify package configuration after installation. They must not be abused to start services, stop services, or run any other commands that will modify the currently running system.

These scripts execute when a package is removed.The pkg-deinstall script is run twice by mport 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 environment variable is set to the package installation directory.

The pkg-deinstall script is 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 environment variable is set to the package installation directory.

If using pkg-pre-deinstall or pkg-post-deinstall instead, the script is run only once (before or after deinstalling the package), with the single argument ${PKGNAME}. Using pkg-pre-deinstall.lua or pkg-post-deinstall.lua will run a lua script instead of a shell script. Lua scripts run by pkg provide some extensions and a few restrictions, both explained in pkg-lua-script(5).

Using pkg-pre-deinstall (or pkg-pre-deinstall.lua) and pkg-post-deinstall (or pkg-post-deinstall.lua) is preferred to using pkg-deinstall.

These scripts are automatically added to the packing list.

These scripts are here to simplify cleanup after package deinstallation. They must not be abused to start services, stop services, or run any other commands that will modify the currently running system.