From owner-svn-doc-all@FreeBSD.ORG Mon Sep 22 16:15:38 2014 Return-Path: Delivered-To: svn-doc-all@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 B1D13B6E; Mon, 22 Sep 2014 16:15:38 +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 91A9DF1E; Mon, 22 Sep 2014 16:15:38 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.9/8.14.9) with ESMTP id s8MGFchJ076543; Mon, 22 Sep 2014 16:15:38 GMT (envelope-from mat@FreeBSD.org) Received: (from mat@localhost) by svn.freebsd.org (8.14.9/8.14.9/Submit) id s8MGFctl076542; Mon, 22 Sep 2014 16:15:38 GMT (envelope-from mat@FreeBSD.org) Message-Id: <201409221615.s8MGFctl076542@svn.freebsd.org> X-Authentication-Warning: svn.freebsd.org: mat set sender to mat@FreeBSD.org using -f From: Mathieu Arnold Date: Mon, 22 Sep 2014 16:15:38 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r45656 - 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-all@freebsd.org X-Mailman-Version: 2.1.18-1 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 22 Sep 2014 16:15:38 -0000 Author: mat (ports committer) Date: Mon Sep 22 16:15:38 2014 New Revision: 45656 URL: http://svnweb.freebsd.org/changeset/doc/45656 Log: Document the @dir and @ empty keyword Deprecate @dirrm and @dirrmtry Keywords now use ucl files Differential Revision: https://reviews.freebsd.org/D807 Reviewed by: wblock, bjk Sponsored by: Absolight 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 Mon Sep 22 04:01:24 2014 (r45655) +++ head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml Mon Sep 22 16:15:38 2014 (r45656) @@ -318,6 +318,19 @@ etc/orbit.conf-dist Expanding Package List with Keywords + All keywords can also take optional arguments in + parentheses. The arguments are owner, group, and mode. This + argument is used on the file or directory referenced. + To change the owner, group, and mode of a configuration file, + use: + + @sample(games,games,640) etc/config.sample + + The arguments are optional. If only the group and mode + need to be changed, use: + + @sample(,games,660) etc/config.sample + @@ -401,10 +414,22 @@ etc/orbit.conf-dist Base Keywords - There are a few historic keywords that are hardcoded, and + There are a few keywords that are hardcoded, and documented in &man.pkg-create.8;. For the sake of completeness, they are also documented here. + + <literal>@</literal> + [<replaceable>file</replaceable>] + + The empty keyword is a placeholder to use when the + file's owner, group, or mode need to be changed. For + example, to set the group of the file to + games and add the setgid bit, add: + + @(,games,2755) sbin/daemon + + <literal>@cwd</literal> [<replaceable>directory</replaceable>] @@ -497,6 +522,13 @@ etc/orbit.conf-dist same as that used by &man.chmod.1;. Use without an arg to set back to default permissions (mode of the file while being packed). + + + This must be a numeric mode, like + 644, 4755, or + 600. It cannnot be a relative mode + like u+s. + @@ -526,22 +558,37 @@ etc/orbit.conf-dist This line is ignored when packing. + + <literal>@dir</literal> + <replaceable>directory</replaceable> + + Declare directory name. By default, directories created + under PREFIX by a package installation + are automatically removed. Use this when an empty directory + under PREFIX needs to be created, or when + the directory needs to have non default owner, group, or + mode. Directories outside of PREFIX need + to be registered. For example, + /var/db/${PORTNAME} needs to have a + @dir entry whereas + ${PREFIX}/share/${PORTNAME} does not if + it contains files or uses the default owner, group, and + mode. + + <literal>@dirrm</literal> - <replaceable>directory</replaceable> + directory (Deprecated) Declare directory name to be deleted at deinstall time. - By default, directories created by a package installation - are not deleted when the package is deinstalled. This - provides an explicit directory cleanup method. These - directives must appear at the end of the package list. If - the directory is not empty a warning is printed, and the - directory is not removed. + By default, directories created under + PREFIX by a package installation are + deleted when the package is deinstalled. <literal>@dirrmtry</literal> - <replaceable>directory</replaceable> + directory (Deprecated) Declare directory name to be removed, as for @dirrm, but does not issue a warning if @@ -555,9 +602,9 @@ etc/orbit.conf-dist Package list files can be extended by keywords that are defined in the ${PORTSDIR}/Keywords directory. - The settings for each keyword lives in a - YAML file named - keyword.yaml. + The settings for each keyword are stored in a + UCL file named + keyword.ucl. The file must contain at least one of the next sections: @@ -595,11 +642,20 @@ etc/orbit.conf-dist + dir + + + Register a directory to be created on + install and removed on deinstall. + + + + dirrm Register a directory to be deleted on - deinstall. + deinstall. Deprecated. @@ -608,7 +664,7 @@ etc/orbit.conf-dist Register a directory to try and deleted on - deinstall. + deinstall. Deprecated. @@ -701,13 +757,14 @@ etc/orbit.conf-dist removed when deinstalling the package. actions: [dirrmtry] -post-deinstall: | - echo "Directory %D/%@ removed." +post-deinstall: <<EOD + echo "Directory %D/%@ removed." +EOD Real Life Example, How the <literal>@sample</literal> - Could be Implemented + is Implemented This keyword does three things, it adds the filename passed as an argument to @@ -719,7 +776,7 @@ post-deinstall: | configuration file if it has not been modified. actions: [file] -post-install: | +post-install: <<EOD case "%@" in /*) sample_file="%@" ;; *) sample_file="%D/%@" ;; @@ -728,7 +785,8 @@ post-install: | if ! [ -f "${target_file}" ]; then /bin/cp -p "${sample_file}" "${target_file}" fi -pre-deinstall: | +EOD +pre-deinstall: <<EOD case "%@" in /*) sample_file="%@" ;; *) sample_file="%D/%@" ;; @@ -736,7 +794,10 @@ pre-deinstall: | target_file="${sample_file%.sample}" if cmp -s "${target_file}" "${sample_file}"; then rm -f "${target_file}" - fi + else + echo "You may need to manually remove ${target_file} if it's no longer needed." + fi +EOD