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$ $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> <title>The <filename>pkg-*</filename> Files</title>
Files</title>
<para>There are some tricks we have not mentioned yet about the <para>There are some tricks we have not mentioned yet about the
<filename>pkg-*</filename> files <filename>pkg-*</filename> files that come in handy
that come in handy sometimes.</para> sometimes.</para>
<sect1 xml:id="porting-message"> <sect1 xml:id="porting-message">
<title><filename>pkg-message</filename></title> <title><filename>pkg-message</filename></title>
<para>If you need to display a message to the installer, you may <para>If you need to display a message to the installer, you may
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>When some lines about the build-time knobs or warnings
have to be displayed, use <varname>ECHO_MSG</varname>. The have to be displayed, use <varname>ECHO_MSG</varname>. The
<filename>pkg-message</filename> file is only for <filename>pkg-message</filename> file is only for
post-installation steps. Likewise, the distinction between post-installation steps. Likewise, the distinction between
<varname>ECHO_MSG</varname> and <varname>ECHO_CMD</varname> <varname>ECHO_MSG</varname> and <varname>ECHO_CMD</varname>
should be kept in mind. The former is for printing should be kept in mind. The former is for printing
informational text to the screen, while the latter is for informational text to the screen, while the latter is for
command pipelining:</para> command pipelining:</para>
<programlisting>update-etc-shells: <programlisting>update-etc-shells:
@${ECHO_MSG} "updating /etc/shells" @${ECHO_MSG} "updating /etc/shells"
@${CP} /etc/shells /etc/shells.bak @${CP} /etc/shells /etc/shells.bak
@( ${GREP} -v ${PREFIX}/bin/bash /etc/shells.bak; \ @( ${GREP} -v ${PREFIX}/bin/bash /etc/shells.bak; \
${ECHO_CMD} ${PREFIX}/bin/bash) &gt;/etc/shells ${ECHO_CMD} ${PREFIX}/bin/bash) &gt;/etc/shells
@${RM} /etc/shells.bak</programlisting> @${RM} /etc/shells.bak</programlisting>
<note> <note>
<para>The <filename>pkg-message</filename> file does not need <para>The <filename>pkg-message</filename> file does not need
to be added to <filename>pkg-plist</filename>.</para> to be added to <filename>pkg-plist</filename>.</para>
</note> </note>
</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 your port needs to execute commands when the binary <para>If your 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> you can do this via the <command>pkg install</command> you can do this via the
<filename>pkg-install</filename> script. This script will <filename>pkg-install</filename> script. This script will
automatically be added to the package, and will be run twice automatically be added to the package, and will be run twice by
by <command>pkg</command> the first time as <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>
<note> <literal>&dollar;{SH} pkg-install &dollar;{PKGNAME}
<para>This script is not run automatically if you install the PRE-INSTALL</literal> and the second time as
port with <command>make install</command>. If you are <literal>&dollar;{SH} pkg-install &dollar;{PKGNAME}
depending on it being run, you will have to explicitly call POST-INSTALL</literal>. <literal>&dollar;2</literal> can be
it from your port's <filename>Makefile</filename>, with a tested to determine which mode the script is being run in.
line like <literal>PKG_PREFIX=&dollar;{PREFIX} &dollar;{SH} The <envar>PKG_PREFIX</envar> environmental variable will be
&dollar;{PKGINSTALL} &dollar;{PKGNAME} set to the package installation directory.</para>
PRE-INSTALL</literal>.</para>
</note>
</sect1>
<sect1 xml:id="pkg-deinstall"> <note>
<title><filename>pkg-deinstall</filename></title> <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 <para>This script executes when a package is removed.</para>
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>
<sect1 xml:id="pkg-names"> <para>This script will be run twice by
<title xml:id="porting-pkgfiles">Changing the Names of <command>pkg delete</command> The first time as
<filename>pkg-*</filename> <literal>&dollar;{SH} pkg-deinstall &dollar;{PKGNAME}
Files</title> DEINSTALL</literal> and the second time as
<literal>&dollar;{SH} pkg-deinstall
&dollar;{PKGNAME} POST-DEINSTALL</literal>.</para>
</sect1>
<para>All the names of <sect1 xml:id="pkg-names">
<filename>pkg-*</filename> files <title xml:id="porting-pkgfiles">Changing the Names of
are defined using variables so you can change them in your <filename>pkg-*</filename> Files</title>
<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. <para>All the names of <filename>pkg-*</filename> files are
(<varname>PKGDIR</varname> defaults to defined using variables so you can change them in your
<varname>${MASTERDIR}</varname>.)</para> <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"> <para>Here is a list of variable names and their default values.
<tgroup cols="2"> (<varname>PKGDIR</varname> defaults to
<thead> <varname>${MASTERDIR}</varname>.)</para>
<row>
<entry>Variable</entry>
<entry>Default value</entry>
</row>
</thead>
<tbody> <informaltable frame="none" pgwide="0">
<row> <tgroup cols="2">
<entry><varname>DESCR</varname></entry> <thead>
<entry><literal>${PKGDIR}/pkg-descr</literal></entry> <row>
</row> <entry>Variable</entry>
<entry>Default value</entry>
</row>
</thead>
<row> <tbody>
<entry><varname>PLIST</varname></entry> <row>
<entry><literal>${PKGDIR}/pkg-plist</literal></entry> <entry><varname>DESCR</varname></entry>
</row> <entry><literal>${PKGDIR}/pkg-descr</literal></entry>
</row>
<row> <row>
<entry><varname>PKGINSTALL</varname></entry> <entry><varname>PLIST</varname></entry>
<entry><literal>${PKGDIR}/pkg-install</literal></entry> <entry><literal>${PKGDIR}/pkg-plist</literal></entry>
</row> </row>
<row> <row>
<entry><varname>PKGDEINSTALL</varname></entry> <entry><varname>PKGINSTALL</varname></entry>
<entry><literal>${PKGDIR}/pkg-deinstall</literal></entry> <entry><literal>${PKGDIR}/pkg-install</literal></entry>
</row> </row>
<row> <row>
<entry><varname>PKGMESSAGE</varname></entry> <entry><varname>PKGDEINSTALL</varname></entry>
<entry><literal>${PKGDIR}/pkg-message</literal></entry> <entry><literal>${PKGDIR}/pkg-deinstall</literal></entry>
</row> </row>
</tbody>
</tgroup>
</informaltable>
<para>Please change these variables rather than overriding <row>
<varname>PKG_ARGS</varname>. If you change <entry><varname>PKGMESSAGE</varname></entry>
<varname>PKG_ARGS</varname>, those files will not correctly be <entry><literal>${PKGDIR}/pkg-message</literal></entry>
installed in <filename>/var/db/pkg</filename> upon install </row>
from a port.</para> </tbody>
</sect1> </tgroup>
</informaltable>
<sect1 xml:id="using-sub-files"> <para>Please change these variables rather than overriding
<title>Making Use of <varname>SUB_FILES</varname> and <varname>PKG_ARGS</varname>. If you change
<varname>SUB_LIST</varname></title> <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 <sect1 xml:id="using-sub-files">
<varname>SUB_LIST</varname> variables are useful for dynamic <title>Making Use of <varname>SUB_FILES</varname> and
values in port files, such as the installation <varname>SUB_LIST</varname></title>
<varname>PREFIX</varname> in
<filename>pkg-message</filename>.</para>
<para>The <varname>SUB_FILES</varname> variable specifies a list <para>The <varname>SUB_FILES</varname> and
of files to be automatically modified. Each <varname>SUB_LIST</varname> variables are useful for dynamic
<replaceable>file</replaceable> in the values in port files, such as the installation
<varname>SUB_FILES</varname> list must have a corresponding <varname>PREFIX</varname> in
<filename>file.in</filename> <filename>pkg-message</filename>.</para>
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 <para>The <varname>SUB_FILES</varname> variable specifies a list
<literal>VAR=VALUE</literal> pairs. For each pair of files to be automatically modified. Each
<literal>%%VAR%%</literal> will get replaced with <replaceable>file</replaceable> in the
<literal>VALUE</literal> in each file listed in <varname>SUB_FILES</varname> list must have a corresponding
<varname>SUB_FILES</varname>. Several common pairs are <filename>file.in</filename> present in
automatically defined: <varname>PREFIX</varname>, <varname>FILESDIR</varname>. A modified version will be created
<varname>LOCALBASE</varname>, <varname>DATADIR</varname>, in <varname>WRKDIR</varname>. Files defined as a value of
<varname>DOCSDIR</varname>, <varname>EXAMPLESDIR</varname>, <varname>USE_RC_SUBR</varname> (or the deprecated
<varname>WWWDIR</varname>, and <varname>ETCDIR</varname>. <varname>USE_RCORDER</varname>) are automatically added to the
Any line beginning with <literal>@comment</literal> will be <varname>SUB_FILES</varname>. For the files
deleted from resulting files after a variable <filename>pkg-message</filename>,
substitution.</para> <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 <para>The <varname>SUB_LIST</varname> variable is a list of
<literal>%%ARCH%%</literal> with the system architecture in a <literal>VAR=VALUE</literal> pairs. For each pair
<filename>pkg-message</filename>:</para> <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> SUB_LIST= ARCH=${ARCH}</programlisting>
<para>Note that for this example, the <para>Note that for this example, the
<filename>pkg-message.in</filename> file must exist in <filename>pkg-message.in</filename> file must exist in
<varname>FILESDIR</varname>.</para> <varname>FILESDIR</varname>.</para>
<para>Example of a good <para>Example of a good
<filename>pkg-message.in</filename>:</para> <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 Copy %%PREFIX%%/share/examples/putsy/%%ARCH%%.conf into your home directory
as .putsy.conf and edit it.</programlisting> as .putsy.conf and edit it.</programlisting>
</sect1> </sect1>
</chapter> </chapter>