svn commit: r45619 - head/en_US.ISO8859-1/books/porters-handbook/plist
Mathieu Arnold
mat at FreeBSD.org
Tue Sep 16 12:44:46 UTC 2014
Author: mat (ports committer)
Date: Tue Sep 16 12:44:45 2014
New Revision: 45619
URL: http://svnweb.freebsd.org/changeset/doc/45619
Log:
igor -Ry and some other rewording and fixes.
Differential Revision: https://reviews.freebsd.org/D646
Reviewed by: wblock
Sponsored by: Absolight
Modified:
head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml
Modified: head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml Tue Sep 16 12:41:02 2014 (r45618)
+++ head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml Tue Sep 16 12:44:45 2014 (r45619)
@@ -19,45 +19,47 @@
need to change their <filename>pkg-plist</filename> depending on
what options they are configured with (or version of
<literal>perl</literal>, in the case of <literal>p5-</literal>
- ports). To make this easy, any instances in the
+ ports). To make this easy, any instances in
<filename>pkg-plist</filename> of <literal>%%OSREL%%</literal>,
<literal>%%PERL_VER%%</literal>, and
- <literal>%%PERL_VERSION%%</literal> will be substituted for
+ <literal>%%PERL_VERSION%%</literal> will be substituted
appropriately. The value of <literal>%%OSREL%%</literal> is the
- numeric revision of the operating system (e.g.,
+ numeric revision of the operating system (for example,
<literal>4.9</literal>). <literal>%%PERL_VERSION%%</literal>
and <literal>%%PERL_VER%%</literal> is the full version number
- of <command>perl</command> (e.g., <literal>5.8.9</literal>).
+ of <command>perl</command> (for example, <literal>5.8.9</literal>).
Several other
<literal>%%<replaceable>VARS</replaceable>%%</literal> related
to port's documentation files are described in <link
linkend="install-documentation">the relevant
section</link>.</para>
- <para>If you need to make other substitutions, you can set the
- <varname>PLIST_SUB</varname> variable with a list of
+ <para>To make other substitutions, set
+ <varname>PLIST_SUB</varname> with a list of
<literal><replaceable>VAR</replaceable>=<replaceable>VALUE</replaceable></literal>
pairs and instances of
<literal>%%<replaceable>VAR</replaceable>%%</literal> will be
- substituted with <replaceable>VALUE</replaceable> in the
+ substituted with <replaceable>VALUE</replaceable> in
<filename>pkg-plist</filename>.</para>
- <para>For instance, if you have a port that installs many files
- in a version-specific subdirectory, you can put something
- like</para>
+ <para>For instance, if a port installs many files
+ in a version-specific subdirectory, use a placeholder for the
+ version so that <filename>pkg-plist</filename> does not have to
+ be regenerated every time the port is updated. For
+ example:</para>
- <programlisting>OCTAVE_VERSION= 2.0.13
+ <programlisting>OCTAVE_VERSION= ${PORTREVISION}
PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting>
<para>in the <filename>Makefile</filename> and use
<literal>%%OCTAVE_VERSION%%</literal> wherever the version shows
- up in <filename>pkg-plist</filename>. That way, when you
- upgrade the port, you will not have to change dozens (or in some
- cases, hundreds) of lines in the
+ up in <filename>pkg-plist</filename>. When
+ the port is upgraded, it will not be necessary to edit dozens (or in some
+ cases, hundreds) of lines in
<filename>pkg-plist</filename>.</para>
- <para>If your port installs files conditionally on the options
- set in the port, the usual way of handling it is prefixing the
+ <para>If files are installed conditionally on the options
+ set in the port, the usual way of handling it is prefixing
<filename>pkg-plist</filename> lines with a
<literal>%%OPT%%</literal> for lines needed when the option is
enabled, or <literal>%%NO_OPT%%</literal> when the option is
@@ -66,13 +68,13 @@ PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSI
linkend="options_sub"/> for more information.</para>
<para>For instance, if there are files that are only installed
- when the <literal>X11</literal> option is enabled, and the
+ when the <literal>X11</literal> option is enabled, and
<filename>Makefile</filename> has:</para>
<programlisting>OPTIONS_DEFINE= X11
OPTIONS_SUB= yes</programlisting>
- <para>In the <filename>pkg-plist</filename> file, put
+ <para>In <filename>pkg-plist</filename>, put
<literal>%%X11%%</literal> in front of the lines only being
installed when the option is enabled, like this :</para>
@@ -83,9 +85,9 @@ OPTIONS_SUB= yes</programlisting>
<buildtarget>do-install</buildtarget> targets, by reading from
<filename>PLIST</filename> and writing to
<filename>TMPPLIST</filename> (default:
- <filename>WRKDIR/.PLIST.mktmp</filename>). So if your port
+ <filename>WRKDIR/.PLIST.mktmp</filename>). So if the port
builds <filename>PLIST</filename> on the fly, do so in or before
- <buildtarget>pre-install</buildtarget>. Also, if your port
+ <buildtarget>pre-install</buildtarget>. Also, if the port
needs to edit the resulting file, do so in
<buildtarget>post-install</buildtarget> to a file named
<filename>TMPPLIST</filename>.</para>
@@ -108,13 +110,13 @@ OPTIONS_SUB= yes</programlisting>
<varname>PLIST_DIRSTRY</varname>, respectively. To take effect,
<varname>PLIST_FILES</varname>, <varname>PLIST_DIRS</varname>,
and <varname>PLIST_DIRSTRY</varname> must be set before
- <filename>TMPPLIST</filename> is written, i.e., in
+ <filename>TMPPLIST</filename> is written, that is, in
<buildtarget>pre-install</buildtarget> or earlier.</para>
- <para>From time to time, the <varname>OPTIONS_SUB</varname>
- construct is not enough, in those cases, adding a specific
- <literal>TAG</literal> to the <varname>PLIST_SUB</varname>
- variable inside the <filename>Makefile</filename> with a special
+ <para>From time to time, using <varname>OPTIONS_SUB</varname>
+ is not enough. In those cases, adding a specific
+ <literal><replaceable>TAG</replaceable></literal> to <varname>PLIST_SUB</varname>
+ inside the <filename>Makefile</filename> with a special
value of <literal>@comment</literal>, makes package tools to
ignore the line. For instance, if some files are only installed
when the <literal>X11</literal> option is on and the
@@ -139,8 +141,8 @@ PLIST_SUB+= X11I386="@comment "
<para>When being de-installed, A port has to remove empty
directories it created. This is usually accomplished by
adding <literal>@dirrm</literal> lines for all directories
- that are specifically created by the port. You need to delete
- subdirectories before you can delete parent
+ that are specifically created by the port. Subdirectories
+ must be deleted before deleting parent
directories.</para>
<programlisting> :
@@ -152,8 +154,8 @@ lib/X11/oneko/sounds/cat.au
@dirrm lib/X11/oneko</programlisting>
<para>However, sometimes <literal>@dirrm</literal> will give
- you errors because other ports share the same directory. You
- can use <literal>@dirrmtry</literal> to remove only empty
+ errors because other ports share the same directory.
+ Use <literal>@dirrmtry</literal> to remove only empty
directories without warning.</para>
<programlisting>@dirrmtry share/doc/gimp</programlisting>
@@ -169,33 +171,38 @@ lib/X11/oneko/sounds/cat.au
<title>Creating Empty Directories</title>
<para>Empty directories created during port installation need
- special attention. They will not get created when installing
- the package, because packages only store the files, and both
- <command>pkg add</command> and <command>pkg install</command>
- creates directories for them as needed. To make sure the
- empty directory is created when installing the package, add
- this line to <filename>pkg-plist</filename> above the
- corresponding <literal>@dirrm</literal> line:</para>
+ special attention. They must be present when the package
+ is created. If they are not created by the port code, create
+ them in the <filename>Makefile</filename>:</para>
+
+ <programlisting>post-stage:
+ @${MKDIR} ${STAGEDIR}${PREFIX}/some/directory</programlisting>
+
+ <para>Add the directory to <filename>pkg-plist</filename>
+ like any other. For example, if the directory has files
+ created when the port is used:</para>
- <programlisting>@exec mkdir -p %D/share/foo/templates</programlisting>
+ <programlisting>@dirrmtry some/directory</programlisting>
</sect2>
</sect1>
<sect1 xml:id="plist-config">
<title>Configuration Files</title>
- <para>If your port installs configuration files to
+ <para>If the port installs configuration files to
<filename>PREFIX/etc</filename> (or elsewhere) do
- <emphasis>not</emphasis> simply list them in the
+ <emphasis>not</emphasis> list them in
<filename>pkg-plist</filename>. That will cause
- <command>pkg delete</command> to remove the files carefully
+ <command>pkg delete</command> to remove files that have been carefully
edited by the user, and a re-installation will wipe them
out.</para>
- <para>Instead, install sample file(s) as
- <filename><replaceable>filename</replaceable>.sample</filename>,
- and for each sample file, add this line to your
- <filename>pkg-plist</filename>.</para>
+ <para>Instead, install sample files with a
+ <filename><replaceable>filename</replaceable>.sample</filename>
+ extension. The <literal>@sample</literal> macro automates this,
+ see <xref linkend="plist-keywords-sample"/> for what it does
+ exactly. For each sample file, add a line to
+ <filename>pkg-plist</filename>:</para>
<programlisting>@sample etc/orbit.conf.sample</programlisting>
@@ -209,19 +216,19 @@ lib/X11/oneko/sounds/cat.au
<tip>
<para>When a port installs its configuration in a subdirectory
- of <filename>${PREFIX}/etc</filename>, it should be in
+ of <filename>${PREFIX}/etc</filename>, use
<varname>ETCDIR</varname>, which defaults to
<literal>${PREFIX}/etc/${PORTNAME}</literal>, it can be
overridden in the ports <filename>Makefile</filename> if there
is a convention for the port to use some other directory. The
- <literal>%%ETCDIR%%</literal> macro should be used in its
- stead in the <filename>pkg-plist</filename> file.</para>
+ <literal>%%ETCDIR%%</literal> macro will be used in its
+ stead in <filename>pkg-plist</filename>.</para>
</tip>
<note>
<para>The sample configuration files should always have the
<filename>.sample</filename> suffix. If for some historical
- reason you cannot use the standard suffix, you can still use
+ reason using the standard suffix is not possible, use
this construct:</para>
<programlisting>@unexec if cmp -s %D/etc/orbit.conf-dist %D/etc/orbit.conf; then rm -f %D/etc/orbit.conf; fi
@@ -253,15 +260,15 @@ etc/orbit.conf-dist
<title>Dynamic Versus Static Package List</title>
<para>A <emphasis>static package list</emphasis> is a package
- list which is available in the Ports Collection either as a
- <filename>pkg-plist</filename> file (with or without variable
+ list which is available in the Ports Collection either as
+ <filename>pkg-plist</filename> (with or without variable
substitution), or embedded into the
<filename>Makefile</filename> via
<varname>PLIST_FILES</varname>, <varname>PLIST_DIRS</varname>,
and <varname>PLIST_DIRSTRY</varname>. Even if the contents are
auto-generated by a tool or a target in the Makefile
<emphasis>before</emphasis> the inclusion into the Ports
- Collection by a committer (e.g., using <command>make
+ Collection by a committer (for example, using <command>make
makeplist></command>), this is still considered a static list,
since it is possible to examine it without having to download or
compile the distfile.</para>
@@ -281,8 +288,8 @@ etc/orbit.conf-dist
the package list changes drastically based upon optional
features of the port (and thus maintaining a static package list
is infeasible), or ports which change the package list based
- upon the version of dependent software used (e.g., ports which
- generate docs with <application>Javadoc</application>).</para>
+ upon the version of dependent software used. For example, ports which
+ generate docs with <application>Javadoc</application>.</para>
</sect1>
<sect1 xml:id="plist-autoplist">
@@ -290,7 +297,7 @@ etc/orbit.conf-dist
<para>First, make sure the port is almost complete, with only
<filename>pkg-plist</filename> missing. Running <command>make
- makeplist</command> will show what should be put in
+ makeplist</command> will show an example for
<filename>pkg-plist</filename>. The output of
<buildtarget>makeplist</buildtarget> must be double checked for
correctness as it tries to automatically guess a few things, and
@@ -298,12 +305,12 @@ etc/orbit.conf-dist
<para>User configuration files should be installed as
<filename><replaceable>filename</replaceable>.sample</filename>,
- as it is described in <xref linkend="plist-config"/>. The
- <filename>info/dir</filename> file should not be listed and
- appropriate <filename>install-info</filename> lines should be
+ as it is described in <xref linkend="plist-config"/>.
+ <filename>info/dir</filename> must not be listed and
+ appropriate <filename>install-info</filename> lines must be
added as noted in the <link linkend="makefile-info">info
files</link> section. Any libraries installed by the port
- should be listed as specified in the <link
+ must be listed as specified in the <link
linkend="porting-shlibs">shared libraries</link>
section.</para>
</sect1>
@@ -412,9 +419,9 @@ etc/orbit.conf-dist
<replaceable>command</replaceable></title>
<para>Execute <replaceable>command</replaceable> as part of
- the unpacking process. If command contains any of the
- following sequences somewhere in it, they are expanded
- inline. For the following examples, assume that
+ the unpacking process. If command contains any of these
+ sequences somewhere in it, they are expanded
+ inline. For these examples, assume that
<literal>@cwd</literal> is set to <filename
class="directory">/usr/local</filename> and the last
extracted file was <filename>bin/emacs</filename>.</para>
@@ -527,7 +534,7 @@ etc/orbit.conf-dist
By default, directories created by a package installation
are not deleted when the package is deinstalled. This
provides an explicit directory cleanup method. These
- directives should appear at the end of the package list. If
+ directives must appear at the end of the package list. If
the directory is not empty a warning is printed, and the
directory is not removed.</para>
</sect3>
@@ -542,8 +549,8 @@ etc/orbit.conf-dist
</sect3>
</sect2>
- <sect2 xml:id="plist-keywords-your-own">
- <title>Creating Your Own Keyword</title>
+ <sect2 xml:id="plist-keywords-creating-new">
+ <title>Creating New Keywords</title>
<para>Package list files can be extended by keywords that are
defined in the <filename
@@ -551,7 +558,7 @@ etc/orbit.conf-dist
The settings for each keyword lives in a
<acronym>YAML</acronym> file named
<filename><replaceable>keyword</replaceable>.yaml</filename>.
- The file must contain at least one of the following
+ The file must contain at least one of the next
sections:</para>
<variablelist>
@@ -713,13 +720,19 @@ post-deinstall: |
<programlisting>actions: [file]
post-install: |
- sample_file="%D/%@"
+ case "%@" in
+ /*) sample_file="%@" ;;
+ *) sample_file="%D/%@" ;;
+ esac
target_file="${sample_file%.sample}"
if ! [ -f "${target_file}" ]; then
/bin/cp -p "${sample_file}" "${target_file}"
fi
pre-deinstall: |
- sample_file="%D/%@"
+ case "%@" in
+ /*) sample_file="%@" ;;
+ *) sample_file="%D/%@" ;;
+ esac
target_file="${sample_file%.sample}"
if cmp -s "${target_file}" "${sample_file}"; then
rm -f "${target_file}"
More information about the svn-doc-all
mailing list