Differential D20512 Diff 58225 en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml

Changeset View

Standalone View

en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml

Show All 18 Lines	<sect1 xml:id="porting-message">
<title><filename>pkg-message</filename></title>		<title><filename>pkg-message</filename></title>

<para>To display a message when the package is installed,		<para>To display a message when the package is installed,
place the message in <filename>pkg-message</filename>. This		place the message in <filename>pkg-message</filename>. This
capability is often useful to display additional installation		capability is often useful to display additional installation
steps to be taken after a <command>pkg install</command> or to		steps to be taken after a <command>pkg install</command> or to
display licensing information.</para>		display licensing information.</para>

<para>When some lines about the build-time knobs or warnings		<para>pkg-message supports two formats:</para>
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>

<programlisting>update-etc-shells:		<variablelist>
@${ECHO_MSG} "updating /etc/shells"		<varlistentry>
@${CP} /etc/shells /etc/shells.bak		<term>raw</term>
@( ${GREP} -v ${PREFIX}/bin/bash /etc/shells.bak; \
${ECHO_CMD} ${PREFIX}/bin/bash) >/etc/shells
@${RM} /etc/shells.bak</programlisting>

		<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>		<note>
<para>Do not add an entry for <filename>pkg-message</filename>		<para>Do not add an entry for <filename>pkg-message</filename>
in <filename>pkg-plist</filename>.</para>		in <filename>pkg-plist</filename>.</para>
</note>		</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>
		bcrUnsubmitted Done Inline Actions "mandatory" needs to be indented below the first a of the <para> above. bcr: "mandatory" needs to be indented below the first a of the <para> above.
		</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>
		baptUnsubmitted Done Inline Actions in reality it can have 3 values or not exists at all. if that is what people do understand with this (I know this is what I wrote in my txt file :)) then I am fine bapt: in reality it can have 3 values or not exists at all. if that is what people do understand with…
		matAuthorUnsubmitted Done Inline Actions The examples should show what this means. mat: The examples should show what this means.

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

<sect1 xml:id="pkg-install">		<sect1 xml:id="pkg-install">
<title><filename>pkg-install</filename></title>		<title><filename>pkg-install</filename></title>

<para>If the port needs to execute commands when the binary		<para>If the port needs to execute commands when the binary
package is installed with <command>pkg add</command> or		package is installed with <command>pkg add</command> or
<command>pkg install</command>, use		<command>pkg install</command>, use
▲ Show 20 Lines • Show All 166 Lines • Show Last 20 Lines