Adding upstream version 1.22.4.upstream/1.22.4

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

4 files changed, 1099 insertions, 0 deletions

diff --git a/doc/spec/frontend-api.txt b/doc/spec/frontend-api.txt
new file mode 100644
index 0000000..5f25741
--- /dev/null
+++ b/doc/spec/frontend-api.txt
@@ -0,0 +1,30 @@
+Frontend Interfaces
+===================
+
+Status: recommendation, stable
+
+
+Overview
+--------
+
+This file will try to document some of the interfaces that dpkg makes
+available to frontends or that expects them to use, which are currently
+not covered by any other type of documentation.
+
+
+Database Locking
+----------------
+
+Any frontend needing to make sure no write operation is currently happening,
+and no other frontend is running should first acquire the frontend lock at
+«<admindir>/lock-frontend», and then acquire the dpkg database lock at
+«<admindir>/lock». When the frontend invokes dpkg, it should set the
+environment variable DPKG_FRONTEND_LOCKED (to prevent dpkg from acquiring
+the frontend lock), and then release the dpkg database lock, which will be
+acquired by dpkg itself. This way no other frontend following this protocol
+can race to perform operations while another one has one in progress.
+
+These locks must be file record locks (i.e. fcntl(2) advisory locking), and
+the whole file should be locked, as that's the most portable way to perform
+this operation; this can be achieved by using start=0, len=0 and
+whence=SEEK_SET.
diff --git a/doc/spec/protected-field.txt b/doc/spec/protected-field.txt
new file mode 100644
index 0000000..90e2441
--- /dev/null
+++ b/doc/spec/protected-field.txt
@@ -0,0 +1,74 @@
+Support for a Protected field
+=============================
+
+Status: draft, experimental
+URL: https://wiki.debian.org/Teams/Dpkg/Spec/ProtectedField
+
+Summary
+-------
+
+The goal of the following proposal is to standardize a field to split
+part of the «Essential» packages, and add support for it in the package
+management stack. There is currently an Important field, that has the
+correct semantics but has a very confusing name and is only supported
+by apt anyway, so this new field would phase out that one.
+
+Background
+----------
+
+Our current use of «Essential: yes» is confused, and it includes several
+conflated things, some of which would be worth splitting up.
+
+We use «Essential» to:
+
+  * Denote that a package must be always installed and cannot be
+    removed (easily), because it is essential to the system in some way.
+  * Denote that a package must be functional even when just unpacked
+    (after having been configured once / fully bootstrapped).
+  * Mark auto-vivification, by making front-ends either complain very
+    loudly or reinstalling these packages when missing.
+  * Minimize dependency loops, by making these dependencies implicit.
+
+One problem is that the first point above includes being essential for
+the packaging system during upgrades/installation, for the operation
+of the system in general, and for the operation of the system during
+boot.
+
+The latter is not always necessary though, for example within a chroot,
+or some types of containers. There has been work on trying to trim down
+the pseudo-essential set as can be seen from:
+
+  <https://wiki.debian.org/Proposals/EssentialOnDiet>
+  <https://wiki.debian.org/BusterPriorityRequalification>
+
+And several of these switches made use of a pre-existing field called
+«Important», defined and currently only supported by apt, which had the
+following properties:
+
+  * These packages are not required to be installed.
+  * They do not have to be usable while unconfigured.
+  * Dependencies need to be spelled out.
+
+Proposal
+--------
+
+The proposal would be to add support for a new Protected field, with the
+following properties:
+
+  * Protected packages should not be trivial to remove (require a force
+    option for example, like «Essential»).
+  * Protected packages should not be required to be installed (i.e. once
+    removed they should not be automatically brought back by a front-end,
+    unlike «Essential»).
+  * Protected packages must be depended on explicitly (unlike «Essential»).
+  * Protected packages must be functional even when unpacked (think of
+    a boot loader or an init system; like «Essential»). [XXX: This one is
+    not entirely clear and might not match reality anyway, for example kernels,
+    which might require building an initramfs, etc.]
+
+This would make it possible to phase out the current «Important» field
+usage (because it has a name too confusing relative to the «Priority»
+value; and has small tooling coverage) and the usage of «Essential» for
+at least packages involved in the boot process, and perhaps also for
+packages essential for operation of the system in general (in contrast
+to packages required for the packaging system).
diff --git a/doc/spec/rootless-builds.txt b/doc/spec/rootless-builds.txt
new file mode 100644
index 0000000..5a5af83
--- /dev/null
+++ b/doc/spec/rootless-builds.txt
@@ -0,0 +1,177 @@
+Supporting rootless builds
+==========================
+
+Status: recommendation, stable
+Version: 1.0
+
+Background
+----------
+
+Traditionally, Debian packages have required (fake)root privileges for some
+of the "debian/rules" targets. This has required also a split between build
+and binary targets; making the builds slower, due to the increased amount
+of invocations of "debian/rules" and the overhead of using fakeroot(1) or
+equivalent fake environments, or less secure due to the increased dangers
+of running under real root via sudo or equivalent.
+
+On this document when talking about "(fake)root" privileges, it will refer
+to any mechanism, supported by the dpkg-buildpackage "-r/--root-command"
+option, that can provide either a real or faked root user environment.
+
+Specification
+-------------
+
+We add a new field to the "Source" stanza of debian/control:
+
+  Rules-Requires-Root: no | binary-targets | <implementations-keywords>
+
+The case sensitive values are defined as:
+
+ * If "no", then "debian/rules binary" will not require root at all (not even
+   fakeroot). This is the default in dpkg-build-api level >= 1.
+   - If the "no" keyword is used, it MUST be the only keyword in that field
+     and MUST appear exactly once.
+
+ * If "binary-targets", then "debian/rules binary" (etc.) must always be run
+   under (fake)root. This is the status quo, default in dpkg-build-api level 0.
+
+ * <implementations-keywords> will be a space separated list of keywords which
+   define when root is required.
+
+   - Keywords consists of <namespace>/<cases>. The "namespace" part cannot
+     contain "/" or whitespace. The "cases" part cannot contain whitespace.
+     Furthermore, both parts MUST consist entirely of printable ASCII
+     characters.
+
+   - Each tool/package will define a namespace named after itself and provide
+     a number of cases where (fake)root is required.
+     (See also "Implementation provided keywords".)
+
+   - When "Rules-Requires-Root" is set to <implementations-keywords>, the
+     builder (i.e. whatever is executing debian/rules) will expose an
+     interface that is used to run a command under (fake)root via the
+     "Gain Root API". If the builder cannot provide such a command, it
+     MUST behave like "Rules-Requires-Root" was set to "binary-targets",
+     i.e. run "debian/rules binary" under (fake)root.
+
+When the builder supports this specification, it MUST notify this fact to
+the rules file via the "DEB_RULES_REQUIRES_ROOT" environment variable, with
+the value it has obtained from the Rules-Requires-Root field or some builder
+specific override mechanism, which will denote the level of support the
+builder has chosen to commit to take effect during the build. When set,
+it MUST be a valid value for the Rules-Requires-Root field. If unset,
+the build system SHOULD assume that the builder does not recognize the
+Rules-Requires-Root field at all.
+
+It is always permissible for a builder to ignore this field and fall back to
+running the binary targets under (fake)root. This is to ensure backwards
+compatibility when builds are performed by legacy builders or older versions
+of the tooling.
+
+Tools called from the rules file MUST cope gracefully with being called under
+(fake)root even when Rules-Requires-Root is set to a value that implies they
+should not be (e.g. "no"). However, they MUST NOT attempt to run processes
+under (fake)root when run as a regular user when Rules-Requires-Root does
+not list any keywords they respond to.
+
+Tools MUST gracefully ignore valid unknown keywords outside their namespace.
+They MAY warn about unknown keywords inside their namespace.
+
+The value of this field MUST NOT change the content of the package in any
+way. Notably, packages that are bit-for-bit reproducible MUST still provide
+bit-for-bit identical results even when the field is ignored.
+
+Implementation provided keywords
+--------------------------------
+
+Keywords provided by various implementations:
+
+ * dpkg/target-subcommand: When the package needs to run a given command
+   under (fake)root within the "debian/rules" files directly, this MUST be
+   declared via this keyword.
+
+ * dpkg/target/<target-name>: When a specific "debian/rules" unofficial
+   target (none of the root-requiring "binary-indep", "binary-arch", "binary",
+   "clean", nor the non-root-requiring "build-indep", "build-arch", "build")
+   needs to be run under (fake)root, this MUST be declared via this dynamic
+   keyword, where <target-name> is the name of the "debian/rules" target.
+
+ * debhelper/upstream-make-install: The dh_auto_install command will run
+   the "install" target from the upstream's Makefile under (fake)root (for
+   the "makefile" build system or one derived from it).
+
+Gain Root API
+-------------
+
+The builder will provide a command to promote a given command to (fake)root
+by exposing it in the environment variable "DEB_GAIN_ROOT_CMD". Tools that
+need this promotion will then use it like the following:
+
+    $DEB_GAIN_ROOT_CMD cmd-that-needs-root ...
+
+This command is subject to the same requirements as the "gain-root-command"
+that dpkg-buildpackage accepts via its "-r/--root-command" option, which
+means that it can contain space-separated parameters. If dpkg-buildpackage is
+called with "-r/--root-command", then dpkg-buildpackage shall use that value
+as the value for "DEB_GAIN_ROOT_CMD". The command SHOULD preserve all the
+environment variables, unmodified.
+
+The variable SHOULD only be provided when there is a need for it. Notably
+when "Rules-Requires-Root" is either "no" or "binary-targets" the variable
+SHOULD NOT be defined.
+
+(The "DEB_GAIN_ROOT_CMD" variable used to be named "DPKG_GAIN_ROOT_CMD"
+starting with dpkg 1.19.0 and before dpkg 1.19.1 when this specification
+got released as stable. The old name MUST not be used.)
+
+Common cases
+------------
+
+ * Upstream installation insists on "sudo make install"-like behavior.
+   => Use dpkg/target-subcommand or debhelper/upstream-make-install.
+
+ * Files shipped in the package must be owned by another user than root.
+   => Not covered; use "binary-targets" for now until dpkg+debhelper
+      provides the required interface.
+
+Prototyping/preparation
+=======================
+
+dpkg side
+---------
+
+dpkg-deb --build provides the --root-owner-group option so that dh_builddeb
+or direct calls can control the owner/group file values w/o requiring
+(fake)root.
+
+dpkg-buildpackage must export DEB_GAIN_ROOT_CMD when necessary (for
+prototyping, doing this unconditionally would be fine).
+
+
+debhelper side
+--------------
+
+When the field is present:
+
+ * dh_testroot will behave as usual when Rules-Requires-Root is not present
+   or set to "binary-targets".
+
+ * dh_testroot will be a no-op when Rules-Requires-Root is set to "no".
+
+ * Otherwise, dh_testroot will either verify that it is run under (fake)root
+   (as usual) OR assert that DEB_GAIN_ROOT_CMD is defined.
+
+ * debhelper build systems will be patched to check for the
+   "debhelper/upstream-make-install" keyword and use the "Gain Root API"
+   accordingly.
+
+ * All other (src:)debhelper commands will skip their calls to chown
+   (currently they just reset them to "0:0" anyway).
+
+With the above, a default "dh $@" will no longer require (fake)root when
+built (and Rules-Requires-Root is "no").
+
+Prototyping:
+
+ * During prototyping, dh_builddeb can wrap the dpkg-deb --build call with
+   fakeroot (when not already root).
diff --git a/doc/spec/triggers.txt b/doc/spec/triggers.txt
new file mode 100644
index 0000000..64f4232
--- /dev/null
+++ b/doc/spec/triggers.txt
@@ -0,0 +1,818 @@
+Triggers
+========
+
+Status: recommendation, stable
+
+Introduction
+------------
+
+A dpkg trigger is a facility that allows events caused by one package
+but of interest 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.
+
+(NB: Triggers are intended for events that occur during package
+installation, not events that occur in general operation.)
+
+
+Concepts
+--------
+
+Each trigger is named, and at any time zero or more packages may be
+interested in it.
+
+We currently envisage three kinds of triggers:
+ * Explicit triggers.  These can be activated by any program
+   by running dpkg-trigger (at any time, but ideally from a maintainer
+   script).
+ * File triggers.  These are activated automatically by dpkg
+   when a matching file is installed, upgraded or removed as part
+   of a package.  They may also be explicitly activated by running
+   dpkg-trigger.
+ * Future kinds of special triggers, which are activated by magic code
+   in dpkg itself.  Currently none are defined besides file triggers.
+
+A trigger is always activated by a particular package.
+
+Trigger names contain only printing 7-bit ASCII characters (no
+whitespace).  Each trigger kind has a distinct subset of the trigger
+name space so that the kind can be determined from the name.  After we
+run out of straightforward syntaxes, we will use <kind>:<details>.
+
+When a trigger is activated, it becomes pending for every package
+which is interested in the trigger at that time.  Each package has a
+list of zero or more pending triggers.  Repeated activation of the
+same trigger has no additional effect.  Note that in general a trigger
+will not be processed immediately when it is activated; processing is
+deferred until it is convenient (as described below).
+
+At a trigger activation, the interested packages(s) are added to the
+triggering package's list of triggers-awaited packages (unless the
+trigger has been configured to not require it); the triggering
+package is said to await the trigger processing.
+
+A package which has pending triggers, or which awaits triggers, is not
+considered properly installed.  There are two new dpkg status values,
+‘triggers-pending’ and ‘triggers-awaited’, which lie between
+‘config-failed’ and ‘installed’.
+
+
+Details - Overview table
+------------------------
+
+  Status      Pending   Awaited   Satisfies  Remedy
+              triggers  triggers  Depends
+
+  unpacked    never      maybe    No    postinst configure
+  c.-failed   never      maybe    No    postinst configure (when requested)
+  t.-awaited  yes        always   No    postinst triggered + fix awaited pkg(s)
+  t.-awaited  no         always   No    fix awaited package(s)
+  t.-pending  always     never    Yes   postinst triggered
+  installed   never      never    Yes   n/a
+
+Packages in t-awaited and t-pending demand satisfaction of their
+dependencies just like packages in installed.
+
+
+Details - triggering package
+----------------------------
+
+When a package <T> activates a trigger in which a package <I> is
+interested, <I> is added to the list of packages whose trigger
+processing is awaited by <T>. Zero or more packages <I> may be added as a
+result of any particular trigger activation, depending on how many
+packages were interested. (If <T> chooses, explicit trigger activation
+using dpkg-trigger of <I> by <T> need not make <T> become triggers-awaited
+in this way.)
+
+A package which awaits trigger processing but would otherwise be
+‘installed’ or ‘triggers-pending’ is considered to be in state
+‘triggers-awaited’.  Packages in ‘triggers-awaited’ do not satisfy
+Depends dependencies.
+
+Every triggered package <I> in <T>'s list of awaited packages either has a
+nonempty list of pending triggers, or is in ‘config-failed’ or worse.
+When <I> enters ‘installed’ (or ‘config-files’ or ‘not-installed’), the
+entry in <T>'s list of awaited packages is removed so that <T> may, if it
+no longer awaits any packages, become ‘installed’ or ‘triggers-pending’.
+
+Packages in ‘config-files’ or ‘not-installed’ do not await triggers.
+
+
+Details - triggered package
+---------------------------
+
+When one of the triggers in which a package is interested is
+activated, the triggered package has the trigger added to its list of
+pending triggers.  Packages with a nonempty list of pending triggers
+which would otherwise be in state ‘installed’ are in state
+‘triggers-pending’ instead, so if the package was previously
+‘installed’ it becomes ‘triggers-pending’.
+
+If a package has nonempty lists both of pending and awaited triggers,
+then it is in ‘triggers-awaited’.  Nevertheless efforts will still be
+made to process its triggers so as to make the list of pending
+triggers empty.
+
+To restore a package in state ‘triggers-pending’ to ‘installed’, or to
+process pending triggers of a package with both pending and awaited
+triggers, dpkg will run the postinst script as:
+
+   postinst triggered "<trigger-name> <trigger-name> ..."
+
+by passing a space-separated list of <trigger-name>s as the second argument.
+
+This will be attempted for each relevant package at the end of each
+dpkg run; so, normally, in the same dpkg run as the event which made
+the package go to ‘triggers-pending’.  This leaves packages in
+reasonable states by default.
+
+If the “postinst triggered” run fails the package goes to
+‘config-failed’, so that the trigger processing will not be attempted
+again until explicitly requested.
+
+
+             │
+             v
+       ┌────────────┐
+       │  unpacked  │
+       └─────┬──────┘
+             │
+             │
+  (automatic)│      ┌───────────────┐
+             │      │ config-failed │
+             │      └─────┬─────────┘
+             │            │   ^
+             │            │   │
+             ├──────<─────┘   │     ┌──────────────────────────────────┐
+             │ (user request) │     │         triggers-pending         │
+  postinst   │                │     │                or                │
+ "configure" │                │     │ triggers-awaited w/ some pending │
+             │                │     └────────────┬─────────────────────┘
+             │                │                  │    ^
+             ├────────>───────┤       postinst   │    │
+             │      error     │      "triggered" │    │
+             │                │      (automatic) │    │
+             │                │                  │    │ trigger(s)
+             │                │                  │    │ activated
+             │                └────────<─────────┤    │
+             │                       error       │    │
+             │                                   │    │
+             v                                   v    │
+       ┌──────────────────────────────────────────────┴────┐
+       │   installed or triggers-awaited w/ none pending   │
+       └───────────────────────────────────────────────────┘
+
+Packages in ‘config-failed’ or worse are never considered to have
+lists of pending triggers.  A package whose postinst is being run
+can however acquire pending triggers during that run (ie, a package
+can trigger itself).
+
+This means that if a triggering package <T> awaits trigger processing by
+an interested package <I>, and <I> goes to ‘config-failed’ or worse (eg,
+during unpack for upgrade), then when <I> is reconfigured (goes to
+‘installed’) or removed, <T> will no longer await processing by <I>, so
+that <T> may automatically go from ‘triggers-awaited’ to ‘installed’.
+
+Or to put it another way, triggered actions are considered irrelevant
+if the interested package <I> is not configured. When <I>'s postinst is
+called with ‘configure’, it must do whatever actions are necessary to
+deal with any trigger activations which might have occurred while it
+was not configured, just as if the package was being configured for
+the first time.
+
+Trigger processing should be idempotent.  The list of triggers being
+processed is provided to the postinst only so that it can optimize
+away redundant processing.
+
+In that case, where an interested package has more than one trigger
+and wants to process them differently, the list of triggers can be can
+be examined in a shell script like this:
+   case " $2 " in
+   *" trigger-name-a "*)  process-trigger-a ;;
+   esac
+Generally each trigger name should be tested for separately, as the
+postinst will often be called for several triggers at once.
+
+Note that if a package both activates triggers in other packages, and
+is interested in triggers of its own, its postinst may run for trigger
+processing before the postinst(s) of the package(s) it has triggered.
+
+
+Timing guarantees, races, etc.
+------------------------------
+
+Activating a trigger will not have any immediate effect, although
+putative resulting status changes will show up in dpkg --status etc.
+(Putative because the actual status changes may depend on the state of
+trigger interests when dpkg processes the trigger activation into
+the status database, rather than that when dpkg --status is run.)
+
+A package is only guaranteed to become notified of a trigger
+activation if it is continuously interested in the trigger, and never
+in ‘config-failed’ or worse, during the period from when the trigger
+is activated until dpkg runs the package postinst (either due to
+--configure --pending, or at the end of the relevant run, as described
+above).  Subsequent to activation and before notification, the
+interested package will not be considered in state ‘installed’, so
+long as the package remains interested, and the triggering package
+will not be considered ‘installed’.
+
+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
+‘config-failed’ inclusive) declares some trigger interests then the
+triggering packages *will* await their configuration (which implies
+completion of any necessary trigger processing) or removal.
+
+It is not defined in what order triggers will run.  dpkg will make
+some effort to minimize redundant work in the case where many packages
+have postinst trigger processing activating another package's triggers
+(for example, by processing triggers in fifo order during a single
+dpkg run).  Cycles in the triggering graph are prohibited and will
+eventually, perhaps after some looping, be detected by dpkg and cause
+trigger processing to fail; when this happens one of the packages
+involved will be put in state ‘config-failed’ so that the trigger loop
+will not be reattempted.  See “Cycle detection” below.
+
+
+Explicit triggers
+-----------------
+
+Explicit triggers have names with the same syntax as package names,
+*but* should *not* normally be named identically to a package.
+
+When choosing an explicit trigger name it is usually good to include a
+relevant package name or some other useful identifier to help make the
+trigger name unique.  On the other hand, explicit triggers should
+generally not be renamed just because the interested or triggering
+packages' names change.
+
+Explicit trigger names form part of the interface between packages.
+Therefore in case of wider use of any trigger the name and purpose
+should be discussed in the usual way and documented in the appropriate
+packaging guidelines (eg, in the distribution policy).
+
+
+File triggers
+-------------
+
+File triggers have names of the form
+  /path/to/directory/or/file
+and are activated when the specified filesystem object, or any object
+under the specified subdirectory, is created, updated or deleted by
+dpkg during package unpack or removal.  The pathname must be absolute.
+
+File triggers should not generally be used without mutual consent.
+The use of a file trigger, and the name of the trigger used, should be
+stated in the distribution policy, so that a package which creates a
+relevant file in a maintainer script can activate the trigger explicitly.
+
+File triggers must definitely not be used as an escalation tool in
+disagreements between different packages as to the desired contents of
+the filesystem.  Trigger activation due to a particular file should
+not generally modify that file again.
+
+Configuration files (whether dpkg-handled conffiles or not), or any
+other files which are modified at times other than package management,
+should not rely on file triggers detecting all modifications; dpkg
+triggers are not a general mechanism for filesystem monitoring.
+
+If there are or might be 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 truename 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.
+
+A file trigger is guaranteed to be activated before the file in
+question is modified by dpkg; on the other hand, a file trigger might
+be activated even though no file was actually modified.  Changes made
+by dpkg to the link count of a file, or to solely the inode number
+(ie, if dpkg atomically replaces it with another identical file), are
+not guaranteed to cause trigger activation.
+
+Because of the restriction on trigger names, it is not possible to
+declare a file trigger for a directory whose name contains whitespace,
+i18n characters, etc.  Such a trigger should not be necessary.
+
+
+Package declarations regarding triggers
+---------------------------------------
+
+See deb-triggers(5).
+
+Support future extension of the trigger name syntax with additional
+dpkg-generated triggers is as follows: a package which is interested
+in any unsupported trigger kinds cannot be configured (since such a
+package cannot be guaranteed to have these triggers properly activated
+by dpkg).  Therefore no package can be interested in any unsupported
+trigger kinds and they can be freely activated (both by ‘activate’ and
+by dpkg-trigger).  dpkg-deb will be changed to warn about unrecognized
+trigger names syntaxes and unrecognized trigger control directives.
+
+
+New command line interfaces to dpkg tools
+-----------------------------------------
+
+See dpkg(1).
+
+Here is a summary of the behaviors:
+
+ Command line		Trigproc	Trigproc	Configure
+			these		any triggered
+ ----------------------+---------------+---------------+-----------------
+ --unpack		no		usually[1]	none
+ --remove		n/a		usually[1]	none
+ --install		n/a		usually[1]	these
+ --configure -a		any needed	usually[1]	any needed
+ --configure <some>	if needed	usually[1]	must, or trigproc
+ --triggers-only -a	any needed	usually[1]	none
+ --triggers-only <some>	must		usually not[1]	none
+
+ [1] can be specified explicitly by --triggers or --no-triggers
+
+
+See dpkg-trigger(1).
+
+A trigger may be activated explicitly with:
+   dpkg-trigger [--by-package <package>] <name-of-trigger>
+   dpkg-trigger --no-await <name-of-trigger>
+
+There will be no output to stdout, and none to stderr unless
+dpkg-trigger is unable to make a record of the trigger activation.
+
+NB that in the case of a file trigger the name of the trigger is
+needed, not the name of a file which would match the trigger.
+
+
+apt and aptitude
+----------------
+
+These must be taught about the new ‘triggers-awaited’ and
+‘triggers-pending’ states.  Packages in these states should be treated
+roughly like those in ‘unpacked’: the remedy is to run dpkg
+--configure.
+
+Normally apt and aptitude will not see packages in ‘triggers-pending’
+since dpkg will generally attempt to run the triggers thus leaving the
+package in ‘config-failed’ or ‘installed’.
+
+Note that automatic package management tools which call dpkg (like apt
+and aptitude) should not attempt to configure individual packages in
+state ‘triggers-pending’ (or indeed ‘triggers-awaited’) with dpkg
+--triggers-only <package>... or dpkg --no-triggers --configure <package>...,
+or similar approaches. This might defeat dpkg's trigger cycle detection.
+
+A package management tool which will run dpkg --configure --pending at
+the end may use --no-triggers on its other dpkg runs.  This would be
+more efficient as it allows more aggressive deferral (and hence more
+unification) of trigger processing.
+
+
+Error handling
+--------------
+
+Packages should be written so that they DO NOT BREAK just because
+their pending triggers have not yet been run.  It is allowed for the
+functionality relating to the unprocessed trigger to fail (ie, the
+package which is awaiting the trigger processing may be broken), but
+the remainder of the interested package must work normally.
+
+For example, a package which uses file triggers to register addons
+must cope with (a) an addon being dropped into the filesystem but not
+yet registered and (b) an addon being removed but not yet
+deregistered.  In both of these cases the package's main functionality
+must continue to work normally; failure of the addon in question is
+expected, warning messages are tolerable, but complete failure of the
+whole package, or failures of other addons, are not acceptable.
+
+dpkg cannot ensure that triggers are run in a timely enough manner for
+pathological error behaviors to be tolerable.
+
+
+Where a trigger script finds bad data provided by a triggering
+package, it should generally report to stderr the problem with the bad
+data and exit nonzero, leaving the interested package in config-failed
+and the triggering package in triggers-awaited and thus signalling the
+problem to the user.
+
+Alternatively, in some situations it may be more desirable to allow
+the interested package to be configured even though it can only
+provide partial service.  In this case clear information will have to
+be given in appropriate places about the missing functionality, and a
+record should be made of the cause of the errors.  This option is
+recommended for situations where the coupling between the interested
+and triggering package is particularly loose; an example of such a
+loose coupling would be Python modules.
+
+
+
+WORKED EXAMPLE - SCROLLKEEPER
+=============================
+
+Currently, every Gnome program which comes with some help installs the
+help files in /usr/share/gnome/help and then in the postinst runs
+scrollkeeper-update.  scrollkeeper-update reads, parses and rewrites
+some large xml files in /var/lib/scrollkeeper; currently this
+occurs at every relevant package installation, upgrade or removal.
+
+When triggers are available, this will work as follows:
+
+ * gnome-foobar will ship its «omf» file in /usr/share/omf as
+   normal, but will not contain any special machinery to invoke
+   scrollkeeper.
+
+ * scrollkeeper will in its triggers control file say:
+       interest /usr/share/omf
+   and in its postinst say:
+       scrollkeeper-update-now -q
+
+   dpkg will arrange that this is run once at the end of each run
+   where any documentation was updated.
+
+   Note that it is not necessary to execute this only on particular
+   postinst "$1" values; however, at the time of writing, scrollkeeper
+   does this:
+
+       if [ "$1" = "configure" ]; then
+         printf "Rebuilding the database. This may take some time.\n"
+         scrollkeeper-rebuilddb -q
+       fi
+
+   and to retain this behavior, something along the following lines
+   would be sensible:
+
+       if [ "$1" = "configure" ]; then
+         printf "Rebuilding the database. This may take some time.\n"
+         scrollkeeper-rebuilddb -q
+       else
+         printf "Updating GNOME help database.\n"
+         scrollkeeper-update-now -q
+       fi
+
+ * dh_scrollkeeper will only adjust the DTD declarations and no longer
+   edit maintainer scripts.
+
+
+Full implementation of the transition plan defined below, for
+scrollkeeper, goes like this:
+
+ 1. Update scrollkeeper:
+     - Add a ‘triggers’ control archive file containing
+           interest /usr/share/omf
+     - Make the postinst modifications as described above.
+     - Rename scrollkeeper-update to scrollkeeper-update-now
+     - Provide a new wrapper script as scrollkeeper-update:
+	   #!/bin/sh
+	   set -e
+	   if type dpkg-trigger >/dev/null 2>&1 && \
+	      dpkg-trigger /usr/share/omf; then
+		 exit 0
+	   fi
+	   exec scrollkeeper-update-now "$@"
+
+ 2. In gnome-policy chapter 2, “Use of scrollkeeper”,
+     - delete the requirement that the package must depend on
+       scrollkeeper
+     - delete the requirement that the package must invoke
+       scrollkeeper in the postinst and postrm
+     - instead say:
+
+         OMF files should be installed under /usr/share/omf in the
+         usual way.  A dpkg trigger is used to arrange to update the
+         scrollkeeper documentation index automatically and no special
+         care need be taken in packages which supply OMFs.
+
+         If an OMF file is placed, modified or removed other than as
+         a file installed in the ordinary way by dpkg, the dpkg file
+         trigger «/usr/share/omf» should be activated; see the dpkg
+         triggers specification for details.
+
+         Existing packages which Depend on scrollkeeper (>= 3.8)
+         because of dh_scrollkeeper or explicit calls to
+         scrollkeeper-update should be modified not to Depend on
+         scrollkeeper.
+
+ 3. Update debhelper's dh_scrollkeeper not to edit maintainer
+    scripts.  One of dh_scrollkeeper or lintian should be changed to
+    issue a warning for packages with scrollkeeper (>= 3.8) in the
+    Depends control file line.
+
+ 4. Remove the spurious dependencies on scrollkeeper, at our leisure.
+    As a bonus, after this is complete it will be possible to remove
+    scrollkeeper while keeping all of the documentation-supplying
+    gnome packages installed.
+
+ 5. If there are any packages which do by hand what dh_scrollkeeper
+    does, change them not to call scrollkeeper-update and drop
+    their dependency on scrollkeeper.
+
+This is not 100% in keeping with the full transition plan defined
+below: if a new gnome package is used with an old scrollkeeper, there
+is some possibility that the help will not properly be available.
+
+Unfortunately, dh_scrollkeeper doesn't generate the scrollkeeper
+dependency in the control file, which makes it excessively hard to get
+the dependency up to date.  The bad consequences of the inaccurate
+dependencies are less severe than the contortions which would be
+required to deal with the problem.
+
+
+TRANSITION PLAN
+===============
+
+
+Old dpkg to new dpkg
+--------------------
+
+The first time a trigger-supporting dpkg is run on any system, it will
+activate all triggers in which anyone is interested, immediately.
+
+These trigger activations will not be processed in the same dpkg run,
+to avoid unexpectedly processing triggers while attempting an
+unrelated operation.  dpkg --configure --pending (and not other dpkg
+operations) will run the triggers, and the dpkg postinst will warn the
+user about the need to run it (if this deferred triggers condition
+exists).  (Any triggers activated or reactivated *after* this
+mass-activation will be processed in the normal way.)
+
+To use this correctly:
+ * Packages which are interested in triggers, or which want to
+    explicitly activate triggers, should Depend on the
+    triggers-supporting version of dpkg.
+ * Update instructions and tools should arrange to run
+    dpkg --configure --pending
+   after the install; this will process the pending triggers.
+
+dpkg's prerm will check for attempts to downgrade while triggers are
+pending and refuse.  (Since the new dpkg would be installed but then
+refuse to read the status file.)  In case this is necessary a separate
+tool will be provided which will:
+  * Put all packages with any pending triggers into state
+    ‘config-failed’ and remove the list of pending triggers.
+  * Remove the list of awaited triggers from every package.  This
+    may cause packages to go from ‘triggers-awaited’ to ‘installed’
+    which is not 100% accurate but the best that can be done.
+  * Remove /var/lib/dpkg/triggers (to put the situation to that which
+    we would have seen if the trigger-supporting dpkg had never been
+    installed).
+
+
+Higher-level programs
+---------------------
+
+The new dpkg will declare versioned Conflicts against apt and aptitude
+and other critical package management tools which will be broken by
+the new Status field values.  Therefore, the new higher-level tools
+will have to be deployed first.
+
+The new dpkg will declare versioned Breaks against any known
+noncritical package management tools which will be broken by the new
+Status field value.
+
+
+Transition hints for existing packages
+--------------------------------------
+
+When a central (consumer) package defines a directory where other leaf
+(producer) packages may place files and/or directories, and currently
+the producer packages are required to run an «update-consumer» script
+in their postinst:
+ 1. In the relevant policy, define a trigger name which is the name of
+    the directory where the individual files are placed by producer
+    packages.
+ 2. Update the consumer package:
+    * Declare an interest in the trigger.
+    * Edit «update-consumer» so that if it is called without --real
+      it does the following:
+	  if type dpkg-trigger >/dev/null 2>&1 && \
+	     dpkg-trigger name-of-trigger; then
+		exit 0
+	  fi
+      If this fails to cause «update-consumer» to exit, it should do
+      its normal update processing.  Alternatively, if it is more
+      convenient, «update-consumer» could be renamed and supplanted with
+      a wrapper script which conditionally runs the real
+      «update-consumer».
+    * In the postinst, arrange for the new ‘triggered’ invocation to
+      run «update-consumer --real».  The consumer package's postinst
+      will already run «update-consumer» during configuration, and this
+      should be retained and supplemented with the --real option (or
+      changed to call the real script rather than the wrapper).
+ 3. Update the producer packages:
+    * In the postinst, remove the call to «update-consumer».
+    * Change the dependency on consumer to be versioned, specifying a
+      trigger-interested consumer.
+    This can be done at our leisure.  Ideally for loosely coupled
+    packages this would be done only in the release after the one
+    containing the triggers-interested consumer, to facilitate partial
+    upgrades and backports.
+ 4. After all producer packages have been updated according to step 3,
+    «update-consumer» has become an interface internal to the consumer
+    and need no longer be kept stable.  If un-updated producers are
+    still of interest, incompatible changes to «update-consumer» imply
+    a versioned Breaks against the old producers.
+(See also “Transition plan”, below.)
+
+If there are several consumer packages all of which are interested in
+the features provided by producer packages, the current arrangements
+usually involve an additional central switchboard package (eg,
+emacsen-common).  In this case:
+
+ -- NOTE - this part of the transition plan is still a proof of
+           concept and we might yet improve on it
+
+ 1. Define the trigger name.
+ 2. Update the switchboard to have any new functionality needed by the
+    consumers in step 3 (2nd bullet).
+ 3. Update the consumer packages:
+    * Declare an interest in the trigger.
+    * In the postinst, arrange for the new ‘trigger’ invocation to run
+      the compilation/registration process.  This may involve scanning
+      for new or removed producers, and may involve new common
+      functionality from the switchboard (in which case a versioned
+      Depends is needed).
+    * The old interface allowing the switchboard to run
+      compilation/registration should be preserved, including
+      calls to the switchboard to register this consumer.
+ 4. When all consumers have been updated, update the switchboard:
+    * Make the registration scripts called by producers try to
+      activate the trigger and if that succeeds quit without
+      doing any work (as for bullet 2 in the simple case above).
+    * Versioned Breaks, against the old (pre-step-3) consumers.
+ 5. After the switchboard has been updated, producers can be updated:
+    * Remove the calls to the switchboard registration/compilation
+      functions.
+    * Change the dependency on the switchboard to a versioned one,
+      specifying the one which Breaks old consumers.  Alternatively,
+      it may be the case that the switchboard is no longer needed (or
+      not needed for this producer), in which case the dependency on
+      the switchboard can be removed in favour of an appropriate
+      versioned Breaks (probably, identical to that in the new
+      switchboard).
+ 6. After all the producers have been updated, the cruft in the
+    consumers can go away:
+    * Remove the calls to the switchboard's registration system.
+    * Versioned Breaks against old switchboards, or versioned Depends
+      on new switchboards, depending on whether the switchboard is
+      still needed for other common functionality.
+ 7. After all of the producers and consumers have been updated, the
+    cruft in the switchboard can go away:
+    * Remove the switchboard's registration system (but not obviously
+      the common functionality from step 3, discussed above).
+    * Versioned Breaks against pre-step-6 consumers and pre-step-5
+      producers.
+
+
+DISCUSSION
+==========
+
+The activation of a trigger does not record details of the activating
+event.  For example, file triggers do not inform the package of the
+filename.  In the future this might be added as an additional feature,
+but there are some problems with this.
+
+
+Broken producer packages, and error reporting
+---------------------------------------------
+
+Often trigger processing will involve a central package registering,
+compiling or generally parsing some data provided by a leaf package.
+
+If the central package finds problems with the leaf package data it is
+usually more correct for only the individual leaf package to be
+recorded as not properly installed.  There is not currently any way to
+do this and there are no plans to provide one.
+
+The naive approach of giving the postinst a list of the triggering
+packages does not work because this information is not recorded in the
+right way (it might suffer from lacunae); enhancing the bookkeeping
+for this to work would be possible but it is far better simply to make
+the system more idempotent.  See above for the recommended approach.
+
+
+
+
+INTERNALS
+=========
+
+On-disk state
+-------------
+
+A single file /var/lib/dpkg/triggers/File lists all of the filename
+trigger interests in the form
+   /path/to/directory/or/file package
+
+For each explicit trigger in which any package is interested,
+a file /var/lib/dpkg/triggers/<name-of-trigger> is a list of
+the interested packages, one per line.
+
+These interest files are not updated to remove a package just because
+a state change causes it not to be interested in any triggers any more
+- they are updated when we remove or unpack.
+
+For each package which has pending triggers, the status file contains
+a Triggers-Pending field which contains the space-separated names of
+the pending triggers.  For each package which awaits triggers the
+status file contains a Triggers-Awaited field which contains the
+*package* names of the packages whose trigger processing is awaited.
+See “Details - Overview table” above for the invariants which relate
+Triggers-Pending, Triggers-Awaited, and Status.
+
+During dpkg's execution, /var/lib/dpkg/triggers/Unincorp is a list of
+the triggers which have been requested by dpkg-trigger but not yet
+incorporated in the status file.  Each line is a trigger name followed
+by one or more triggering package names.  The triggering package name
+"-" is used to indicate one or more package(s) which did not need to
+await the trigger.
+
+/var/lib/dpkg/triggers/Lock is the fcntl lockfile for the trigger
+system.  Processes hang onto this lock only briefly: dpkg-trigger
+to add new activations, or dpkg to incorporate activations (and
+perhaps when it updates interests).  Therefore this lock is always
+acquired with F_GETLKW so as to serialize rather than fail on
+contention.
+
+
+Processing
+----------
+
+dpkg-trigger updates triggers/Unincorp, and does not read or write the
+status file or take out the dpkg status lock.  dpkg (and dpkg-query)
+reads triggers/Unincorp after reading /var/lib/dpkg/status, and after
+running a maintainer script.  If the status database is opened for
+writing then the data from Unincorp is moved to updates as
+Triggers-Pending and Triggers-Awaited entries and corresponding Status
+changes.
+
+This means that dpkg is guaranteed to reincorporate pending trigger
+information into the status file only 1. when a maintainer script has
+finished, or 2. when dpkg starts up with a view to performing some
+operation.
+
+When a package is unpacked or removed, its triggers control file will
+be parsed and /var/lib/dpkg/triggers/* updated accordingly.
+
+Triggers are run as part of configuration.  dpkg will try to first
+configure all packages which do not depend on packages which are
+awaiting triggers, and then run triggers one package at a time in the
+hope of making useful progress.  (This will involve a new ‘dependtry’
+level in configure.c's algorithm.)  The only constraint on the
+ordering of postinsts is only the normal Depends constraint, so the
+usual Depends cycle breaking will function properly.  See “Cycle
+detection” below regarding cycles in the “A triggers B” relation.
+
+
+Processing - Transitional
+-------------------------
+
+The case where a triggers-supporting dpkg is run for the first time is
+detected by the absence of /var/lib/dpkg/triggers/Unincorp.  When the
+triggers-supporting dpkg starts up without this it will set each
+package's list of pending triggers equal to its interests (obviously
+only for packages which are in ‘installed’ or ‘triggers-pending’).
+This may result in a package going from ‘installed’ to
+‘triggers-pending’ but it will not create the directory at this time.
+Packages marked as triggers-pending in this way will not be scheduled
+for trigger processing in this dpkg run.
+
+dpkg will also at this time create /var/lib/dpkg/triggers if
+necessary, triggers/File, triggers/Unincorp, and the per-trigger
+package lists in /var/lib/dpkg/triggers/<trigger-name>, so that future
+trigger activations will be processed properly.
+
+Only dpkg may create /var/lib/dpkg/triggers and only when it is
+holding the overall dpkg status lock.
+
+dpkg and/or dpkg-deb will be made to reject packages containing
+Triggers-Pending and Triggers-Awaited control file fields, to prevent
+accidents.
+
+
+Cycle detection
+---------------
+
+In addition to dependency cycles, triggers raise the possibility of
+mutually triggering packages - a cycle detectable only dynamically,
+which we will call a “trigger cycle”.
+
+Trigger cycles are detected using the usual hare-and-tortoise
+approach.  Each time after dpkg runs a postinst for triggers, dpkg
+records the set of pending triggers (ie, the set of activated <pending
+package, trigger name> tuples).  If the hare set is a superset of the
+tortoise set, a cycle has been found.
+
+For guaranteed termination, it would be sufficient to declare a cycle
+only when the two sets are identical, but because of the requirement
+to make progress we can cut this short.  Formally, there is supposed
+to be a complete ordering of pending trigger sets satisfying the
+condition that any set of pending triggers is (strictly) greater than
+all its (strict) subsets.  Trigger processing is supposed to
+monotonically decrease the set in this ordering.  (The set elements
+are <package, trigger name> tuples.)
+
+(See “Processing” above for discussion of dependency cycles.)