From owner-svn-doc-head@FreeBSD.ORG Thu Mar 27 16:50:33 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 58E1D465; Thu, 27 Mar 2014 16:50:33 +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 444AB8DB; Thu, 27 Mar 2014 16:50:33 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s2RGoX0G074747; Thu, 27 Mar 2014 16:50:33 GMT (envelope-from mat@svn.freebsd.org) Received: (from mat@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s2RGoWkT074743; Thu, 27 Mar 2014 16:50:32 GMT (envelope-from mat@svn.freebsd.org) Message-Id: <201403271650.s2RGoWkT074743@svn.freebsd.org> From: Mathieu Arnold Date: Thu, 27 Mar 2014 16:50:32 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44363 - in head/en_US.ISO8859-1/books/porters-handbook: pkg-files plist upgrading 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: Thu, 27 Mar 2014 16:50:33 -0000 Author: mat (ports committer) Date: Thu Mar 27 16:50:32 2014 New Revision: 44363 URL: http://svnweb.freebsd.org/changeset/doc/44363 Log: Update plist, pkg-files and upgrading chapters. Sponsored by: Absolight Modified: head/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml head/en_US.ISO8859-1/books/porters-handbook/upgrading/chapter.xml Modified: head/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml Thu Mar 27 16:13:55 2014 (r44362) +++ head/en_US.ISO8859-1/books/porters-handbook/pkg-files/chapter.xml Thu Mar 27 16:50:32 2014 (r44363) @@ -54,25 +54,15 @@ pkg install you can do this via the pkg-install script. This script will automatically be added to the package, and will be run twice by - pkg the first time as - - ${SH} pkg-install ${PKGNAME} - PRE-INSTALL and the second time as + pkg the first time as ${SH} + pkg-install ${PKGNAME} PRE-INSTALL before the + package is installed and the second time as ${SH} pkg-install ${PKGNAME} - POST-INSTALL. $2 can be - tested to determine which mode the script is being run in. - The PKG_PREFIX environmental variable will be - set to the package installation directory. - - - This script is not run automatically if you install the - port with make install. If you are - depending on it being run, you will have to explicitly call - it from your port's Makefile, with a - line like PKG_PREFIX=${PREFIX} ${SH} - ${PKGINSTALL} ${PKGNAME} - PRE-INSTALL. - + POST-INSTALL after it has been installed. + $2 can be tested to determine which + mode the script is being run in. The PKG_PREFIX + environmental variable will be set to the package installation + directory. @@ -80,12 +70,16 @@ This script executes when a package is removed. - This script will be run twice by - pkg delete The first time as + This script will be run twice by pkg + delete The first time as ${SH} + pkg-deinstall ${PKGNAME} DEINSTALL before the + port is de-installed and the second time as ${SH} pkg-deinstall ${PKGNAME} - DEINSTALL and the second time as - ${SH} pkg-deinstall - ${PKGNAME} POST-DEINSTALL. + POST-DEINSTALL after the port has been de-installed. + $2 can be tested to determine which + mode the script is being run in. The PKG_PREFIX + environmental variable will be set to the package installation + directory @@ -143,12 +137,6 @@ - - Please change these variables rather than overriding - PKG_ARGS. If you change - PKG_ARGS, those files will not correctly be - installed in /var/db/pkg upon install - from a port. @@ -163,14 +151,15 @@ The SUB_FILES variable specifies a list of files to be automatically modified. Each - file in the + file in the SUB_FILES list must have a corresponding - file.in present in - FILESDIR. A modified version will be created - in WRKDIR. Files defined as a value of - USE_RC_SUBR (or the deprecated - USE_RCORDER) are automatically added to the - SUB_FILES. For the files + file.in present + in FILESDIR. A modified version will be + created as + ${WRKDIR}/file. + Files defined as a value of USE_RC_SUBR (or + the deprecated USE_RCORDER) are automatically + added to the SUB_FILES. For the files pkg-message, pkg-install, and pkg-deinstall, the corresponding Makefile @@ -186,7 +175,7 @@ LOCALBASE, DATADIR, DOCSDIR, EXAMPLESDIR, WWWDIR, and ETCDIR. Any - line beginning with @comment will be deleted + line beginning with @comment will be deleted from resulting files after a variable substitution. The following example will replace Modified: head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml Thu Mar 27 16:13:55 2014 (r44362) +++ head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml Thu Mar 27 16:50:32 2014 (r44363) @@ -57,19 +57,22 @@ PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSI 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) -PLIST_SUB+= X11="" -.else -PLIST_SUB+= X11="@comment " -.endif - - and in the pkg-plist: + %%OPT%% for lines needed when the option is + enabled, or %%NO_OPT%% when the option is + disabled, and adding OPTIONS_SUB=yes to the + Makefile. See for more information. + + For instance, if there are files that are only installed + when the X11 option is enabled, and the + Makefile has: + + OPTIONS_DEFINE= X11 +OPTIONS_SUB= yes + + In the pkg-plist file, put + %%X11%% in front of the lines only being + installed when the option is enabled, like this : %%X11%%bin/foo-gui @@ -104,6 +107,24 @@ PLIST_SUB+= X11="@comment " and PLIST_DIRSTRY must be set before TMPPLIST is written, i.e., in pre-install or earlier. + + From time to time, the OPTIONS_SUB + construct is not enough, in those cases, adding a specific + TAG to the PLIST_SUB + variable inside the Makefile with a special + value of @comment, makes package tools to + ignore the line. For instance, if some files are only installed + when the X11 option is on and the + architecture is i386: + + .include <bsd.port.pre.mk> + +.if ${PORT_OPTIONS:MX11} && ${ARCH} == "i386" +PLIST_SUB+= X11I386="" +.else +PLIST_SUB+= X11I386="@comment " +.endif + @@ -112,10 +133,10 @@ PLIST_SUB+= X11="@comment " 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 + 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. You need to delete subdirectories before you can delete parent directories. @@ -209,6 +230,17 @@ etc/orbit.conf.sample message pointing out that the user must copy and edit the file before the software will work. + + + When a port installs its configuration in a subdirectory + of ${PREFIX}/etc, it should be in + ETCDIR, which defaults to + ${PREFIX}/etc/${PORTNAME}, it can be + overrided in the ports Makefile if there + is a convention for the port to use some other directory. The + %%ETCDIR%% macro should be used in its + stead in the pkg-plist file. + @@ -223,9 +255,10 @@ etc/orbit.conf.sample 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. + Collection by a committer (e.g., using make + makeplist>), 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 @@ -249,14 +282,17 @@ etc/orbit.conf.sample 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 + First, make sure the port is almost complete, with only + pkg-plist missing. Running make + makeplist will show what should be put in + pkg-plist. The output of + makeplist must be double checked for + correctness as it tries to automatically guess a few things, and + can get it wrong. + + User configuration files should be installed as + filename.sample, as it is described in + . The info/dir file should not be listed and appropriate install-info lines should be added as noted in the Modified: head/en_US.ISO8859-1/books/porters-handbook/upgrading/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/upgrading/chapter.xml Thu Mar 27 16:13:55 2014 (r44362) +++ head/en_US.ISO8859-1/books/porters-handbook/upgrading/chapter.xml Thu Mar 27 16:50:32 2014 (r44363) @@ -147,7 +147,10 @@ to see what has changed, and to update the diff if something was modified in the Ports Collection since you began work on it, or if the - committer asks for something to be fixed. + committer asks for something to be fixed. Also, a patch + generated with svn diff can be easily applied + with svn patch and will save some time to the + committer. &prompt.user; cd ~/my_wrkdir &prompt.user; svn co https://svn0.us-west.FreeBSD.org/ports/head/dns/pdnsd @@ -173,10 +176,11 @@ While in the working directory, make any changes that you - would usually make to the port. If you add or remove a file, - use svn to track these changes: + would usually make to the port. If you add, move or remove a + file, use svn to track these changes: &prompt.user; svn add new_file +&prompt.user; svn move old_name new_name &prompt.user; svn remove deleted_file Make sure that you check the port using the checklist in @@ -251,6 +255,14 @@ Send your patch following the guidelines in . + + + You can have patch automatically generated and the PR + pre-filled with your contact information by using + the Port Tools port + submit command. See for more details. + @@ -273,6 +285,17 @@ instructions, please make sure to get the shell escaping right. + + It is recommended that the AFFECTS line contains a glob + matching all the ports affected by the entry so that automated + tools can parse it as easily as possible. If an update + concerns all the existing BIND 9 + versions the AFFECTS content should be + users of dns/bind9*, it should + not be users of BIND + 9 + + The /usr/ports/MOVED file is used to list moved or removed ports. Each line in the file is made up of the name of the port, where the port was moved to, when, @@ -285,12 +308,18 @@ The date should be entered in the form YYYY-MM-DD. New entries should be added to - the end of the file to keep it in chronological order. + the top of the file to keep it in reverse chronological order + (the latest entries first). If a port was removed but has since been restored, delete the line in this file that states that it was removed. + If a port was renamed and then renamed back to its original + name, you should add a new one with the intermediate name to the + old name, and remove the old entry as to not create a + loop. + The changes can be validated with Tools/scripts/MOVEDlint.awk.