Add a section about plist keywords.
Reviewed by: wblock, bcr Sponsored by: Absolight
This commit is contained in:
Mathieu Arnold
parent
e48fc921b4
commit
8a25b71e28
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=44611
1 changed files with 405 additions and 0 deletions
|
|
@ -304,4 +304,409 @@ etc/orbit.conf-dist
|
||||||
the <link linkend="porting-shlibs">shared libraries</link>
|
the <link linkend="porting-shlibs">shared libraries</link>
|
||||||
section.</para>
|
section.</para>
|
||||||
</sect1>
|
</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>
|
</chapter>
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue