Date: Mon, 22 Sep 2014 16:15:38 +0000 (UTC) From: Mathieu Arnold <mat@FreeBSD.org> 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 Message-ID: <201409221615.s8MGFctl076542@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201409221615.s8MGFctl076542>