From owner-svn-doc-all@FreeBSD.ORG Sun Apr 20 09:50:21 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 545B118D; Sun, 20 Apr 2014 09:50:21 +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 262CE1D05; Sun, 20 Apr 2014 09:50:21 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s3K9oLVa055481; Sun, 20 Apr 2014 09:50:21 GMT (envelope-from mat@svn.freebsd.org) Received: (from mat@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s3K9oLRY055480; Sun, 20 Apr 2014 09:50:21 GMT (envelope-from mat@svn.freebsd.org) Message-Id: <201404200950.s3K9oLRY055480@svn.freebsd.org> From: Mathieu Arnold Date: Sun, 20 Apr 2014 09:50:20 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44611 - 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.17 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: Sun, 20 Apr 2014 09:50:21 -0000 Author: mat (ports committer) Date: Sun Apr 20 09:50:20 2014 New Revision: 44611 URL: http://svnweb.freebsd.org/changeset/doc/44611 Log: Add a section about plist keywords. Reviewed by: wblock, bcr 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 Fri Apr 18 22:13:32 2014 (r44610) +++ head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml Sun Apr 20 09:50:20 2014 (r44611) @@ -304,4 +304,409 @@ etc/orbit.conf-dist the shared libraries section. + + + Expanding Package List with Keywords + + + <literal>@fc</literal> + <replaceable>directory</replaceable> + + Add a @dirrmtry entry for the + directory passed as an argument, and run fc-cache + -s on that directory after installation and + deinstallation. + + + + <literal>@fcfontsdir</literal> + <replaceable>directory</replaceable> + + Add a @dirrmtry entry for the + directory passed as an argument, and run fc-cache + -s, mkfontscale and + mkfontdir on that directory after + installation and deinstallation. Additionally, on + deinstallation, it removes the + fonts.scale and + fonts.dir cache files if they are + empty. + + + + <literal>@fontsdir</literal> + <replaceable>directory</replaceable> + + Add a @dirrmtry entry for the + directory passed as an argument, and run + mkfontscale and + mkfontdir on that directory after + installation and deinstallation. Additionally, on + deinstallation, it removes the + fonts.scale and + fonts.dir cache files if they are + empty. + + + + <literal>@info</literal> + <replaceable>file</replaceable> + + Add the file passed as argument to the plist, and updates + the info document index on installation and deinstallation. + Additionally, it removes the index if empty on + deinstallation. + + + + <literal>@sample</literal> + <replaceable>file</replaceable> + + Add the file passed as argument to the plist. + + On installation, check for a real file with + just the base name (the name without the + .sample extension). If the real file is + not found, copy the sample file to the base file name. On + deinstallation, remove the configuration file if it has not + been modified. See for more + information. + + + + Base Keywords + + There are a few historic keywords that are hardcoded, and + documented in &man.pkg-create.8;. For the sake of + completeness, they are also documented here. + + + <literal>@cwd</literal> + [<replaceable>directory</replaceable>] + + Set the internal directory pointer to point to + directory. All subsequent filenames are assumed relative to + this directory. + + + + <literal>@exec</literal> + <replaceable>command</replaceable> (deprecated) + + Execute command as part of + the unpacking process. If command contains any of the + following sequences somewhere in it, they are expanded + inline. For the following examples, assume that + @cwd is set to /usr/local and the last + extracted file was bin/emacs. + + + + %F + + + Expand to the last filename extracted (as + specified). In the example case + bin/emacs. + + + + + %D + + Expand to the current directory prefix, as set + with @cwd. In the example case + /usr/local. + + + + + %B + + + Expand to the basename of the fully qualified + filename, that is, the current directory prefix plus + the last filespec, minus the trailing filename. In + the example case, that would be /usr/local/bin. + + + + + %f + + + Expand to the filename part of the fully qualified + name, or the converse of %B. In + the example case, + emacs. + + + + + + + <literal>@unexec</literal> + <replaceable>command</replaceable> (deprecated) + + Execute command as part of + the deinstallation process. Expansion of special + % sequences is the same as for + @exec. This command is not executed + during the package add, as @exec is, but + rather when the package is deleted. This is useful for + deleting links and other ancillary files that were created + as a result of adding the package, but not directly known to + the package's table of contents (and hence not automatically + removable). + + + + <literal>@mode</literal> + <replaceable>mode</replaceable> + + Set default permission for all subsequently extracted + files to mode. Format is the + 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). + + + + <literal>@owner</literal> + <replaceable>user</replaceable> + + Set default ownership for all subsequent files to + user. Use without an argument to + set back to default ownership (root). + + + + <literal>@group</literal> + <replaceable>group</replaceable> + + Set default group ownership for all subsequent files to + group. Use without an arg to set + back to default group ownership (wheel). + + + + <literal>@comment</literal> + <replaceable>string</replaceable> + + This line is ignored when packing. + + + + <literal>@dirrm</literal> + <replaceable>directory</replaceable> + + 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 should appear at the end of the package list. If + the directory is not empty a warning is printed, and the + directory is not removed. + + + + <literal>@dirrmtry</literal> + <replaceable>directory</replaceable> + + Declare directory name to be removed, as for + @dirrm, but does not issue a warning if + the directory cannot be removed. + + + + + Creating Your Own Keyword + + 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 file must contain at least one of the following + sections: + + + + attributes + + + Changes the owner, group, or mode used by the + keyword. Contains an associative array where the + possible keys are owner, + group, and mode. + The values are, respectively, a user name, a group name, + and a file mode. For example: + + attributes: { owner: "games", group: "games", mode: 0555 } + + + + + action + + + Defines what happens to the keyword's parameter. + Contains an array where the possible values are: + + + + setprefix + + + Set the prefix for the next plist + entries. + + + + + dirrm + + + Register a directory to be deleted on + deinstall. + + + + + dirrmtry + + + Register a directory to try and deleted on + deinstall. + + + + + file + + + Register a file. + + + + + setmode + + + Set the mode for the next plist + entries. + + + + + setowner + + + Set the owner for the next plist + entries. + + + + + setgroup + + + Set the group for the next plist + entries. + + + + + comment + + + Does not do anything, equivalent to not + entering an action + section. + + + + + ignore_next + + + Ignore the next entry in the plist. + + + + + + + + pre-install + post-install + pre-deinstall + post-deinstall + pre-upgrade + post-upgrade + + + These keywords contains a &man.sh.1; script to be + executed before or after installation, deinstallation, + or upgrade of the package. In addition to the usual + @exec + %foo + placeholders described in , there is a new + one, %@, which represents the + argument of the keyword. + + + + + + Example of a <literal>@dirrmtryecho</literal> + Keyword + + This keyword does two things, it adds a + @dirrmtry + directory line to the + packing list, and echoes the fact that the directory is + removed when deinstalling the package. + + actions: [dirrmtry] +post-deinstall: | + echo "Directory %D/%@ removed." + + + + Real Life Example, How the <literal>@sample</literal> + Could be Implemented + + This keyword does three things, it adds the + filename passed as an argument to + @sample to the packing list, it adds to + the post-install script instructions to + copy the sample to the actual configuration file if it does + not already exist, and it adds to the + post-deinstall instructions to remove the + configuration file if it has not been modified. + + actions: [file] +post-install: | + sample_file="%D/%@" + target_file="${sample_file%.sample}" + if ! [ -f "${target_file}" ]; then + /bin/cp -p "${sample_file}" "${target_file}" + fi +pre-deinstall: | + sample_file="%D/%@" + target_file="${sample_file%.sample}" + if cmp -s "${target_file}" "${sample_file}"; then + rm -f "${target_file}" + fi + + +