svn commit: r53113 - head/en_US.ISO8859-1/books/porters-handbook/pkg-files
Mathieu Arnold
mat at FreeBSD.org
Thu Jun 6 11:26:56 UTC 2019
Author: mat
Date: Thu Jun 6 11:26:55 2019
New Revision: 53113
URL: https://svnweb.freebsd.org/changeset/doc/53113
Log:
Document using UCL in pkg-message.
Reviewed by: bapt, bcr
Differential Revision: https://reviews.freebsd.org/D20512
Modified:
head/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml
Modified: head/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml Thu Jun 6 02:39:50 2019 (r53112)
+++ head/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml Thu Jun 6 11:26:55 2019 (r53113)
@@ -24,26 +24,232 @@
steps to be taken after a <command>pkg install</command> or to
display licensing information.</para>
- <para>When some lines about the build-time knobs or warnings
- have to be displayed, use <varname>ECHO_MSG</varname>.
- <filename>pkg-message</filename> is only for
- post-installation steps. Likewise, the distinction between
- <varname>ECHO_MSG</varname> is for printing
- informational text to the screen and <varname>ECHO_CMD</varname>
- is for
- command pipelining:</para>
+ <para>pkg-message supports two formats:</para>
- <programlisting>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</programlisting>
+ <variablelist>
+ <varlistentry>
+ <term>raw</term>
+ <listitem>
+ <para>A regular plain text file. Its message is always
+ displayed, on install, and on upgrade.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><acronym>UCL</acronym></term>
+
+ <listitem>
+ <para>If the file starts with
+ <quote><literal>[</literal></quote> then it is considered
+ to be a <acronym>UCL</acronym> file. The
+ <acronym>UCL</acronym> format is
+ described on <link
+ xlink:href="https://github.com/vstakhov/libucl">libucl's
+ GitHub page</link>.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
<note>
<para>Do not add an entry for <filename>pkg-message</filename>
in <filename>pkg-plist</filename>.</para>
</note>
+
+ <sect2 xml:id="porting-message-ucl">
+ <title><acronym>UCL</acronym> in
+ <filename>pkg-message</filename></title>
+
+ <para>The format is the following. It should be an array of
+ objects. The objects themselves can have these
+ keywords:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>message</literal></term>
+
+ <listitem>
+ <para>The actual message to be displayed. This keyword is
+ mandatory.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>type</literal></term>
+
+ <listitem>
+ <para>When the message should be displayed.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>maximum_version</literal></term>
+
+ <listitem>
+ <para>Only if <literal>type</literal> is
+ <literal>upgrade</literal>. Display if upgrading from a
+ version strictly lower than the version
+ specified.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>minimum_version</literal></term>
+
+ <listitem>
+ <para>Only if <literal>type</literal> is
+ <literal>upgrade</literal>. Display if upgrading from a
+ version stictly greater than the version
+ specified.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>The <literal>maximum_version</literal> and
+ <literal>minimum_version</literal> keywords can be
+ combined.</para>
+
+ <para>The <literal>type</literal> keyword can have four
+ values:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>(no type specified)</term>
+
+ <listitem>
+ <para>The message is always displayed.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>install</literal></term>
+
+ <listitem>
+ <para>The message should only be displayed when the
+ package is installed.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>remove</literal></term>
+
+ <listitem>
+ <para>The message should only be displayed when the
+ package is removed.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>upgrade</literal></term>
+
+ <listitem>
+ <para>the message should only be displayed during an
+ upgrade of the package..</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <tip>
+ <para>UCL allows for two kind of strings, either delimited
+ by double quotes
+ <literal>"<replaceable>foo</replaceable>"</literal>, or as a
+ here document. These two
+ are equivalent:</para>
+
+ <programlisting>[
+{ message: "Always displayed"
+}
+]</programlisting>
+
+ <programlisting>[
+{ message: <<EOM
+Always displayed
+EOM
+}
+]</programlisting>
+ </tip>
+
+ <warning>
+ <para>To preserve the compatibility with non
+ <acronym>UCL</acronym> <filename>pkg-message</filename>
+ files, the first line of a <acronym>UCL</acronym>
+ <filename>pkg-message</filename> <emphasis>MUST
+ be</emphasis> a single
+ <quote><literal>[</literal></quote>, and the last line
+ <emphasis>MUST be</emphasis> a single
+ <quote><literal>]</literal></quote>.</para>
+ </warning>
+
+ <example xml:id="porting-message-ucl-ex1">
+ <title>Always Display a Message</title>
+
+ <para>If a port has a <filename>pkg-message</filename>
+ containing simple text, it can be transformed into
+ <acronym>UCL</acronym> easily. Given this
+ <filename>pkg-message</filename>:</para>
+
+ <programlisting>* 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. *</programlisting>
+
+ <programlisting>[
+{
+ 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
+}
+]</programlisting>
+ </example>
+
+ <example xml:id="porting-message-ucl-ex2">
+ <title>Display a Message on Install/Deinstall</title>
+
+ <para>When a message only needs to be displayed on
+ installation or uninstallation, set the type:</para>
+
+ <programlisting>[
+{
+ message: "package being removed."
+ type: remove
+}
+{ message: "package being installed.", type: install }
+]</programlisting>
+ </example>
+
+ <example xml:id="porting-message-ucl-ex3">
+ <title>Display a Message on Upgrade</title>
+
+ <para>When a port is upgraded, the message displayed can be
+ even more tailored to the port's needs.</para>
+
+ <programlisting>[
+{
+ 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
+}
+]</programlisting>
+ </example>
+ </sect2>
</sect1>
<sect1 xml:id="pkg-install">
More information about the svn-doc-head
mailing list