svn commit: r45707 - in head/en_US.ISO8859-1/books/porters-handbook: makefiles plist quick-porting
Mathieu Arnold
mat at FreeBSD.org
Thu Oct 2 13:47:41 UTC 2014
Author: mat (ports committer)
Date: Thu Oct 2 13:47:39 2014
New Revision: 45707
URL: https://svnweb.freebsd.org/changeset/doc/45707
Log:
Second round of @dirrm* cleanup.
Differential Revision: https://reviews.freebsd.org/D882
Reviewed by: bcr
Sponsored by: Absolight
Modified:
head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml
head/en_US.ISO8859-1/books/porters-handbook/quick-porting/chapter.xml
Modified: head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml Thu Oct 2 00:31:14 2014 (r45706)
+++ head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml Thu Oct 2 13:47:39 2014 (r45707)
@@ -4674,8 +4674,7 @@ PORTVERSION= 1.0</programlisting>
<literal>%%PORTDOCS%%</literal> prefix, for example:</para>
<programlisting>%%PORTDOCS%%%%DOCSDIR%%/AUTHORS
-%%PORTDOCS%%%%DOCSDIR%%/CONTACT
-%%PORTDOCS%%@dirrm %%DOCSDIR%%</programlisting>
+%%PORTDOCS%%%%DOCSDIR%%/CONTACT</programlisting>
<para>As an alternative to enumerating the documentation files
in <filename>pkg-plist</filename>, a port can set the variable
Modified: head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml Thu Oct 2 00:31:14 2014 (r45706)
+++ head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml Thu Oct 2 13:47:39 2014 (r45707)
@@ -93,23 +93,21 @@ OPTIONS_SUB= yes</programlisting>
<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
+ setting the variables <varname>PLIST_FILES</varname> and
+ <varname>PLIST_DIRS</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
+ <varname>PLIST_FILES</varname> and
+ <varname>PLIST_DIRS</varname> are subject to
<literal>%%<replaceable>VAR</replaceable>%%</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
+ list unchanged, while <literal>@dir</literal>
+ will be prepended to names from
+ <varname>PLIST_DIRS</varname>. To take effect,
+ <varname>PLIST_FILES</varname> and
+ <varname>PLIST_DIRS</varname> must be set before
<filename>TMPPLIST</filename> is written, that is, in
<buildtarget>pre-install</buildtarget> or earlier.</para>
@@ -138,33 +136,18 @@ PLIST_SUB+= X11I386="@comment "
<sect2 xml:id="plist-dir-cleaning">
<title>Cleaning Up Empty Directories</title>
- <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. Subdirectories
- must be deleted before deleting parent
- directories.</para>
-
- <programlisting> :
-lib/X11/oneko/pixmaps/cat.xpm
-lib/X11/oneko/sounds/cat.au
- :
- at dirrm lib/X11/oneko/pixmaps
- at dirrm lib/X11/oneko/sounds
- at dirrm lib/X11/oneko</programlisting>
-
- <para>However, sometimes <literal>@dirrm</literal> will give
- 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>
-
- <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>
+ <para>When being de-installed, a port has to remove empty
+ directories it created. Most of these directories are removed
+ automatically by &man.pkg.8;, but for directories created
+ outside of <filename>${PREFIX}</filename>, or empty
+ directories, some more work needs to be done. This is usually
+ accomplished by adding <literal>@dir</literal> lines for those
+ directories. Subdirectories must be deleted before deleting
+ parent directories.</para>
+
+ <programlisting>[...]
+ at dir /var/games/oneko/saved-games
+ at dir /var/games/oneko</programlisting>
</sect2>
<sect2 xml:id="plist-dir-empty">
@@ -179,10 +162,9 @@ lib/X11/oneko/sounds/cat.au
@${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>
+ like any other. For example:</para>
- <programlisting>@dirrmtry some/directory</programlisting>
+ <programlisting>@dir some/directory</programlisting>
</sect2>
</sect1>
@@ -264,8 +246,8 @@ etc/orbit.conf-dist
<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
+ <varname>PLIST_FILES</varname> and
+ <varname>PLIST_DIRS</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 (for example, using <command>make
@@ -337,7 +319,7 @@ etc/orbit.conf-dist
<title><literal>@fc</literal>
<replaceable>directory</replaceable></title>
- <para>Add a <literal>@dirrmtry</literal> entry for the
+ <para>Add a <literal>@dir</literal> entry for the
directory passed as an argument, and run <command>fc-cache
-s</command> on that directory after installation and
deinstallation.</para>
@@ -347,7 +329,7 @@ etc/orbit.conf-dist
<title><literal>@fcfontsdir</literal>
<replaceable>directory</replaceable></title>
- <para>Add a <literal>@dirrmtry</literal> entry for the
+ <para>Add a <literal>@dir</literal> entry for the
directory passed as an argument, and run <command>fc-cache
-s</command>, <command>mkfontscale</command> and
<command>mkfontdir</command> on that directory after
@@ -362,7 +344,7 @@ etc/orbit.conf-dist
<title><literal>@fontsdir</literal>
<replaceable>directory</replaceable></title>
- <para>Add a <literal>@dirrmtry</literal> entry for the
+ <para>Add a <literal>@dir</literal> entry for the
directory passed as an argument, and run
<command>mkfontscale</command> and
<command>mkfontdir</command> on that directory after
Modified: head/en_US.ISO8859-1/books/porters-handbook/quick-porting/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/quick-porting/chapter.xml Thu Oct 2 00:31:14 2014 (r45706)
+++ head/en_US.ISO8859-1/books/porters-handbook/quick-porting/chapter.xml Thu Oct 2 13:47:39 2014 (r45707)
@@ -143,10 +143,7 @@ WWW: http://www.oneko.org/</programlisti
is also called the <quote>packing list</quote> because the
package is generated by packing the files listed here. The
pathnames are relative to the installation prefix (usually
- <filename>/usr/local</filename>. If the port creates
- directories during installation, make sure to add
- <literal>@dirrm</literal> lines to remove them when the
- package is deleted.</para>
+ <filename>/usr/local</filename>.</para>
<para>Here is a small example:</para>
@@ -155,8 +152,7 @@ man/man1/oneko.1.gz
lib/X11/app-defaults/Oneko
lib/X11/oneko/cat1.xpm
lib/X11/oneko/cat2.xpm
-lib/X11/oneko/mouse.xpm
- at dirrm lib/X11/oneko</programlisting>
+lib/X11/oneko/mouse.xpm</programlisting>
<para>Refer to the &man.pkg-create.8; manual page for details
on the packing list.</para>
@@ -167,19 +163,17 @@ lib/X11/oneko/mouse.xpm
changes when upgrading the port much easier.</para>
</note>
- <note>
+ <tip>
<para>Creating a packing list manually can be a very tedious
task. If the port installs a large numbers of files,
<link linkend="plist-autoplist">creating the packing list
automatically</link> might save time.</para>
- </note>
+ </tip>
<para>There is only one case when
<filename>pkg-plist</filename> can be omitted from a port.
- If the port installs just a handful of files, and perhaps
- directories, the files and directories may be listed in the
- variables <varname>PLIST_FILES</varname> and
- <varname>PLIST_DIRS</varname>, respectively, within the
+ If the port installs just a handful of files, list them in
+ <varname>PLIST_FILES</varname>, within the
port's <filename>Makefile</filename>. For instance, we
could get along without <filename>pkg-plist</filename> in
the above <filename>oneko</filename> port by adding these
@@ -190,27 +184,29 @@ lib/X11/oneko/mouse.xpm
lib/X11/app-defaults/Oneko \
lib/X11/oneko/cat1.xpm \
lib/X11/oneko/cat2.xpm \
- lib/X11/oneko/mouse.xpm
-PLIST_DIRS= lib/X11/oneko</programlisting>
-
- <para>Of course, <varname>PLIST_DIRS</varname> does not need to
- be set if a port installs no directories of its own.</para>
+ lib/X11/oneko/mouse.xpm</programlisting>
<note>
- <para>Several ports can share a common directory. In that
- case, <varname>PLIST_DIRS</varname> must be replaced by
- <varname>PLIST_DIRSTRY</varname> so that the directory is
- removed only if empty, otherwise it is silently ignored.
- <varname>PLIST_DIRS</varname> and
- <varname>PLIST_DIRSTRY</varname> are equivalent to using
- <literal>@dirrm</literal> and <literal>@dirrmtry</literal>
- in <filename>pkg-plist</filename>, as described in
- <xref linkend="plist-dir-cleaning"/>.</para>
+ <para>Usage of <varname>PLIST_FILES</varname> should not be
+ abused. When looking for the origin of a file, people
+ usually try to <application>grep</application> through the
+ <filename>pkg-plist</filename> files in the ports tree.
+ Listing files in <varname>PLIST_FILES</varname> in the
+ <filename>Makefile</filename> makes that search more
+ difficult.</para>
</note>
+ <tip>
+ <para>If a port needs to create an empty directory, or creates
+ directories outside of <filename>${PREFIX}</filename> during
+ installation, refer to <xref linkend="plist-dir-cleaning"/>
+ for more information.</para>
+ </tip>
+
<para>The price for this way of listing a port's files and
- directories is that then command sequences described in
- &man.pkg-create.8; cannot be used. Therefore, it is suitable
+ directories is that the keywords described in
+ &man.pkg-create.8; and <xref linkend="plist-keywords"/> cannot
+ be used. Therefore, it is suitable
only for simple ports and makes them even simpler. At the
same time, it has the advantage of reducing the number of
files in the ports collection. Please consider using this
More information about the svn-doc-head
mailing list