From owner-svn-doc-head@FreeBSD.ORG Thu Oct 2 13:47:41 2014 Return-Path: Delivered-To: svn-doc-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 2B1BBA94; Thu, 2 Oct 2014 13:47:41 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 14B40611; Thu, 2 Oct 2014 13:47:41 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.9/8.14.9) with ESMTP id s92DleEh090352; Thu, 2 Oct 2014 13:47:40 GMT (envelope-from mat@FreeBSD.org) Received: (from mat@localhost) by svn.freebsd.org (8.14.9/8.14.9/Submit) id s92DleuY090349; Thu, 2 Oct 2014 13:47:40 GMT (envelope-from mat@FreeBSD.org) Message-Id: <201410021347.s92DleuY090349@svn.freebsd.org> X-Authentication-Warning: svn.freebsd.org: mat set sender to mat@FreeBSD.org using -f From: Mathieu Arnold Date: Thu, 2 Oct 2014 13:47:40 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r45707 - in head/en_US.ISO8859-1/books/porters-handbook: makefiles plist quick-porting X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.18-1 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 02 Oct 2014 13:47:41 -0000 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 %%PORTDOCS%% prefix, for example: %%PORTDOCS%%%%DOCSDIR%%/AUTHORS -%%PORTDOCS%%%%DOCSDIR%%/CONTACT -%%PORTDOCS%%@dirrm %%DOCSDIR%% +%%PORTDOCS%%%%DOCSDIR%%/CONTACT As an alternative to enumerating the documentation files in pkg-plist, 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 TMPPLIST. Another way of modifying a port's packing list is based on - setting the variables PLIST_FILES, - PLIST_DIRS, and - PLIST_DIRSTRY. The value of each variable is + setting the variables PLIST_FILES and + PLIST_DIRS. The value of each variable is regarded as a list of pathnames to write to TMPPLIST along with PLIST contents. Names listed in - PLIST_FILES, PLIST_DIRS, - and PLIST_DIRSTRY are subject to + PLIST_FILES and + PLIST_DIRS are subject to %%VAR%% substitution as described above. Except for that, names from PLIST_FILES will appear in the final packing - list unchanged, while @dirrm and - @dirrmtry will be prepended to names from - PLIST_DIRS and - PLIST_DIRSTRY, respectively. To take effect, - PLIST_FILES, PLIST_DIRS, - and PLIST_DIRSTRY must be set before + list unchanged, while @dir + will be prepended to names from + PLIST_DIRS. To take effect, + PLIST_FILES and + PLIST_DIRS must be set before TMPPLIST is written, that is, in pre-install or earlier. @@ -138,33 +136,18 @@ PLIST_SUB+= X11I386="@comment " Cleaning Up Empty Directories - When being de-installed, A port has to remove empty - directories it created. This is usually accomplished by - adding @dirrm lines for all directories - that are specifically created by the port. Subdirectories - must be deleted before deleting parent - directories. - - : -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 - - However, sometimes @dirrm will give - errors because other ports share the same directory. - Use @dirrmtry to remove only empty - directories without warning. - - @dirrmtry share/doc/gimp - - This will neither print any error messages nor cause - pkg delete (see &man.pkg-delete.8;) to - exit abnormally even if - ${PREFIX}/share/doc/gimp is not empty - due to other ports installing some files in there. + 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 ${PREFIX}, or empty + directories, some more work needs to be done. This is usually + accomplished by adding @dir lines for those + directories. Subdirectories must be deleted before deleting + parent directories. + + [...] +@dir /var/games/oneko/saved-games +@dir /var/games/oneko @@ -179,10 +162,9 @@ lib/X11/oneko/sounds/cat.au @${MKDIR} ${STAGEDIR}${PREFIX}/some/directory Add the directory to pkg-plist - like any other. For example, if the directory has files - created when the port is used: + like any other. For example: - @dirrmtry some/directory + @dir some/directory @@ -264,8 +246,8 @@ etc/orbit.conf-dist pkg-plist (with or without variable substitution), or embedded into the Makefile via - PLIST_FILES, PLIST_DIRS, - and PLIST_DIRSTRY. Even if the contents are + PLIST_FILES and + PLIST_DIRS. Even if the contents are auto-generated by a tool or a target in the Makefile before the inclusion into the Ports Collection by a committer (for example, using make @@ -337,7 +319,7 @@ etc/orbit.conf-dist <literal>@fc</literal> <replaceable>directory</replaceable> - Add a @dirrmtry entry for the + Add a @dir entry for the directory passed as an argument, and run fc-cache -s on that directory after installation and deinstallation. @@ -347,7 +329,7 @@ etc/orbit.conf-dist <literal>@fcfontsdir</literal> <replaceable>directory</replaceable> - Add a @dirrmtry entry for the + Add a @dir entry for the directory passed as an argument, and run fc-cache -s, mkfontscale and mkfontdir on that directory after @@ -362,7 +344,7 @@ etc/orbit.conf-dist <literal>@fontsdir</literal> <replaceable>directory</replaceable> - Add a @dirrmtry entry for the + Add a @dir entry for the directory passed as an argument, and run mkfontscale and mkfontdir 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/packing list because the package is generated by packing the files listed here. The pathnames are relative to the installation prefix (usually - /usr/local. If the port creates - directories during installation, make sure to add - @dirrm lines to remove them when the - package is deleted. + /usr/local. Here is a small example: @@ -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 +lib/X11/oneko/mouse.xpm Refer to the &man.pkg-create.8; manual page for details on the packing list. @@ -167,19 +163,17 @@ lib/X11/oneko/mouse.xpm changes when upgrading the port much easier. - + Creating a packing list manually can be a very tedious task. If the port installs a large numbers of files, creating the packing list automatically might save time. - + There is only one case when pkg-plist 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 PLIST_FILES and - PLIST_DIRS, respectively, within the + If the port installs just a handful of files, list them in + PLIST_FILES, within the port's Makefile. For instance, we could get along without pkg-plist in the above oneko 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 - - Of course, PLIST_DIRS does not need to - be set if a port installs no directories of its own. + lib/X11/oneko/mouse.xpm - Several ports can share a common directory. In that - case, PLIST_DIRS must be replaced by - PLIST_DIRSTRY so that the directory is - removed only if empty, otherwise it is silently ignored. - PLIST_DIRS and - PLIST_DIRSTRY are equivalent to using - @dirrm and @dirrmtry - in pkg-plist, as described in - . + Usage of PLIST_FILES should not be + abused. When looking for the origin of a file, people + usually try to grep through the + pkg-plist files in the ports tree. + Listing files in PLIST_FILES in the + Makefile makes that search more + difficult. + + If a port needs to create an empty directory, or creates + directories outside of ${PREFIX} during + installation, refer to + for more information. + + 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 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