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

Second round of @dirrm* cleanup.

Browse source 
Differential Revision:	https://reviews.freebsd.org/D882
Reviewed by:	bcr
Sponsored by:	Absolight
This commit is contained in:
Mathieu Arnold 2014-10-02 13:47:39 +00:00
parent e67742da2c
commit 92af771969
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=45707
3 changed files with 52 additions and 75 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
View file

@ -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

72
en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml
View file

@ -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>
<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> :
lib/X11/oneko/pixmaps/cat.xpm
lib/X11/oneko/sounds/cat.au
:
@dirrm lib/X11/oneko/pixmaps
@dirrm lib/X11/oneko/sounds
@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>
<programlisting>[...]
@dir /var/games/oneko/saved-games
@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

52
en_US.ISO8859-1/books/porters-handbook/quick-porting/chapter.xml
View file

@ -143,10 +143,7 @@ WWW: http://www.oneko.org/</programlisting>
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
@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