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
+++ head/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml
@@ -24,26 +24,232 @@
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-messageMUST
+ 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
+}
+]
+
+