svn commit: r45656 - head/en_US.ISO8859-1/books/porters-handbook/plist
Mathieu Arnold
mat at FreeBSD.org
Mon Sep 22 16:15:38 UTC 2014
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
<sect1 xml:id="plist-keywords">
<title>Expanding Package List with Keywords</title>
+ <para>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:</para>
+
+ <programlisting>@sample(games,games,640) etc/config.sample</programlisting>
+
+ <para>The arguments are optional. If only the group and mode
+ need to be changed, use:</para>
+
+ <programlisting>@sample(,games,660) etc/config.sample</programlisting>
+
<!-- Try and keep the keywords alphanumerically sorted -->
<sect2 xml:id="plist-keywords-fc">
@@ -401,10 +414,22 @@ etc/orbit.conf-dist
<sect2 xml:id="plist-keywords-base">
<title>Base Keywords</title>
- <para>There are a few historic keywords that are hardcoded, and
+ <para>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.</para>
+ <sect3 xml:id="plist-keywords-base-empty">
+ <title><literal>@</literal>
+ [<replaceable>file</replaceable>]</title>
+
+ <para>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
+ <literal>games</literal> and add the setgid bit, add:</para>
+
+ <programlisting>@(,games,2755) sbin/daemon</programlisting>
+ </sect3>
+
<sect3 xml:id="plist-keywords-base-cwd">
<title><literal>@cwd</literal>
[<replaceable>directory</replaceable>]</title>
@@ -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).</para>
+
+ <important>
+ <para>This must be a numeric mode, like
+ <literal>644</literal>, <literal>4755</literal>, or
+ <literal>600</literal>. It cannnot be a relative mode
+ like <literal>u+s</literal>.</para>
+ </important>
</sect3>
<sect3 xml:id="plist-keywords-base-owner">
@@ -526,22 +558,37 @@ etc/orbit.conf-dist
<para>This line is ignored when packing.</para>
</sect3>
+ <sect3 xml:id="plist-keywords-base-dir">
+ <title><literal>@dir</literal>
+ <replaceable>directory</replaceable></title>
+
+ <para>Declare directory name. By default, directories created
+ under <varname>PREFIX</varname> by a package installation
+ are automatically removed. Use this when an empty directory
+ under <varname>PREFIX</varname> needs to be created, or when
+ the directory needs to have non default owner, group, or
+ mode. Directories outside of <varname>PREFIX</varname> need
+ to be registered. For example,
+ <filename>/var/db/${PORTNAME}</filename> needs to have a
+ <literal>@dir</literal> entry whereas
+ <filename>${PREFIX}/share/${PORTNAME}</filename> does not if
+ it contains files or uses the default owner, group, and
+ mode.</para>
+ </sect3>
+
<sect3 xml:id="plist-keywords-base-dirrm">
<title><literal>@dirrm</literal>
- <replaceable>directory</replaceable></title>
+ <replaceable>directory</replaceable> (Deprecated)</title>
<para>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.</para>
+ By default, directories created under
+ <varname>PREFIX</varname> by a package installation are
+ deleted when the package is deinstalled.</para>
</sect3>
<sect3 xml:id="plist-keywords-base-dirrmtry">
<title><literal>@dirrmtry</literal>
- <replaceable>directory</replaceable></title>
+ <replaceable>directory</replaceable> (Deprecated)</title>
<para>Declare directory name to be removed, as for
<literal>@dirrm</literal>, but does not issue a warning if
@@ -555,9 +602,9 @@ etc/orbit.conf-dist
<para>Package list files can be extended by keywords that are
defined in the <filename
class="directory">${PORTSDIR}/Keywords</filename> directory.
- The settings for each keyword lives in a
- <acronym>YAML</acronym> file named
- <filename><replaceable>keyword</replaceable>.yaml</filename>.
+ The settings for each keyword are stored in a
+ <acronym>UCL</acronym> file named
+ <filename><replaceable>keyword</replaceable>.ucl</filename>.
The file must contain at least one of the next
sections:</para>
@@ -595,11 +642,20 @@ etc/orbit.conf-dist
</varlistentry>
<varlistentry>
+ <term><literal>dir</literal></term>
+
+ <listitem>
+ <para>Register a directory to be created on
+ install and removed on deinstall.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><literal>dirrm</literal></term>
<listitem>
<para>Register a directory to be deleted on
- deinstall.</para>
+ deinstall. Deprecated.</para>
</listitem>
</varlistentry>
@@ -608,7 +664,7 @@ etc/orbit.conf-dist
<listitem>
<para>Register a directory to try and deleted on
- deinstall.</para>
+ deinstall. Deprecated.</para>
</listitem>
</varlistentry>
@@ -701,13 +757,14 @@ etc/orbit.conf-dist
removed when deinstalling the package.</para>
<programlisting>actions: [dirrmtry]
-post-deinstall: |
- echo "Directory %D/%@ removed."</programlisting>
+post-deinstall: <<EOD
+ echo "Directory %D/%@ removed."
+EOD</programlisting>
</example>
<example xml:id="plist-keywords-sample-example">
<title>Real Life Example, How the <literal>@sample</literal>
- Could be Implemented</title>
+ is Implemented</title>
<para>This keyword does three things, it adds the
<replaceable>filename</replaceable> passed as an argument to
@@ -719,7 +776,7 @@ post-deinstall: |
configuration file if it has not been modified.</para>
<programlisting>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</programlisting>
+ else
+ echo "You may need to manually remove ${target_file} if it's no longer needed."
+ fi
+EOD</programlisting>
</example>
</sect2>
</sect1>
More information about the svn-doc-head
mailing list