diff options
Diffstat (limited to 'en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml')
| -rw-r--r-- | en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml | 448 |
1 files changed, 0 insertions, 448 deletions
diff --git a/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml b/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml deleted file mode 100644 index cf85a100b2..0000000000 --- a/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml +++ /dev/null @@ -1,448 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<!-- - The FreeBSD Documentation Project - - $FreeBSD$ ---> - -<chapter xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" - xml:id="pkg-files"> - - <title><filename>pkg-*</filename></title> - - <para>There are some tricks we have not mentioned yet about the - <filename>pkg-<replaceable>*</replaceable></filename> files that - come in handy sometimes.</para> - - <sect1 xml:id="porting-message"> - <title><filename>pkg-message</filename></title> - - <para>To display a message when the package is installed, place - the message in <filename>pkg-message</filename>. This - capability is often useful to display additional installation - steps to be taken after a <command>pkg install</command> or - <command>pkg upgrade</command>.</para> - - <important> - <itemizedlist> - <listitem> - <para><filename>pkg-message</filename> must contain only - information that is <emphasis>vital</emphasis> to setup and - operation on &os;, and that is unique to the port in - question.</para> - </listitem> - - <listitem> - <para>Setup information should only be shown on initial install. - Upgrade instructions should be shown only when upgrading from - the relevant version.</para> - </listitem> - - <listitem> - <para>Do not surround the messages with either whitespace or - lines of symbols (like <literal>----------</literal>, - <literal>**********</literal>, or - <literal>==========</literal>). Leave the formatting to - &man.pkg.8;.</para> - </listitem> - - <listitem> - <para>Committers have blanket approval to constrain existing - messages to install or upgrade ranges using the - <acronym>UCL</acronym> format specifications.</para> - </listitem> - </itemizedlist> - </important> - - <para>pkg-message supports two formats:</para> - - <variablelist> - <varlistentry> - <term>raw</term> - - <listitem> - <para>A regular plain text file. Its message is only - displayed on install.</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 three - values:</para> - - <variablelist> - <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> - - <important> - <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> - </important> - - <example xml:id="porting-message-ucl-short-ex"> - <title><acronym>UCL</acronym> Short Strings</title> - - <para>The message is delimited by double quotes - <literal>"</literal>, this is used for simple single line - strings:</para> - - <programlisting>[ -{ type: install - message: "Simple message" -} -]</programlisting> - </example> - - <example xml:id="porting-message-ucl-multiline-ex"> - <title><acronym>UCL</acronym> Multiline Strings</title> - - <para>Multiline strings use the standard here document - notation. The multiline delimiter <emphasis>must</emphasis> - start just after <literal><<</literal> symbols without - any whitespace and it <emphasis>must</emphasis> consist of - capital letters only. To finish a multiline string, add the - delimiter string on a line of its own without any - whitespace. The message from <xref - linkend="porting-message-ucl-short-ex"/> can be written - as:</para> - - <programlisting>[ -{ type: install - message: <<EOM -Simple message -EOM -} -]</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>[ -{ - type: remove - message: "package being removed." -} -{ type: install, message: "package being installed."} -]</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>[ -{ - type: upgrade - message: "Package is being upgraded." -} -{ - type: upgrade - maximum_version: "1.0" - message: "Upgrading from before 1.0 need to do this." -} -{ - type: upgrade - minimum_version: "1.0" - message: "Upgrading from after 1.0 should do that." -} -{ - type: upgrade - maximum_version: "3.0" - minimum_version: "1.0" - message: "Upgrading from > 1.0 and < 3.0 remove that file." -} -]</programlisting> - - <important> - <para>When displaying a message on upgrade, it is important - to limit when it is being shown to the user. Most of the - time it is by using <literal>maximum_version</literal> to - limit its usage to upgrades from before a certain version - when something specific needs to be done.</para> - </important> - </example> - </sect2> - </sect1> - - <sect1 xml:id="pkg-install"> - <title><filename>pkg-install</filename></title> - - <para>If the port needs to execute commands when the binary - package is installed with <command>pkg add</command> or - <command>pkg install</command>, use - <filename>pkg-install</filename>. This script will - automatically be added to the package. It will be run twice by - <command>pkg</command>, the first time as <literal>${SH} - pkg-install ${PKGNAME} PRE-INSTALL</literal> before the - package is installed, and the second time as - <literal>${SH} pkg-install ${PKGNAME} - POST-INSTALL</literal> after it has been installed. - <literal>$2</literal> can be tested to determine which - mode the script is being run in. The <envar>PKG_PREFIX</envar> - environmental variable will be set to the package installation - directory.</para> - - <important> - <para>This script is here to help you set up the package so that - it is as ready to use as possible. It <emphasis>must - not</emphasis> be abused to start services, stop services, - or run any other commands that will modify the currently - running system.</para> - </important> - </sect1> - - <sect1 xml:id="pkg-deinstall"> - <title><filename>pkg-deinstall</filename></title> - - <para>This script executes when a package is removed.</para> - - <para>This script will be run twice by <command>pkg - delete</command> The first time as <literal>${SH} - pkg-deinstall ${PKGNAME} DEINSTALL</literal> before the - port is de-installed and the second time as - <literal>${SH} pkg-deinstall ${PKGNAME} - POST-DEINSTALL</literal> after the port has been de-installed. - <literal>$2</literal> can be tested to determine which - mode the script is being run in. The <envar>PKG_PREFIX</envar> - environmental variable will be set to the package installation - directory</para> - - <important> - <para>This script is here to help you set up the package so that - it is as ready to use as possible. It <emphasis>must - not</emphasis> be abused to start services, stop services, - or run any other commands that will modify the currently - running system.</para> - </important> - </sect1> - - <sect1 xml:id="pkg-names"> - <title xml:id="porting-pkgfiles">Changing the Names of - <filename>pkg-<replaceable>*</replaceable></filename></title> - - <para>All the names of - <filename>pkg-<replaceable>*</replaceable></filename> are - defined using variables that can be changed in the - <filename>Makefile</filename> if needed. This is especially - useful when sharing the same - <filename>pkg-<replaceable>*</replaceable></filename> files - among several ports or when it is necessary to write to one of - these files. - See <link linkend="porting-wrkdir">writing to places other than - <varname>WRKDIR</varname></link> for why it is a bad idea to - write directly into - the directory containing the - <filename>pkg-<replaceable>*</replaceable></filename> - files.</para> - - <para>Here is a list of variable names and their default values. - (<varname>PKGDIR</varname> defaults to - <varname>${MASTERDIR}</varname>.)</para> - - <informaltable frame="none" pgwide="0"> - <tgroup cols="2"> - <thead> - <row> - <entry>Variable</entry> - <entry>Default value</entry> - </row> - </thead> - - <tbody> - <row> - <entry><varname>DESCR</varname></entry> - <entry><literal>${PKGDIR}/pkg-descr</literal></entry> - </row> - - <row> - <entry><varname>PLIST</varname></entry> - <entry><literal>${PKGDIR}/pkg-plist</literal></entry> - </row> - - <row> - <entry><varname>PKGINSTALL</varname></entry> - <entry><literal>${PKGDIR}/pkg-install</literal></entry> - </row> - - <row> - <entry><varname>PKGDEINSTALL</varname></entry> - <entry><literal>${PKGDIR}/pkg-deinstall</literal></entry> - </row> - - <row> - <entry><varname>PKGMESSAGE</varname></entry> - <entry><literal>${PKGDIR}/pkg-message</literal></entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect1> - - <sect1 xml:id="using-sub-files"> - <title>Making Use of <varname>SUB_FILES</varname> and - <varname>SUB_LIST</varname></title> - - <para><varname>SUB_FILES</varname> and - <varname>SUB_LIST</varname> are useful for dynamic - values in port files, such as the installation - <varname>PREFIX</varname> in - <filename>pkg-message</filename>.</para> - - <para><varname>SUB_FILES</varname> specifies a list - of files to be automatically modified. Each - <filename><replaceable>file</replaceable></filename> in the - <varname>SUB_FILES</varname> list must have a corresponding - <filename><replaceable>file</replaceable>.in</filename> present - in <varname>FILESDIR</varname>. A modified version will be - created as - <filename>${WRKDIR}/<replaceable>file</replaceable></filename>. - Files defined as a value of <varname>USE_RC_SUBR</varname> are - automatically added to <varname>SUB_FILES</varname>. For the files - <filename>pkg-message</filename>, - <filename>pkg-install</filename>, and - <filename>pkg-deinstall</filename>, the corresponding Makefile - variable is automatically set to point to the processed - version.</para> - - <para><varname>SUB_LIST</varname> is a list of - <literal>VAR=VALUE</literal> pairs. For each pair, - <literal>%%VAR%%</literal> will be replaced with - <literal>VALUE</literal> in each file listed in - <varname>SUB_FILES</varname>. Several common pairs are - automatically defined: <varname>PREFIX</varname>, - <varname>LOCALBASE</varname>, <varname>DATADIR</varname>, - <varname>DOCSDIR</varname>, <varname>EXAMPLESDIR</varname>, - <varname>WWWDIR</varname>, and <varname>ETCDIR</varname>. Any - line beginning with <literal>@comment</literal> followed by a - space, will be deleted - from resulting files after a variable substitution.</para> - - <para>This example replaces - <literal>%%ARCH%%</literal> with the system architecture in a - <filename>pkg-message</filename>:</para> - - <programlisting>SUB_FILES= pkg-message -SUB_LIST= ARCH=${ARCH}</programlisting> - - <para>Note that for this example, - <filename>pkg-message.in</filename> must exist in - <varname>FILESDIR</varname>.</para> - - <para>Example of a good - <filename>pkg-message.in</filename>:</para> - - <programlisting>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.</programlisting> - </sect1> -</chapter> |