Date: Sun, 9 Feb 2014 03:37:58 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r43848 - head/en_US.ISO8859-1/books/porters-handbook/pkg-files Message-ID: <201402090337.s193bwsO068484@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: wblock Date: Sun Feb 9 03:37:57 2014 New Revision: 43848 URL: http://svnweb.freebsd.org/changeset/doc/43848 Log: Whitespace-only fixes, translators please ignore. 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 Sun Feb 9 03:26:08 2014 (r43847) +++ head/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml Sun Feb 9 03:37:57 2014 (r43848) @@ -5,211 +5,206 @@ $FreeBSD$ --> -<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="pkg-files"> +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" + xml:id="pkg-files"> + + <title>The <filename>pkg-*</filename> Files</title> + + <para>There are some tricks we have not mentioned yet about the + <filename>pkg-*</filename> files that come in handy + sometimes.</para> + + <sect1 xml:id="porting-message"> + <title><filename>pkg-message</filename></title> + + <para>If you need to display a message to the installer, you may + 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 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>. The + <filename>pkg-message</filename> file is only for + post-installation steps. Likewise, the distinction between + <varname>ECHO_MSG</varname> and <varname>ECHO_CMD</varname> + should be kept in mind. The former is for printing + informational text to the screen, while the latter is for + command pipelining:</para> - <title>The <filename>pkg-*</filename> - Files</title> - - <para>There are some tricks we have not mentioned yet about the - <filename>pkg-*</filename> files - that come in handy sometimes.</para> - - <sect1 xml:id="porting-message"> - <title><filename>pkg-message</filename></title> - - <para>If you need to display a message to the installer, you may - 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 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>. The - <filename>pkg-message</filename> file is only for - post-installation steps. Likewise, the distinction between - <varname>ECHO_MSG</varname> and <varname>ECHO_CMD</varname> - should be kept in mind. The former is for printing - informational text to the screen, while the latter is for - command pipelining:</para> - - <programlisting>update-etc-shells: + <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> - <note> - <para>The <filename>pkg-message</filename> file does not need - to be added to <filename>pkg-plist</filename>.</para> - </note> - </sect1> - - <sect1 xml:id="pkg-install"> - <title><filename>pkg-install</filename></title> - - <para>If your port needs to execute commands when the binary - package is installed with <command>pkg add</command> or - <command>pkg install</command> you can do this via the - <filename>pkg-install</filename> script. This script will - automatically be added to the package, and will be run twice - by <command>pkg</command> the first time as - <literal>${SH} pkg-install ${PKGNAME} - PRE-INSTALL</literal> and the second time as - <literal>${SH} pkg-install ${PKGNAME} - POST-INSTALL</literal>. <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> - - <note> - <para>This script is not run automatically if you install the - port with <command>make install</command>. If you are - depending on it being run, you will have to explicitly call - it from your port's <filename>Makefile</filename>, with a - line like <literal>PKG_PREFIX=${PREFIX} ${SH} - ${PKGINSTALL} ${PKGNAME} - PRE-INSTALL</literal>.</para> - </note> - </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> and the - second time as <literal>${SH} pkg-deinstall - ${PKGNAME} POST-DEINSTALL</literal>.</para> - </sect1> - - <sect1 xml:id="pkg-names"> - <title xml:id="porting-pkgfiles">Changing the Names of - <filename>pkg-*</filename> - Files</title> - - <para>All the names of - <filename>pkg-*</filename> files - are defined using variables so you can change them in your - <filename>Makefile</filename> if need be. This is especially - useful when you are sharing the same - <filename>pkg-*</filename> files - among several ports or have to write to one of the above 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 - <filename>pkg-*</filename> - subdirectory).</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> - - <para>Please change these variables rather than overriding - <varname>PKG_ARGS</varname>. If you change - <varname>PKG_ARGS</varname>, those files will not correctly be - installed in <filename>/var/db/pkg</filename> upon install - from a port.</para> - </sect1> - - <sect1 xml:id="using-sub-files"> - <title>Making Use of <varname>SUB_FILES</varname> and - <varname>SUB_LIST</varname></title> - - <para>The <varname>SUB_FILES</varname> and - <varname>SUB_LIST</varname> variables are useful for dynamic - values in port files, such as the installation - <varname>PREFIX</varname> in - <filename>pkg-message</filename>.</para> - - <para>The <varname>SUB_FILES</varname> variable specifies a list - of files to be automatically modified. Each - <replaceable>file</replaceable> in the - <varname>SUB_FILES</varname> list must have a corresponding - <filename>file.in</filename> - present in <varname>FILESDIR</varname>. A modified version - will be created in <varname>WRKDIR</varname>. Files defined - as a value of <varname>USE_RC_SUBR</varname> (or the - deprecated <varname>USE_RCORDER</varname>) are automatically - added to the <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>The <varname>SUB_LIST</varname> variable is a list of - <literal>VAR=VALUE</literal> pairs. For each pair - <literal>%%VAR%%</literal> will get 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> will be - deleted from resulting files after a variable - substitution.</para> - - <para>The following example will replace - <literal>%%ARCH%%</literal> with the system architecture in a - <filename>pkg-message</filename>:</para> + <note> + <para>The <filename>pkg-message</filename> file does not need + to be added to <filename>pkg-plist</filename>.</para> + </note> + </sect1> + + <sect1 xml:id="pkg-install"> + <title><filename>pkg-install</filename></title> + + <para>If your port needs to execute commands when the binary + package is installed with <command>pkg add</command> or + <command>pkg install</command> you can do this via the + <filename>pkg-install</filename> script. This script will + automatically be added to the package, and will be run twice by + <command>pkg</command> the first time as + + <literal>${SH} pkg-install ${PKGNAME} + PRE-INSTALL</literal> and the second time as + <literal>${SH} pkg-install ${PKGNAME} + POST-INSTALL</literal>. <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> + + <note> + <para>This script is not run automatically if you install the + port with <command>make install</command>. If you are + depending on it being run, you will have to explicitly call + it from your port's <filename>Makefile</filename>, with a + line like <literal>PKG_PREFIX=${PREFIX} ${SH} + ${PKGINSTALL} ${PKGNAME} + PRE-INSTALL</literal>.</para> + </note> + </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> and the second time as + <literal>${SH} pkg-deinstall + ${PKGNAME} POST-DEINSTALL</literal>.</para> + </sect1> + + <sect1 xml:id="pkg-names"> + <title xml:id="porting-pkgfiles">Changing the Names of + <filename>pkg-*</filename> Files</title> + + <para>All the names of <filename>pkg-*</filename> files are + defined using variables so you can change them in your + <filename>Makefile</filename> if need be. This is especially + useful when you are sharing the same <filename>pkg-*</filename> + files among several ports or have to write to one of the above + 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 <filename>pkg-*</filename> + subdirectory).</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> + + <para>Please change these variables rather than overriding + <varname>PKG_ARGS</varname>. If you change + <varname>PKG_ARGS</varname>, those files will not correctly be + installed in <filename>/var/db/pkg</filename> upon install + from a port.</para> + </sect1> + + <sect1 xml:id="using-sub-files"> + <title>Making Use of <varname>SUB_FILES</varname> and + <varname>SUB_LIST</varname></title> + + <para>The <varname>SUB_FILES</varname> and + <varname>SUB_LIST</varname> variables are useful for dynamic + values in port files, such as the installation + <varname>PREFIX</varname> in + <filename>pkg-message</filename>.</para> + + <para>The <varname>SUB_FILES</varname> variable specifies a list + of files to be automatically modified. Each + <replaceable>file</replaceable> in the + <varname>SUB_FILES</varname> list must have a corresponding + <filename>file.in</filename> present in + <varname>FILESDIR</varname>. A modified version will be created + in <varname>WRKDIR</varname>. Files defined as a value of + <varname>USE_RC_SUBR</varname> (or the deprecated + <varname>USE_RCORDER</varname>) are automatically added to the + <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>The <varname>SUB_LIST</varname> variable is a list of + <literal>VAR=VALUE</literal> pairs. For each pair + <literal>%%VAR%%</literal> will get 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> will be deleted + from resulting files after a variable substitution.</para> + + <para>The following example will replace + <literal>%%ARCH%%</literal> with the system architecture in a + <filename>pkg-message</filename>:</para> - <programlisting>SUB_FILES= pkg-message + <programlisting>SUB_FILES= pkg-message SUB_LIST= ARCH=${ARCH}</programlisting> - <para>Note that for this example, the - <filename>pkg-message.in</filename> file must exist in - <varname>FILESDIR</varname>.</para> + <para>Note that for this example, the + <filename>pkg-message.in</filename> file must exist in + <varname>FILESDIR</varname>.</para> - <para>Example of a good - <filename>pkg-message.in</filename>:</para> + <para>Example of a good + <filename>pkg-message.in</filename>:</para> - <programlisting>Now it is time to configure this package. + <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> - + </sect1> +</chapter>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201402090337.s193bwsO068484>