Date: Thu, 6 Jun 2019 11:26:55 +0000 (UTC) From: Mathieu Arnold <mat@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r53113 - head/en_US.ISO8859-1/books/porters-handbook/pkg-files Message-ID: <201906061126.x56BQtSn019254@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
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">
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201906061126.x56BQtSn019254>