Index: head/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml (revision 53112) +++ head/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml (revision 53113) @@ -1,220 +1,426 @@ <filename>pkg-*</filename> There are some tricks we have not mentioned yet about the pkg-* files that come in handy sometimes. <filename>pkg-message</filename> 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 to display licensing information. - When some lines about the build-time knobs or warnings - have to be displayed, use ECHO_MSG. - pkg-message is only for - post-installation steps. Likewise, the distinction between - ECHO_MSG is for printing - informational text to the screen and ECHO_CMD - is for - command pipelining: + pkg-message supports two formats: - update-etc-shells: - @${ECHO_MSG} "updating /etc/shells" - @${CP} /etc/shells /etc/shells.bak - @( ${GREP} -v ${PREFIX}/bin/bash /etc/shells.bak; \ - ${ECHO_CMD} ${PREFIX}/bin/bash) >/etc/shells - @${RM} /etc/shells.bak + + + 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. + + + + Do not add an entry for pkg-message in pkg-plist. + + + <acronym>UCL</acronym> in + <filename>pkg-message</filename> + + 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.. + + + + + + UCL allows for two kind of strings, either delimited + by double quotes + "foo", or as a + here document. These two + are equivalent: + + [ +{ message: "Always displayed" +} +] + + [ +{ message: <<EOM +Always displayed +EOM +} +] + + + + 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 + ]. + + + + 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 +} +] + + + + 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 } +] + + + + 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 +} +] + + <filename>pkg-install</filename> 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. <filename>pkg-deinstall</filename> 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. Changing the Names of <filename>pkg-<replaceable>*</replaceable></filename> 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 Making Use of <varname>SUB_FILES</varname> and <varname>SUB_LIST</varname> 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%%/share/examples/putsy/%%ARCH%%.conf into your home directory as .putsy.conf and edit it.