Bug 181080

Comment 1 Frederic Culot 2013-09-01 08:22:08 UTC

Following an off-list feedback from Warren (wblock@) I submit this
updated patch which adds a note explaining into a bit more detail
what PLIST_DIRSTRY is used for.

This note is added right after the first PLIST_DIRS appearence and
gives a link to the section where the @dirrm and @dirrmtry macros
are explained, so I believe the reader is now able to grasp the
meaning of PLIST_DIRSTRY more easily.

However, adding an example of the PLIST_DISTRY usage was not deemed
necessary as it is pretty straightforward to extrapolate the already
existing PLIST_DIRS example for PLIST_DIRSTRY.

Feel free to ping me in case you have any comments related to this
updated patch, and thanks again Warren for your feedback.

Cheers,
Frederic

Comment 2 Warren Block 2013-09-02 19:19:10 UTC

Responsible Changed
From-To: freebsd-doc->wblock

Take.

Comment 3 dfilter service 2013-09-02 19:21:39 UTC

Author: wblock
Date: Mon Sep  2 18:21:26 2013
New Revision: 42608
URL: http://svnweb.freebsd.org/changeset/doc/42608

Log:
  Mention PLIST_DIRSTRY.  Committed version is slightly edited from the
  second diff in the PR.
  
  PR:		 docs/181080
  Submitted by:	 Frederic Culot <culot@FreeBSD.org>

Modified:
  head/en_US.ISO8859-1/books/porters-handbook/book.xml

Modified: head/en_US.ISO8859-1/books/porters-handbook/book.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/book.xml	Sun Sep  1 22:36:52 2013	(r42607)
+++ head/en_US.ISO8859-1/books/porters-handbook/book.xml	Mon Sep  2 18:21:26 2013	(r42608)
@@ -278,6 +278,19 @@ PLIST_DIRS=	lib/X11/oneko</programlistin
 	<para>Of course, <makevar>PLIST_DIRS</makevar> should be left
 	  unset if a port installs no directories of its own.</para>
 
+	<note>
+
+	  <para>Several ports can share a common directory.  In that
+	    case, <makevar>PLIST_DIRS</makevar> should be replaced by
+	    <makevar>PLIST_DIRSTRY</makevar> so that the directory is
+	    removed only if empty, otherwise it is silently ignored.
+	    <makevar>PLIST_DIRS</makevar> and
+	    <makevar>PLIST_DIRSTRY</makevar> 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>
+	</note>
+
 	<para>The price for this way of listing port's files and
 	  directories is that you cannot use command sequences
 	  described in &man.pkg.create.1;.  Therefore, it is suitable
@@ -9917,21 +9930,26 @@ PLIST_SUB+=	X11="@comment "
 	<maketarget>post-install</maketarget> to a file named
 	<filename><makevar>TMPPLIST</makevar></filename>.</para>
 
-      <para>Another possibility to modify port's packing list is based
-	on setting the variables <makevar>PLIST_FILES</makevar> and
-	<makevar>PLIST_DIRS</makevar>.  The value of each variable is
+      <para>Another way of modifying a port's packing list is based
+	on setting the variables <makevar>PLIST_FILES</makevar>,
+	<makevar>PLIST_DIRS</makevar>, and
+	<makevar>PLIST_DIRSTRY</makevar>.  The value of each variable is
 	regarded as a list of pathnames to write to
 	<filename><makevar>TMPPLIST</makevar></filename> along with
 	<filename><makevar>PLIST</makevar></filename> contents.  Names
-	listed in <makevar>PLIST_FILES</makevar> and
-	<makevar>PLIST_DIRS</makevar> are subject to
+	listed in <makevar>PLIST_FILES</makevar>,
+	<makevar>PLIST_DIRS</makevar>, and
+	<makevar>PLIST_DIRSTRY</makevar> are subject to
 	<literal>%%<replaceable>VAR</replaceable>%%</literal>
-	substitution, as described above.  Except for that, names from
+	substitution as described above.  Except for that, names from
 	<makevar>PLIST_FILES</makevar> will appear in the final
-	packing list unchanged, while <literal>@dirrm</literal> will
-	be prepended to names from <makevar>PLIST_DIRS</makevar>.  To
-	take effect, <makevar>PLIST_FILES</makevar> and
-	<makevar>PLIST_DIRS</makevar> must be set before
+	packing list unchanged, while <literal>@dirrm</literal> and
+	<literal>@dirrmtry</literal> will
+	be prepended to names from <makevar>PLIST_DIRS</makevar>
+	and <makevar>PLIST_DIRSTRY</makevar>, respectively.  To
+	take effect, <makevar>PLIST_FILES</makevar>,
+	<makevar>PLIST_DIRS</makevar>, and
+	<makevar>PLIST_DIRSTRY</makevar> must be set before
 	<filename><makevar>TMPPLIST</makevar></filename> is written,
 	i.e., in <maketarget>pre-install</maketarget> or
 	earlier.</para>
@@ -10059,8 +10077,9 @@ etc/orbit.conf.sample
 	<filename>pkg-plist</filename> file (with or without variable
 	substitution), or embedded into the
 	<filename>Makefile</filename> via
-	<makevar>PLIST_FILES</makevar> and
-	<makevar>PLIST_DIRS</makevar>.  Even if the contents are
+	<makevar>PLIST_FILES</makevar>,
+	<makevar>PLIST_DIRS</makevar>, and
+	<makevar>PLIST_DIRSTRY</makevar>.  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
_______________________________________________
svn-doc-all@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/svn-doc-all
To unsubscribe, send any mail to "svn-doc-all-unsubscribe@freebsd.org"

Comment 4 Warren Block 2013-09-02 19:21:44 UTC

State Changed
From-To: open->closed

Slightly edited version of second diff committed.  Thanks!