Re: Bug#582109: debian-policy: document triggers where appropriate
Hi Charles,
On Fri, 15 Mar 2013, Charles Plessy wrote:
> I am still seeking comments for the attached patch, that describes Dpkg
> triggers.
Here are my comments. There's quite a bit of work left.
> >From 6a7fd0e49cb8dbd025771feb95c2dcafb408c1b8 Mon Sep 17 00:00:00 2001
> From: Charles Plessy <plessy@debian.org>
> Date: Sat, 2 Mar 2013 22:48:04 +0900
> Subject: [PATCH] Document dpkg triggers.
>
> Closes: #582109.
> ---
> policy.sgml | 275 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--
> 1 file changed, 268 insertions(+), 7 deletions(-)
>
> diff --git a/policy.sgml b/policy.sgml
> index a41bc1f..c6e1a9e 100644
> --- a/policy.sgml
> +++ b/policy.sgml
> @@ -900,9 +900,12 @@ zope.
> the package. Other control information files include
> the <qref id="sharedlibs-symbols"><file>symbols</file> file</qref>
> or <qref id="sharedlibs-shlibdeps"><file>shlibs</file> file</qref>
> - used to store shared library dependency information and
> + used to store shared library dependency information,
> the <file>conffiles</file> file that lists the package's
> - configuration files (described in <ref id="config-files">).
> + configuration files (described in <ref id="config-files">), and the
> + file <file>triggers</file> that lists the
"the <file>triggers</file> file"
(invert two words)
> + <qref id="dpkg-triggers">triggers</qref> that the package is interested
> + in.
the triggers file (see man deb-triggers) can contain "interest" directives
but also "activate" ones. So this needs to be reworded.
For example “the triggers file wich defines the package's interaction with
dpkg's trigger system”
> + Dpkg defines the folowing states for the packages.
> + <taglist>
> + <tag>Not-Installed</tag>
I would use the precise states listed in dpkg(1), i.e. entirely in
lowercase. (same for all the states)
> @@ -4141,6 +4189,26 @@ Checksums-Sha256:
> from the package dependencies are not available is often the
> best approach.
> </item>
> +
> + <tag><var>postinst</var> <tt>triggered</tt>
> + "<var>trigger-name</var> <var>trigger-name</var> ..."</tag>
> + <item>
> + Process one or more <qref id="dpkg-triggers">triggers</qref> that
> + this package is <em>interested</em> in. In case of failure the
> + package's state becomes <tt>config-failed</tt>, so that the trigger
> + processing will not be attempted again until explicitly
> + requested<footnote>
I don't think that it's marked "config-failed" to not retry the trigger
processing. It's just that we need an error state and that config-failed
can be reused for this purpose precisely because anything done by trigger
processing is supposed to also be done during normal configuration (so it
is effectively retried on next configure).
“In case of failure the package's state becomes <tt>config-failed</tt>,
and the task associated to the trigger processing will be completed by
the <tt>postinst configure</tt> during the next package's configuration.”
> + When an interested package has more than one trigger and wants
> + to process them differently, the list of triggers can be can be
s/can be can be/can be/
> @@ -4694,6 +4762,198 @@ fi
>
> </p>
> </sect>
> +
> + <sect id="dpkg-triggers">
> + <heading>Dpkg triggers</heading>
> +
> + <p>
> + A <prgn>dpkg</prgn> trigger is a facility that allows events caused
> + by the installation, upgrade or removal of one package, and of
> + <em>interest</em> to another package, to be recorded and
> + aggregated, and processed later by the interested package. This
> + feature simplifies various registration and system-update tasks and
> + reduces duplication of processing.
> + <p>
“<prgn>dpkg</prgn> triggers allows packages to monitor events caused by
the installation, upgrade or removal of packages. Monitoring packages are
said to be <em>interested</em> in some triggers. On the other side,
triggers must be <em>activated</em> to record the event notification on
the <em>interested package</em>. The latter is then said to have
<em>pending triggers</em> and the <em>activating</em> package (if any) is
said to await the processing of the trigger.
Thanks to this feature, it's easy to avoid duplication of processing logic
among packages by implementing it in one package and making sure that all
other packages rely on triggers to execute the wanted code.”
> + <p>
> + Each trigger is named, and at any time zero or more packages may be
> + <em>interested</em> in it. Packages declare their interest by
> + including a <file>triggers</file> file in their control archive.
The triggers file can contain "activate" directives too so I'd suggest
to be more explicit:
“For a package to declare its interest in a trigger, it must include one of
the <tt>interest</tt> directives in the <file>triggers</file> file in its
control archive.”
Then start a new paragraph describing the syntax of the triggers
file.
> + This file contains one directive per line. Leading and trailing
Useless leading whitespaces on this line.
> + whitespace, everything after the first hash character (<tt>#</tt>)
whitespaces ? (with "s")
> + on any line, and empty lines are ignored. The following directives
> + are supported.
> + <taglist>
> + <tag><tt>interest</tt> <var>trigger-name</var></tag>
> + <tag><tt>interest-noawait</tt> <var>trigger-name</var></tag>
> + <item>
> + Specifies that the package is interested in the named trigger.
> + The <em>noawait</em> variant does not put the triggering packages
> + in "Triggers-Awaited" state, and does not add the
> + interested package to the <tt>Triggers-Awaited</tt> list of the
> + triggering package.
> + </item>
> +
> + <tag><tt>activate</tt> <var>trigger-name</var></tag>
> + <tag><tt>activate-noawait</tt> <var>trigger-name</var></tag>
> + <item>
> + Specifies that changes to this package's state will activate the
> + named trigger. The <em>noawait</em> variant does not put the
> + triggering packages in "Triggers-Awaited" state, and does
> + not add the interested package to the <tt>Triggers-Awaited</tt>
> + list of the triggering package.
> + </item>
> + </taglist>
> + </p>
I'm not sure that you need to explain each time that the interested
package doesn't get added to the Triggers-Awaited field. This is just
an implementation detail of the triggers-awaited state. When we put
something in triggers-awaited, we must remember which package
needs to have its triggers processed. And we already explain it later.
> + <p>
> + There currently two kinds of triggers.
+are
> + <taglist>
> + <tag>Explicit triggers</tag>
> + <item>
> + These can be activated by any program by running
> + <prgn>dpkg-trigger</prgn> (at any time, but ideally from a
> + maintainer script.
missing parenthesis ")".
And you must indicate that explicit triggers can also be activated by
state changes of packages having an "activate" directive in their
triggers control file.
> + </item>
> +
> + <tag>File triggers</tag>
> + <item>
> + These are activated automatically by <prgn>dpkg</prgn> when a
> + matching file or directory is created, upgraded or deleted as
> + part of a package's unpacking or removal. They may also be
> + explicitly activated by running <prgn>dpkg-trigger</prgn>.
> + Trigger activation due to a particular file should not generally
> + modify that file again. If there are directory symlinks which
> + result in packages referring to files by different names, then to
> + be sure of activation all of the paths which might be included in
> + packages should be listed. The path specified by the interested
> + package is matched against the path included in the triggering
> + package, not against the true name of the file as installed.
> + Only textually identical filenames (or filenames where the
> + interest is a directory prefix of the installed file) are
> + guaranteed to match.
> + </item>
This whole paragraph about symlinks is not at its place here. Or if you
want to keep it here, put it in a footnote so that it doesn't distract the
high level overview that this section is about.
> + <p>
> + Trigger names are composed of US-ASCII characters excluding
> + control characters and space (i.e., characters in the range 33-126,
> + inclusive). The names of file triggers is an absolute path to
The name of a file trigger is...
> + a file or a directory. The names of Explicit triggers have the same
> + syntax as package names, but should not by identical to a package
s/by/be/
> + <p>
> + When a configured package activates a trigger, its state becomes
> + "Triggers-Awaited" instead of "Installed". For this
> + package, <prgn>dpkg</prgn> keeps a list, <tt>Triggers-Awaited</tt>
> + of interested packages whose trigger processing is awaited. Every
…keeps a list of interested packages whose trigger processing is awaited
in the <tt>Triggers-Awaited</tt> field.
> + package in this list either has a nonempty list of pending triggers,
> + or is in <tt>config-failed</tt> or worse. When a package in the
> + state "Triggers-Pending" becomes "Installed",
> + "Config-Files" or "Not-Installed", its entry is
> + removed from the <tt>Triggers-Awaited</tt> lists of other packages.
> + </p>
> +
> + <p>
> + When a trigger is activated, the state of every interested package
> + becomes "Triggers-Pending". For each package,
> + <prgn>dpkg</prgn> keeps a list, <tt>Triggers-Pending</tt>, of
> + triggers whose processing is pending.
…keeps a list of triggers whose processing is pending in the
<tt>Triggers-Pending</tt> field.
Also you mix states written as <tt>config-failed</tt> with states
written as "Triggers-Pending". I suggest you standardize on the former.
> + <p>
> + Triggers are processed by running the intersted packages'
interested
> + <tt>postinst</tt> script with the <tt>triggered</tt> parameter (see
> + <ref id="mscriptsinstact">). This will be attempted for each
> + relevant package at the end of each <prgn>dpkg</prgn> run; so,
I would add "(unless --no-triggers has been used).".
> + normally, in the same dpkg run as the event which made the package go
> + to <prgn>triggers-pending</prgn>.
s/made the package go to/marked the package as/
> + If the package is not in state "Installed",
> + "Triggers-Pending" or "Triggers-Awaited" then pending
> + triggers are not accumulated. However, if such a package (between
> + "Half-Installed" and <tt>config-failed</tt> inclusive)
> + declares some trigger interests then the triggering packages will
> + await their configuration (which implies completion of any necessary
> + trigger processing) or removal.
> + </p>
> + </sect>
This whole section is made of many paragraphs grabbed from
various parts of /usr/share/doc/dpkg-dev/triggers.txt.gz and
really lacks a bit of structure. You should try to add some sub-sections
and group stuff by topics.
> @@ -4716,8 +4976,8 @@ fi
> dependencies on other packages, the package names listed may
> also include lists of alternative package names, separated
> by vertical bar (pipe) symbols <tt>|</tt>. In such a case,
> - if any one of the alternative packages is installed, that
> - part of the dependency is considered to be satisfied.
> + if any one of the alternative packages is installed or has pending
> + triggers, that part of the dependency is considered to be satisfied.
“or is in <tt>triggers-pending</tt> state,”, no ?
> @@ -4978,7 +5238,8 @@ Build-Depends: foo [linux-any], bar [any-i386], baz [!linux-any]
> <prgn>postinst</prgn> or <prgn>prerm</prgn> scripts
> require the depended-on package to be unpacked or
> configured in order to run. In the case of <tt>postinst
> - configure</tt>, the depended-on packages will be unpacked
> + configure</tt> and <tt>postinst triggers</tt>,
s/postinst triggers/postinst triggered/
> + the depended-on packages will be unpacked
> and configured first. (If both packages are involved in a
> dependency loop, this might not work as expected; see the
> explanation a few paragraphs back.) In the case
> @@ -8097,8 +8358,8 @@ Reloading <var>description</var> configuration...done.
> <p>
> The <package>mime-support</package> package provides the
> <prgn>update-mime</prgn> program, which integrates these
> - registrations in the <file>/etc/mailcap</file> file, using dpkg
> - triggers<footnote>
> + registrations in the <file>/etc/mailcap</file> file, using
> + <qref id="dpkg-triggers">dpkg triggers</qref><footnote>
> Creating, modifying or removing a file in
> <file>/usr/lib/mime/packages/</file> using maintainer scripts will
> not activate the trigger. In that case, it can be done by calling
Cheers,
--
Raphaël Hertzog ◈ Debian Developer
Get the Debian Administrator's Handbook:
→ http://debian-handbook.info/get/
Reply to: