os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Whitespace-only fixes, translators please ignore.

Browse source
This commit is contained in:
Warren Block 2014-02-09 03:37:57 +00:00
parent 1715f0f666
commit a0f57683ad
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=43848
1 changed files with 163 additions and 168 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -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>
<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>
<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>
<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>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>
<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) &gt;/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>
<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>
<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>&dollar;{SH} pkg-install &dollar;{PKGNAME}
PRE-INSTALL</literal> and the second time as
<literal>&dollar;{SH} pkg-install &dollar;{PKGNAME}
POST-INSTALL</literal>. <literal>&dollar;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>
<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
<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=&dollar;{PREFIX} &dollar;{SH}
&dollar;{PKGINSTALL} &dollar;{PKGNAME}
PRE-INSTALL</literal>.</para>
</note>
</sect1>
<literal>&dollar;{SH} pkg-install &dollar;{PKGNAME}
PRE-INSTALL</literal> and the second time as
<literal>&dollar;{SH} pkg-install &dollar;{PKGNAME}
POST-INSTALL</literal>. <literal>&dollar;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>
<sect1 xml:id="pkg-deinstall">
<title><filename>pkg-deinstall</filename></title>
<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=&dollar;{PREFIX} &dollar;{SH}
&dollar;{PKGINSTALL} &dollar;{PKGNAME}
PRE-INSTALL</literal>.</para>
</note>
</sect1>
<para>This script executes when a package is removed.</para>
<sect1 xml:id="pkg-deinstall">
<title><filename>pkg-deinstall</filename></title>
<para>This script will be run twice by <command>pkg
delete</command> The first time as <literal>&dollar;{SH}
pkg-deinstall &dollar;{PKGNAME} DEINSTALL</literal> and the
second time as <literal>&dollar;{SH} pkg-deinstall
&dollar;{PKGNAME} POST-DEINSTALL</literal>.</para>
</sect1>
<para>This script executes when a package is removed.</para>
<sect1 xml:id="pkg-names">
<title xml:id="porting-pkgfiles">Changing the Names of
<filename>pkg-*</filename>
Files</title>
<para>This script will be run twice by
<command>pkg delete</command> The first time as
<literal>&dollar;{SH} pkg-deinstall &dollar;{PKGNAME}
DEINSTALL</literal> and the second time as
<literal>&dollar;{SH} pkg-deinstall
&dollar;{PKGNAME} POST-DEINSTALL</literal>.</para>
</sect1>
<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>
<sect1 xml:id="pkg-names">
<title xml:id="porting-pkgfiles">Changing the Names of
<filename>pkg-*</filename> Files</title>
<para>Here is a list of variable names and their default values.
(<varname>PKGDIR</varname> defaults to
<varname>${MASTERDIR}</varname>.)</para>
<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>
<informaltable frame="none" pgwide="0">
<tgroup cols="2">
<thead>
<row>
<entry>Variable</entry>
<entry>Default value</entry>
</row>
</thead>
<para>Here is a list of variable names and their default values.
(<varname>PKGDIR</varname> defaults to
<varname>${MASTERDIR}</varname>.)</para>
<tbody>
<row>
<entry><varname>DESCR</varname></entry>
<entry><literal>${PKGDIR}/pkg-descr</literal></entry>
</row>
<informaltable frame="none" pgwide="0">
<tgroup cols="2">
<thead>
<row>
<entry>Variable</entry>
<entry>Default value</entry>
</row>
</thead>
<row>
<entry><varname>PLIST</varname></entry>
<entry><literal>${PKGDIR}/pkg-plist</literal></entry>
</row>
<tbody>
<row>
<entry><varname>DESCR</varname></entry>
<entry><literal>${PKGDIR}/pkg-descr</literal></entry>
</row>
<row>
<entry><varname>PKGINSTALL</varname></entry>
<entry><literal>${PKGDIR}/pkg-install</literal></entry>
</row>
<row>
<entry><varname>PLIST</varname></entry>
<entry><literal>${PKGDIR}/pkg-plist</literal></entry>
</row>
<row>
<entry><varname>PKGDEINSTALL</varname></entry>
<entry><literal>${PKGDIR}/pkg-deinstall</literal></entry>
</row>
<row>
<entry><varname>PKGINSTALL</varname></entry>
<entry><literal>${PKGDIR}/pkg-install</literal></entry>
</row>
<row>
<entry><varname>PKGMESSAGE</varname></entry>
<entry><literal>${PKGDIR}/pkg-message</literal></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<row>
<entry><varname>PKGDEINSTALL</varname></entry>
<entry><literal>${PKGDIR}/pkg-deinstall</literal></entry>
</row>
<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>
<row>
<entry><varname>PKGMESSAGE</varname></entry>
<entry><literal>${PKGDIR}/pkg-message</literal></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<sect1 xml:id="using-sub-files">
<title>Making Use of <varname>SUB_FILES</varname> and
<varname>SUB_LIST</varname></title>
<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>
<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>
<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> 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_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_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 <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 following example will replace
<literal>%%ARCH%%</literal> with the system architecture in a
<filename>pkg-message</filename>:</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>
<programlisting>SUB_FILES= pkg-message
<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
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>