svn commit: r43850 - head/en_US.ISO8859-1/books/porters-handbook/plist
Warren Block
wblock at FreeBSD.org
Sun Feb 9 04:05:25 UTC 2014
Author: wblock
Date: Sun Feb 9 04:05:25 2014
New Revision: 43850
URL: http://svnweb.freebsd.org/changeset/doc/43850
Log:
Whitespace-only fixes, translators please ignore.
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 Sun Feb 9 03:46:05 2014 (r43849)
+++ head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml Sun Feb 9 04:05:25 2014 (r43850)
@@ -5,127 +5,121 @@
$FreeBSD$
-->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="plist">
+<chapter xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+ xml:id="plist">
+
+ <title>Advanced <filename>pkg-plist</filename> Practices</title>
+
+ <sect1 xml:id="plist-sub">
+ <title>Changing <filename>pkg-plist</filename> Based on Make
+ Variables</title>
+
+ <para>Some ports, particularly the <literal>p5-</literal> ports,
+ 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
+ <filename>pkg-plist</filename> of <literal>%%OSREL%%</literal>,
+ <literal>%%PERL_VER%%</literal>, and
+ <literal>%%PERL_VERSION%%</literal> will be substituted for
+ appropriately. The value of <literal>%%OSREL%%</literal> is the
+ numeric revision of the operating system (e.g.,
+ <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>).
+ Several other <literal>%%VARS%%</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
+ <literal>VAR=VALUE</literal> pairs and instances of
+ <literal>%%VAR%%</literal> will be substituted with
+ <replaceable>VALUE</replaceable> in the
+ <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>
- <title>Advanced <filename>pkg-plist</filename> Practices</title>
-
- <sect1 xml:id="plist-sub">
- <title>Changing <filename>pkg-plist</filename> Based on Make
- Variables</title>
-
- <para>Some ports, particularly the <literal>p5-</literal> ports,
- 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
- <filename>pkg-plist</filename> of
- <literal>%%OSREL%%</literal>, <literal>%%PERL_VER%%</literal>,
- and <literal>%%PERL_VERSION%%</literal> will be substituted
- for appropriately. The value of <literal>%%OSREL%%</literal>
- is the numeric revision of the operating system (e.g.,
- <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>).
- Several other
- <literal>%%VARS%%</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
- <literal>VAR=VALUE</literal>
- pairs and instances of
- <literal>%%VAR%%</literal> will be
- substituted with <replaceable>VALUE</replaceable> in the
- <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>
-
- <programlisting>OCTAVE_VERSION= 2.0.13
+ <programlisting>OCTAVE_VERSION= 2.0.13
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
- <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
- <filename>pkg-plist</filename> lines with a
- <literal>%%TAG%%</literal> and adding that
- <literal>TAG</literal> to the <varname>PLIST_SUB</varname>
- variable inside the <filename>Makefile</filename> with a
- special value of <literal>@comment</literal>, which makes
- package tools to ignore the line:</para>
+ <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
+ <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
+ <filename>pkg-plist</filename> lines with a
+ <literal>%%TAG%%</literal> and adding that
+ <literal>TAG</literal> to the <varname>PLIST_SUB</varname>
+ variable inside the <filename>Makefile</filename> with a special
+ value of <literal>@comment</literal>, which makes package tools
+ to ignore the line:</para>
- <programlisting>.if defined(WITH_X11)
+ <programlisting>.if defined(WITH_X11)
PLIST_SUB+= X11=""
.else
PLIST_SUB+= X11="@comment "
.endif</programlisting>
- <para>and in the <filename>pkg-plist</filename>:</para>
+ <para>and in the <filename>pkg-plist</filename>:</para>
- <programlisting>%%X11%%bin/foo-gui</programlisting>
+ <programlisting>%%X11%%bin/foo-gui</programlisting>
- <para>This substitution
- will be
- done between the <buildtarget>pre-install</buildtarget> and
- <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 builds
- <filename>PLIST</filename> on the fly, do
- so in or before <buildtarget>pre-install</buildtarget>. Also,
- if your port needs to edit the resulting file, do so in
- <buildtarget>post-install</buildtarget> to a file named
- <filename>TMPPLIST</filename>.</para>
-
- <para>Another way of modifying a port's packing list is based
- on setting the variables <varname>PLIST_FILES</varname>,
- <varname>PLIST_DIRS</varname>, and
- <varname>PLIST_DIRSTRY</varname>. The value of each variable
- is regarded as a list of pathnames to write to
- <filename>TMPPLIST</filename> along with
- <filename>PLIST</filename> contents. Names
- listed in <varname>PLIST_FILES</varname>,
- <varname>PLIST_DIRS</varname>, and
- <varname>PLIST_DIRSTRY</varname> are subject to
- <literal>%%VAR%%</literal>
- substitution as described above. Except for that, names from
- <varname>PLIST_FILES</varname> will appear in the final
- packing list unchanged, while <literal>@dirrm</literal> and
- <literal>@dirrmtry</literal> will
- be prepended to names from <varname>PLIST_DIRS</varname>
- and <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 <buildtarget>pre-install</buildtarget> or
- earlier.</para>
- </sect1>
-
- <sect1 xml:id="plist-cleaning">
- <title>Empty Directories</title>
-
- <sect2 xml:id="plist-dir-cleaning">
- <title>Cleaning Up Empty Directories</title>
-
- <para>Do make your ports remove empty directories when they
- are de-installed. 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
- directories.</para>
+ <para>This substitution will be done between the
+ <buildtarget>pre-install</buildtarget> and
+ <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
+ builds <filename>PLIST</filename> on the fly, do so in or before
+ <buildtarget>pre-install</buildtarget>. Also, if your port
+ needs to edit the resulting file, do so in
+ <buildtarget>post-install</buildtarget> to a file named
+ <filename>TMPPLIST</filename>.</para>
+
+ <para>Another way of modifying a port's packing list is based on
+ setting the variables <varname>PLIST_FILES</varname>,
+ <varname>PLIST_DIRS</varname>, and
+ <varname>PLIST_DIRSTRY</varname>. The value of each variable is
+ regarded as a list of pathnames to write to
+ <filename>TMPPLIST</filename> along with
+ <filename>PLIST</filename> contents. Names listed in
+ <varname>PLIST_FILES</varname>, <varname>PLIST_DIRS</varname>,
+ and <varname>PLIST_DIRSTRY</varname> are subject to
+ <literal>%%VAR%%</literal> substitution as described above.
+ Except for that, names from <varname>PLIST_FILES</varname> will
+ appear in the final packing list unchanged, while
+ <literal>@dirrm</literal> and <literal>@dirrmtry</literal> will
+ be prepended to names from <varname>PLIST_DIRS</varname> and
+ <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
+ <buildtarget>pre-install</buildtarget> or earlier.</para>
+ </sect1>
+
+ <sect1 xml:id="plist-cleaning">
+ <title>Empty Directories</title>
+
+ <sect2 xml:id="plist-dir-cleaning">
+ <title>Cleaning Up Empty Directories</title>
+
+ <para>Do make your ports remove empty directories when they are
+ de-installed. 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
+ directories.</para>
- <programlisting> :
+ <programlisting> :
lib/X11/oneko/pixmaps/cat.xpm
lib/X11/oneko/sounds/cat.au
:
@@ -133,156 +127,151 @@ lib/X11/oneko/sounds/cat.au
@dirrm lib/X11/oneko/sounds
@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 directories without warning.</para>
-
- <programlisting>@dirrmtry share/doc/gimp</programlisting>
-
- <para>This will neither print any error messages nor cause
- <command>pkg delete</command> (see &man.pkg-delete.8;) to
- exit abnormally even if
- <filename>${PREFIX}/share/doc/gimp</filename> is not empty
- due to other ports installing some files in there.</para>
- </sect2>
-
- <sect2 xml:id="plist-dir-empty">
- <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>
+ <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
+ directories without warning.</para>
+
+ <programlisting>@dirrmtry share/doc/gimp</programlisting>
+
+ <para>This will neither print any error messages nor cause
+ <command>pkg delete</command> (see &man.pkg-delete.8;) to
+ exit abnormally even if
+ <filename>${PREFIX}/share/doc/gimp</filename> is not empty
+ due to other ports installing some files in there.</para>
+ </sect2>
+
+ <sect2 xml:id="plist-dir-empty">
+ <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>
<programlisting>@exec mkdir -p %D/share/foo/templates</programlisting>
- </sect2>
- </sect1>
+ </sect2>
+ </sect1>
- <sect1 xml:id="plist-config">
- <title>Configuration Files</title>
+ <sect1 xml:id="plist-config">
+ <title>Configuration Files</title>
- <para>If your port installs configuration files to
- <filename>PREFIX/etc</filename> (or
- elsewhere) do <emphasis>not</emphasis> simply list them in the
- <filename>pkg-plist</filename>. That will cause <command>pkg
- delete</command> to remove the files carefully edited by the
- user, and a re-installation will wipe them out.</para>
-
- <para>Instead, install sample file(s) with a
- <filename>filename.sample</filename>
- suffix. Then copy the sample file to the real configuration
- file name, if it does not already exist. On deinstall
- delete the configuration file, but only if it is identical
- to the <filename>.sample</filename> file.
- You need to handle this both in the port
- <filename>Makefile</filename>, and in the
- <filename>pkg-plist</filename> (for installation from the
- package).</para>
+ <para>If your port installs configuration files to
+ <filename>PREFIX/etc</filename> (or elsewhere) do
+ <emphasis>not</emphasis> simply list them in the
+ <filename>pkg-plist</filename>. That will cause
+ <command>pkg delete</command> to remove the files carefully
+ edited by the user, and a re-installation will wipe them
+ out.</para>
+
+ <para>Instead, install sample file(s) with a
+ <filename>filename.sample</filename> suffix. Then copy the
+ sample file to the real configuration file name, if it does not
+ already exist. On deinstall delete the configuration file, but
+ only if it is identical to the <filename>.sample</filename>
+ file. You need to handle this both in the port
+ <filename>Makefile</filename>, and in the
+ <filename>pkg-plist</filename> (for installation from the
+ package).</para>
- <para>Example of the <filename>Makefile</filename> part:</para>
+ <para>Example of the <filename>Makefile</filename> part:</para>
- <programlisting>post-install:
+ <programlisting>post-install:
@if [ ! -f ${PREFIX}/etc/orbit.conf ]; then \
${CP} -p ${PREFIX}/etc/orbit.conf.sample ${STAGEDIR}${PREFIX}/etc/orbit.conf ; \
fi</programlisting>
- <para>For each configuration file, create the following three
- lines in <filename>pkg-plist</filename>:</para>
+ <para>For each configuration file, create the following three
+ lines in <filename>pkg-plist</filename>:</para>
- <programlisting>@unexec if cmp -s %D/etc/orbit.conf.sample %D/etc/orbit.conf; then rm -f %D/etc/orbit.conf; fi
+ <programlisting>@unexec if cmp -s %D/etc/orbit.conf.sample %D/etc/orbit.conf; then rm -f %D/etc/orbit.conf; fi
etc/orbit.conf.sample
@exec if [ ! -f %D/etc/orbit.conf ] ; then cp -p %D/%F %B/orbit.conf; fi</programlisting>
- <para>The order of these lines is important. On deinstallation,
- the sample file is compared to the actual configuration file.
- If these files are identical, no changes have been made by the
- user and the actual file can be safely deleted. Because the
- sample file must still exist for the comparison, the
- <literal>@unexec</literal> line comes before the sample
- configuration file name. On installation, if an actual
- configuration file is not already present, the sample file is
- copied to the actual file. The sample file must be present
- before it can be copied, so the <literal>@exec</literal> line
- comes after the sample configuration file name.</para>
-
- <para>To debug any issues, temporarily remove the
- <literal>-s</literal> flag to &man.cmp.1; for more
- output.</para>
-
- <para>See &man.pkg-create.8; for more information on
- <literal>%D</literal> and related substitution markers.</para>
-
- <para>If there is a very good reason not to install a working
- configuration file by default, leave the
- <literal>@exec</literal> line out of
- <filename>pkg-plist</filename> and add a
- <link linkend="porting-message">message</link> pointing out
- that the user must copy and edit the file before the software
- will work.</para>
- </sect1>
-
- <sect1 xml:id="plist-dynamic">
- <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
- 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, this is still considered a static
- list, since it is possible to examine it without having to
- download or compile the distfile.</para>
-
- <para>A <emphasis>dynamic package list</emphasis> is a package
- list which is generated at the time the port is compiled based
- upon the files and directories which are installed. It is not
- possible to examine it before the source code of the ported
- application is downloaded and compiled, or after running a
- <literal>make clean</literal>.</para>
-
- <para>While the use of dynamic package lists is not forbidden,
- maintainers should use static package lists wherever possible,
- as it enables users to &man.grep.1; through available ports to
- discover, for example, which port installs a certain file.
- Dynamic lists should be primarily used for complex ports where
- 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>
- </sect1>
-
- <sect1 xml:id="plist-autoplist">
- <title>Automated Package List Creation</title>
-
- <para>First, make sure your port is almost complete, with only
- <filename>pkg-plist</filename> missing. You may then run
- <command>make makeplist</command> to
- generate a <filename>pkg-plist</filename> automatically. This
- file must be double checked for correctness.</para>
-
- <para>User configuration files should be
- removed, or installed as
- <filename>filename.sample</filename>.
- The <filename>info/dir</filename> file should not be listed
- and appropriate <filename>install-info</filename> lines should
- 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 linkend="porting-shlibs">shared libraries</link>
- section.</para>
- </sect1>
- </chapter>
-
+ <para>The order of these lines is important. On deinstallation,
+ the sample file is compared to the actual configuration file.
+ If these files are identical, no changes have been made by the
+ user and the actual file can be safely deleted. Because the
+ sample file must still exist for the comparison, the
+ <literal>@unexec</literal> line comes before the sample
+ configuration file name. On installation, if an actual
+ configuration file is not already present, the sample file is
+ copied to the actual file. The sample file must be present
+ before it can be copied, so the <literal>@exec</literal> line
+ comes after the sample configuration file name.</para>
+
+ <para>To debug any issues, temporarily remove the
+ <literal>-s</literal> flag to &man.cmp.1; for more
+ output.</para>
+
+ <para>See &man.pkg-create.8; for more information on
+ <literal>%D</literal> and related substitution markers.</para>
+
+ <para>If there is a very good reason not to install a working
+ configuration file by default, leave the
+ <literal>@exec</literal> line out of
+ <filename>pkg-plist</filename> and add a
+ <link linkend="porting-message">message</link> pointing out that
+ the user must copy and edit the file before the software will
+ work.</para>
+ </sect1>
+
+ <sect1 xml:id="plist-dynamic">
+ <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
+ 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, this is still considered a static
+ list, since it is possible to examine it without having to
+ download or compile the distfile.</para>
+
+ <para>A <emphasis>dynamic package list</emphasis> is a package
+ list which is generated at the time the port is compiled based
+ upon the files and directories which are installed. It is not
+ possible to examine it before the source code of the ported
+ application is downloaded and compiled, or after running a
+ <literal>make clean</literal>.</para>
+
+ <para>While the use of dynamic package lists is not forbidden,
+ maintainers should use static package lists wherever possible,
+ as it enables users to &man.grep.1; through available ports to
+ discover, for example, which port installs a certain file.
+ Dynamic lists should be primarily used for complex ports where
+ 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>
+ </sect1>
+
+ <sect1 xml:id="plist-autoplist">
+ <title>Automated Package List Creation</title>
+
+ <para>First, make sure your port is almost complete, with only
+ <filename>pkg-plist</filename> missing. You may then run
+ <command>make makeplist</command> to generate a
+ <filename>pkg-plist</filename> automatically. This file must be
+ double checked for correctness.</para>
+
+ <para>User configuration files should be removed, or installed as
+ <filename>filename.sample</filename>. The
+ <filename>info/dir</filename> file should not be listed and
+ appropriate <filename>install-info</filename> lines should 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 linkend="porting-shlibs">shared libraries</link>
+ section.</para>
+ </sect1>
+</chapter>
More information about the svn-doc-all
mailing list