From owner-svn-doc-head@FreeBSD.ORG Sun Feb 9 04:05:25 2014 Return-Path: Delivered-To: svn-doc-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id B1E451DA; Sun, 9 Feb 2014 04:05:25 +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)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id 9BBC310DE; Sun, 9 Feb 2014 04:05:25 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s1945PYI081945; Sun, 9 Feb 2014 04:05:25 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s1945PhX081944; Sun, 9 Feb 2014 04:05:25 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201402090405.s1945PhX081944@svn.freebsd.org> From: Warren Block Date: Sun, 9 Feb 2014 04:05:25 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r43850 - head/en_US.ISO8859-1/books/porters-handbook/plist 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.17 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: Sun, 09 Feb 2014 04:05:25 -0000 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$ --> - + + + Advanced <filename>pkg-plist</filename> Practices + + + Changing <filename>pkg-plist</filename> Based on Make + Variables + + Some ports, particularly the p5- ports, + need to change their pkg-plist depending on + what options they are configured with (or version of + perl, in the case of p5- + ports). To make this easy, any instances in the + pkg-plist of %%OSREL%%, + %%PERL_VER%%, and + %%PERL_VERSION%% will be substituted for + appropriately. The value of %%OSREL%% is the + numeric revision of the operating system (e.g., + 4.9). %%PERL_VERSION%% + and %%PERL_VER%% is the full version number + of perl (e.g., 5.8.9). + Several other %%VARS%% related to port's + documentation files are described in + the relevant + section. + + If you need to make other substitutions, you can set the + PLIST_SUB variable with a list of + VAR=VALUE pairs and instances of + %%VAR%% will be substituted with + VALUE in the + pkg-plist. + + For instance, if you have a port that installs many files + in a version-specific subdirectory, you can put something + like - Advanced <filename>pkg-plist</filename> Practices - - - Changing <filename>pkg-plist</filename> Based on Make - Variables - - Some ports, particularly the p5- ports, - need to change their pkg-plist depending - on what options they are configured with (or version of - perl, in the case of p5- - ports). To make this easy, any instances in the - pkg-plist of - %%OSREL%%, %%PERL_VER%%, - and %%PERL_VERSION%% will be substituted - for appropriately. The value of %%OSREL%% - is the numeric revision of the operating system (e.g., - 4.9). %%PERL_VERSION%% - and %%PERL_VER%% is the full version number - of perl (e.g., 5.8.9). - Several other - %%VARS%% related - to port's documentation files are described in - the relevant - section. - - If you need to make other substitutions, you can set the - PLIST_SUB variable with a list of - VAR=VALUE - pairs and instances of - %%VAR%% will be - substituted with VALUE in the - pkg-plist. - - For instance, if you have a port that installs many files - in a version-specific subdirectory, you can put something - like - - OCTAVE_VERSION= 2.0.13 + OCTAVE_VERSION= 2.0.13 PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION} - in the Makefile and use - %%OCTAVE_VERSION%% wherever the version - shows up in pkg-plist. That way, when - you upgrade the port, you will not have to change dozens (or - in some cases, hundreds) of lines in the - pkg-plist. - - If your port installs files conditionally on the options - set in the port, the usual way of handling it is prefixing the - pkg-plist lines with a - %%TAG%% and adding that - TAG to the PLIST_SUB - variable inside the Makefile with a - special value of @comment, which makes - package tools to ignore the line: + in the Makefile and use + %%OCTAVE_VERSION%% wherever the version shows + up in pkg-plist. That way, when you + upgrade the port, you will not have to change dozens (or in some + cases, hundreds) of lines in the + pkg-plist. + + If your port installs files conditionally on the options + set in the port, the usual way of handling it is prefixing the + pkg-plist lines with a + %%TAG%% and adding that + TAG to the PLIST_SUB + variable inside the Makefile with a special + value of @comment, which makes package tools + to ignore the line: - .if defined(WITH_X11) + .if defined(WITH_X11) PLIST_SUB+= X11="" .else PLIST_SUB+= X11="@comment " .endif - and in the pkg-plist: + and in the pkg-plist: - %%X11%%bin/foo-gui + %%X11%%bin/foo-gui - This substitution - will be - done between the pre-install and - do-install targets, by reading from - PLIST and writing to - TMPPLIST (default: - WRKDIR/.PLIST.mktmp). - So if your port builds - PLIST on the fly, do - so in or before pre-install. Also, - if your port needs to edit the resulting file, do so in - post-install to a file named - 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 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 - %%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 - TMPPLIST is written, - i.e., in pre-install or - earlier. - - - - Empty Directories - - - Cleaning Up Empty Directories - - Do make your ports remove empty directories when they - are de-installed. This is usually accomplished by adding - @dirrm lines for all directories that are - specifically created by the port. You need to delete - subdirectories before you can delete parent - directories. + This substitution will be done between the + pre-install and + do-install targets, by reading from + PLIST and writing to + TMPPLIST (default: + WRKDIR/.PLIST.mktmp). So if your port + builds PLIST on the fly, do so in or before + pre-install. Also, if your port + needs to edit the resulting file, do so in + post-install to a file named + 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 + 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 + %%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 + TMPPLIST is written, i.e., in + pre-install or earlier. + + + + Empty Directories + + + Cleaning Up Empty Directories + + Do make your ports remove empty directories when they are + de-installed. This is usually accomplished by adding + @dirrm lines for all directories that are + specifically created by the port. You need to delete + subdirectories before you can delete parent + directories. - : + : 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 - However, sometimes @dirrm will give - you errors because other ports share the same directory. - You can 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. - - - - Creating Empty Directories - - 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 pkg add and pkg - install creates directories for them as needed. - To make sure the empty directory is created when installing - the package, add this line to pkg-plist - above the corresponding @dirrm - line: + However, sometimes @dirrm will give + you errors because other ports share the same directory. You + can 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. + + + + Creating Empty Directories + + 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 + pkg add and pkg install + creates directories for them as needed. To make sure the + empty directory is created when installing the package, add + this line to pkg-plist above the + corresponding @dirrm line: @exec mkdir -p %D/share/foo/templates - - + + - - Configuration Files + + Configuration Files - If your port installs configuration files to - PREFIX/etc (or - elsewhere) do not simply list them in the - pkg-plist. That will cause pkg - delete to remove the files carefully edited by the - user, and a re-installation will wipe them out. - - Instead, install sample file(s) with a - filename.sample - 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 .sample file. - You need to handle this both in the port - Makefile, and in the - pkg-plist (for installation from the - package). + If your port installs configuration files to + PREFIX/etc (or elsewhere) do + not simply list them in the + pkg-plist. That will cause + pkg delete to remove the files carefully + edited by the user, and a re-installation will wipe them + out. + + Instead, install sample file(s) with a + filename.sample 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 .sample + file. You need to handle this both in the port + Makefile, and in the + pkg-plist (for installation from the + package). - Example of the Makefile part: + Example of the Makefile part: - post-install: + post-install: @if [ ! -f ${PREFIX}/etc/orbit.conf ]; then \ ${CP} -p ${PREFIX}/etc/orbit.conf.sample ${STAGEDIR}${PREFIX}/etc/orbit.conf ; \ fi - For each configuration file, create the following three - lines in pkg-plist: + For each configuration file, create the following three + lines in pkg-plist: - @unexec if cmp -s %D/etc/orbit.conf.sample %D/etc/orbit.conf; then rm -f %D/etc/orbit.conf; fi + @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 - 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 - @unexec 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 @exec line - comes after the sample configuration file name. - - To debug any issues, temporarily remove the - -s flag to &man.cmp.1; for more - output. - - See &man.pkg-create.8; for more information on - %D and related substitution markers. - - If there is a very good reason not to install a working - configuration file by default, leave the - @exec line out of - pkg-plist and add a - message pointing out - that the user must copy and edit the file before the software - will work. - - - - Dynamic Versus Static Package List - - A static package list is a package - list which is available in the Ports Collection either as a - pkg-plist file (with or without variable - substitution), or embedded into the - Makefile via - PLIST_FILES, - PLIST_DIRS, and - PLIST_DIRSTRY. 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, this is still considered a static - list, since it is possible to examine it without having to - download or compile the distfile. - - A dynamic package list 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 - make clean. - - 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 - Javadoc). - - - - Automated Package List Creation - - First, make sure your port is almost complete, with only - pkg-plist missing. You may then run - make makeplist to - generate a pkg-plist automatically. This - file must be double checked for correctness. - - User configuration files should be - removed, or installed as - filename.sample. - The info/dir file should not be listed - and appropriate install-info lines should - be added as noted in the - info files section. Any - libraries installed by the port should be listed as specified - in the shared libraries - section. - - - + 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 + @unexec 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 @exec line + comes after the sample configuration file name. + + To debug any issues, temporarily remove the + -s flag to &man.cmp.1; for more + output. + + See &man.pkg-create.8; for more information on + %D and related substitution markers. + + If there is a very good reason not to install a working + configuration file by default, leave the + @exec line out of + pkg-plist and add a + message pointing out that + the user must copy and edit the file before the software will + work. + + + + Dynamic Versus Static Package List + + A static package list is a package + list which is available in the Ports Collection either as a + pkg-plist file (with or without variable + substitution), or embedded into the + Makefile via + PLIST_FILES, PLIST_DIRS, + and PLIST_DIRSTRY. 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, this is still considered a static + list, since it is possible to examine it without having to + download or compile the distfile. + + A dynamic package list 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 + make clean. + + 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 Javadoc). + + + + Automated Package List Creation + + First, make sure your port is almost complete, with only + pkg-plist missing. You may then run + make makeplist to generate a + pkg-plist automatically. This file must be + double checked for correctness. + + User configuration files should be removed, or installed as + filename.sample. The + info/dir file should not be listed and + appropriate install-info lines should be + added as noted in the + info files section. Any + libraries installed by the port should be listed as specified in + the shared libraries + section. + +