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 <ple...@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/ -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org