Date: Sun, 20 Apr 2014 09:50:20 +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: r44611 - head/en_US.ISO8859-1/books/porters-handbook/plist Message-ID: <201404200950.s3K9oLRY055480@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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 <link linkend="porting-shlibs">shared libraries</link> section.</para> </sect1> + + <sect1 xml:id="plist-keywords"> + <title>Expanding Package List with Keywords</title> + + <sect2 xml:id="plist-keywords-fc"> + <title><literal>@fc</literal> + <replaceable>directory</replaceable></title> + + <para>Add a <literal>@dirrmtry</literal> entry for the + directory passed as an argument, and run <command>fc-cache + -s</command> on that directory after installation and + deinstallation.</para> + </sect2> + + <sect2 xml:id="plist-keywords-fcfontsdir"> + <title><literal>@fcfontsdir</literal> + <replaceable>directory</replaceable></title> + + <para>Add a <literal>@dirrmtry</literal> entry for the + directory passed as an argument, and run <command>fc-cache + -s</command>, <command>mkfontscale</command> and + <command>mkfontdir</command> on that directory after + installation and deinstallation. Additionally, on + deinstallation, it removes the + <filename>fonts.scale</filename> and + <filename>fonts.dir</filename> cache files if they are + empty.</para> + </sect2> + + <sect2 xml:id="plist-keywords-fontsdir"> + <title><literal>@fontsdir</literal> + <replaceable>directory</replaceable></title> + + <para>Add a <literal>@dirrmtry</literal> entry for the + directory passed as an argument, and run + <command>mkfontscale</command> and + <command>mkfontdir</command> on that directory after + installation and deinstallation. Additionally, on + deinstallation, it removes the + <filename>fonts.scale</filename> and + <filename>fonts.dir</filename> cache files if they are + empty.</para> + </sect2> + + <sect2 xml:id="plist-keywords-info"> + <title><literal>@info</literal> + <replaceable>file</replaceable></title> + + <para>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.</para> + </sect2> + + <sect2 xml:id="plist-keywords-sample"> + <title><literal>@sample</literal> + <replaceable>file</replaceable></title> + + <para>Add the file passed as argument to the plist.</para> + + <para>On installation, check for a <quote>real</quote> file with + just the base name (the name without the + <filename>.sample</filename> 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 <xref linkend="plist-config"/> for more + information.</para> + </sect2> + + <sect2 xml:id="plist-keywords-base"> + <title>Base Keywords</title> + + <para>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.</para> + + <sect3 xml:id="plist-keywords-base-cwd"> + <title><literal>@cwd</literal> + [<replaceable>directory</replaceable>]</title> + + <para>Set the internal directory pointer to point to + directory. All subsequent filenames are assumed relative to + this directory.</para> + </sect3> + + <sect3 xml:id="plist-keywords-base-exec"> + <title><literal>@exec</literal> + <replaceable>command</replaceable> (deprecated)</title> + + <para>Execute <replaceable>command</replaceable> 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 + <literal>@cwd</literal> is set to <filename + class="directory">/usr/local</filename> and the last + extracted file was <filename>bin/emacs</filename>.</para> + + <variablelist> + <varlistentry> + <term><literal>%F</literal></term> + + <listitem> + <para>Expand to the last filename extracted (as + specified). In the example case + <filename>bin/emacs</filename>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>%D</literal></term> + <listitem> + <para>Expand to the current directory prefix, as set + with <literal>@cwd</literal>. In the example case + <filename + class="directory">/usr/local</filename>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>%B</literal></term> + + <listitem> + <para>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 <filename + class="directory">/usr/local/bin</filename>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>%f</literal></term> + + <listitem> + <para>Expand to the filename part of the fully qualified + name, or the converse of <literal>%B</literal>. In + the example case, + <filename>emacs</filename>.</para> + </listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 xml:id="plist-keywords-base-unexec"> + <title><literal>@unexec</literal> + <replaceable>command</replaceable> (deprecated)</title> + + <para>Execute <replaceable>command</replaceable> as part of + the deinstallation process. Expansion of special + <literal>%</literal> sequences is the same as for + <literal>@exec</literal>. This command is not executed + during the package add, as <literal>@exec</literal> 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).</para> + </sect3> + + <sect3 xml:id="plist-keywords-base-mode"> + <title><literal>@mode</literal> + <replaceable>mode</replaceable></title> + + <para>Set default permission for all subsequently extracted + files to <replaceable>mode</replaceable>. 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).</para> + </sect3> + + <sect3 xml:id="plist-keywords-base-owner"> + <title><literal>@owner</literal> + <replaceable>user</replaceable></title> + + <para>Set default ownership for all subsequent files to + <replaceable>user</replaceable>. Use without an argument to + set back to default ownership (<systemitem + class="username">root</systemitem>).</para> + </sect3> + + <sect3 xml:id="plist-keywords-base-group"> + <title><literal>@group</literal> + <replaceable>group</replaceable></title> + + <para>Set default group ownership for all subsequent files to + <replaceable>group</replaceable>. Use without an arg to set + back to default group ownership (<systemitem + class="groupname">wheel</systemitem>).</para> + </sect3> + + <sect3 xml:id="plist-keywords-base-comment"> + <title><literal>@comment</literal> + <replaceable>string</replaceable></title> + + <para>This line is ignored when packing.</para> + </sect3> + + <sect3 xml:id="plist-keywords-base-dirrm"> + <title><literal>@dirrm</literal> + <replaceable>directory</replaceable></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 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.</para> + </sect3> + + <sect3 xml:id="plist-keywords-base-dirrmtry"> + <title><literal>@dirrmtry</literal> + <replaceable>directory</replaceable></title> + + <para>Declare directory name to be removed, as for + <literal>@dirrm</literal>, but does not issue a warning if + the directory cannot be removed.</para> + </sect3> + </sect2> + + <sect2> + <title>Creating Your Own Keyword</title> + + <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 file must contain at least one of the following + sections:</para> + + <variablelist> + <varlistentry xml:id="plist-keywords-attributes"> + <term><literal>attributes</literal></term> + + <listitem> + <para>Changes the owner, group, or mode used by the + keyword. Contains an associative array where the + possible keys are <literal>owner</literal>, + <literal>group</literal>, and <literal>mode</literal>. + The values are, respectively, a user name, a group name, + and a file mode. For example:</para> + + <programlisting>attributes: { owner: "games", group: "games", mode: 0555 }</programlisting> + </listitem> + </varlistentry> + + <varlistentry xml:id="plist-keywords-action"> + <term><literal>action</literal></term> + + <listitem> + <para>Defines what happens to the keyword's parameter. + Contains an array where the possible values are:</para> + + <variablelist> + <varlistentry> + <term><literal>setprefix</literal></term> + + <listitem> + <para>Set the prefix for the next plist + entries.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>dirrm</literal></term> + + <listitem> + <para>Register a directory to be deleted on + deinstall.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>dirrmtry</literal></term> + + <listitem> + <para>Register a directory to try and deleted on + deinstall.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>file</literal></term> + + <listitem> + <para>Register a file.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>setmode</literal></term> + + <listitem> + <para>Set the mode for the next plist + entries.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>setowner</literal></term> + + <listitem> + <para>Set the owner for the next plist + entries.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>setgroup</literal></term> + + <listitem> + <para>Set the group for the next plist + entries.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>comment</literal></term> + + <listitem> + <para>Does not do anything, equivalent to not + entering an <literal>action</literal> + section.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ignore_next</literal></term> + + <listitem> + <para>Ignore the next entry in the plist.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry xml:id="plist-keywords-pre-post"> + <term><literal>pre-install</literal></term> + <term><literal>post-install</literal></term> + <term><literal>pre-deinstall</literal></term> + <term><literal>post-deinstall</literal></term> + <term><literal>pre-upgrade</literal></term> + <term><literal>post-upgrade</literal></term> + + <listitem> + <para>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 + <literal>@exec</literal> + <literal>%<replaceable>foo</replaceable></literal> + placeholders described in <xref + linkend="plist-keywords-base-exec"/>, there is a new + one, <literal>%@</literal>, which represents the + argument of the keyword.</para> + </listitem> + </varlistentry> + </variablelist> + + <example xml:id="plist-keywords-fc-example"> + <title>Example of a <literal>@dirrmtryecho</literal> + Keyword</title> + + <para>This keyword does two things, it adds a + <literal>@dirrmtry + <replaceable>directory</replaceable></literal> line to the + packing list, and echoes the fact that the directory is + removed when deinstalling the package.</para> + + <programlisting>actions: [dirrmtry] +post-deinstall: | + echo "Directory %D/%@ removed."</programlisting> + </example> + + <example xml:id="plist-keywords-sample-example"> + <title>Real Life Example, How the <literal>@sample</literal> + Could be Implemented</title> + + <para>This keyword does three things, it adds the + <replaceable>filename</replaceable> passed as an argument to + <literal>@sample</literal> to the packing list, it adds to + the <literal>post-install</literal> script instructions to + copy the sample to the actual configuration file if it does + not already exist, and it adds to the + <literal>post-deinstall</literal> instructions to remove the + configuration file if it has not been modified.</para> + + <programlisting>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</programlisting> + </example> + </sect2> + </sect1> </chapter>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201404200950.s3K9oLRY055480>