Commit | Line | Data |
---|---|---|
1479465f GJ |
1 | TRIGGERS |
2 | ======== | |
3 | ||
4 | Introduction | |
5 | ------------ | |
6 | ||
7 | A dpkg trigger is a facility that allows events caused by one package | |
8 | but of interest to another package to be recorded and aggregated, and | |
9 | processed later by the interested package. This feature simplifies | |
10 | various registration and system-update tasks and reduces duplication | |
11 | of processing. | |
12 | ||
13 | (NB: Triggers are intended for events that occur during package | |
14 | installation, not events that occur in general operation.) | |
15 | ||
16 | ||
17 | Concepts | |
18 | -------- | |
19 | ||
20 | Each trigger is named, and at any time zero or more packages may be | |
21 | interested in it. | |
22 | ||
23 | We currently envisage three kinds of triggers: | |
24 | * Explicit triggers. These can be activated by any program | |
25 | by running dpkg-trigger (at any time, but ideally from a maintainer | |
26 | script). | |
27 | * File triggers. These are activated automatically by dpkg | |
28 | when a matching file is installed, upgraded or removed as part | |
29 | of a package. They may also be explicitly activated by running | |
30 | dpkg-trigger. | |
31 | * Future kinds of special triggers, which are activated by magic code | |
32 | in dpkg itself. Currently none are defined besides file triggers. | |
33 | ||
34 | A trigger is always activated by a particular package. | |
35 | ||
36 | Trigger names contain only printing 7-bit ascii characters (no | |
37 | whitespace). Each trigger kind has a distinct subset of the trigger | |
38 | name space so that the kind can be determined from the name. After we | |
39 | run out of straightforward syntaxes, we will use <kind>:<details>. | |
40 | ||
41 | When a trigger is activated, it becomes pending for every package | |
42 | which is interested in the trigger at that time. Each package has a | |
43 | list of zero or more pending triggers. Repeated activation of the | |
44 | same trigger has no additional effect. Note that in general a trigger | |
45 | will not be processed immediately when it is activated; processing is | |
46 | deferred until it is convenient (as described below). | |
47 | ||
48 | At a trigger activation, the interested packages(s) are added to the | |
49 | triggering package's list of triggers-awaited packages (unless the | |
50 | trigger has been configured to not require it); the triggering | |
51 | package is said to await the trigger processing. | |
52 | ||
53 | A package which has pending triggers, or which awaits triggers, is not | |
54 | considered properly installed. There are two new dpkg status values, | |
55 | ‘triggers-pending’ and ‘triggers-awaited’, which lie between | |
56 | ‘config-failed’ and ‘installed’. | |
57 | ||
58 | ||
59 | Details - Overview table | |
60 | ------------------------ | |
61 | ||
62 | Status Pending Awaited Satisfies Remedy | |
63 | triggers triggers Depends | |
64 | ||
65 | unpacked never maybe No postinst configure | |
66 | c.-failed never maybe No postinst configure (when requested) | |
67 | t.-awaited yes always No postinst triggered + fix awaited pkg(s) | |
68 | t.-awaited no always No fix awaited package(s) | |
69 | t.-pending always never Yes postinst triggered | |
70 | installed never never Yes n/a | |
71 | ||
72 | Packages in t-awaited and t-pending demand satisfaction of their | |
73 | dependencies just like packages in installed. | |
74 | ||
75 | ||
76 | Details - triggering package | |
77 | ---------------------------- | |
78 | ||
79 | When a package T activates a trigger in which a package I is | |
80 | interested, I is added to the list of packages whose trigger | |
81 | processing is awaited by T. Zero or more packages I may be added as a | |
82 | result of any particular trigger activation, depending on how many | |
83 | packages were interested. (If T chooses, explicit trigger activation | |
84 | using dpkg-trigger of I by T need not make T become triggers-awaited | |
85 | in this way.) | |
86 | ||
87 | A package which awaits trigger processing but would otherwise be | |
88 | ‘installed’ or ‘triggers-pending’ is considered to be in state | |
89 | ‘triggers-awaited’. Packages in ‘triggers-awaited’ do not satisfy | |
90 | Depends dependencies. | |
91 | ||
92 | Every triggered package I in T's list of awaited packages either has a | |
93 | nonempty list of pending triggers, or is in ‘config-failed’ or worse. | |
94 | When I enters ‘installed’ (or ‘config-files’ or ‘not-installed’), the | |
95 | entry in T's list of awaited packages is removed so that T may, if it | |
96 | no longer awaits any packages, become ‘installed’ or ‘triggers-pending’. | |
97 | ||
98 | Packages in ‘config-files’ or ‘not-installed’ do not await triggers. | |
99 | ||
100 | ||
101 | Details - triggered package | |
102 | --------------------------- | |
103 | ||
104 | When one of the triggers in which a package is interested is | |
105 | activated, the triggered package has the trigger added to its list of | |
106 | pending triggers. Packages with a nonempty list of pending triggers | |
107 | which would otherwise be in state ‘installed’ are in state | |
108 | ‘triggers-pending’ instead, so if the package was previously | |
109 | ‘installed’ it becomes ‘triggers-pending’. | |
110 | ||
111 | If a package has nonempty lists both of pending and awaited triggers, | |
112 | then it is in ‘triggers-awaited’. Nevertheless efforts will still be | |
113 | made to process its triggers so as to make the list of pending | |
114 | triggers empty. | |
115 | ||
116 | To restore a package in state ‘triggers-pending’ to ‘installed’, or to | |
117 | process pending triggers of a package with both pending and awaited | |
118 | triggers, dpkg will run the postinst script: | |
119 | postinst triggered "<trigger-name> <trigger-name> ..." | |
120 | ||
121 | This will be attempted for each relevant package at the end of each | |
122 | dpkg run; so, normally, in the same dpkg run as the event which made | |
123 | the package go to ‘triggers-pending’. This leaves packages in | |
124 | reasonable states by default. | |
125 | ||
126 | If the “postinst triggered” run fails the package goes to | |
127 | ‘config-failed’, so that the trigger processing will not be attempted | |
128 | again until explicitly requested. | |
129 | ||
130 | ||
131 | │ | |
132 | v | |
133 | ┌────────────┐ | |
134 | │ unpacked │ | |
135 | └─────┬──────┘ | |
136 | │ | |
137 | │ | |
138 | (automatic)│ ┌───────────────┐ | |
139 | │ │ config-failed │ | |
140 | │ └─────┬─────────┘ | |
141 | │ │ ^ | |
142 | │ │ │ | |
143 | ├──────<─────┘ │ ┌──────────────────────────────────┐ | |
144 | │ (user request) │ │ triggers-pending │ | |
145 | postinst │ │ │ or │ | |
146 | "configure" │ │ │ triggers-awaited w/ some pending │ | |
147 | │ │ └────────────┬─────────────────────┘ | |
148 | │ │ │ ^ | |
149 | ├────────>───────┤ postinst │ │ | |
150 | │ error │ "triggered" │ │ | |
151 | │ │ (automatic) │ │ | |
152 | │ │ │ │ trigger(s) | |
153 | │ │ │ │ activated | |
154 | │ └────────<─────────┤ │ | |
155 | │ error │ │ | |
156 | │ │ │ | |
157 | v v │ | |
158 | ┌──────────────────────────────────────────────┴────┐ | |
159 | │ installed or triggers-awaited w/ none pending │ | |
160 | └───────────────────────────────────────────────────┘ | |
161 | ||
162 | Packages in ‘config-failed’ or worse are never considered to have | |
163 | lists of pending triggers. A package whose postinst is being run | |
164 | can however acquire pending triggers during that run (ie, a package | |
165 | can trigger itself). | |
166 | ||
167 | This means that if a triggering package T awaits trigger processing by | |
168 | an interested package I, and I goes to ‘config-failed’ or worse (eg, | |
169 | during unpack for upgrade), then when I is reconfigured (goes to | |
170 | ‘installed’) or removed, T will no longer await processing by I, so | |
171 | that T may automatically go from ‘triggers-awaited’ to ‘installed’. | |
172 | ||
173 | Or to put it another way, triggered actions are considered irrelevant | |
174 | if the interested package I is not configured. When I's postinst is | |
175 | called with ‘configure’, it must do whatever actions are necessary to | |
176 | deal with any trigger activations which might have occurred while it | |
177 | was not configured, just as if the package was being configured for | |
178 | the first time. | |
179 | ||
180 | Trigger processing should be idempotent. The list of triggers being | |
181 | processed is provided to the postinst only so that it can optimize | |
182 | away redundant processing. | |
183 | ||
184 | In that case, where an interested package has more than one trigger | |
185 | and wants to process them differently, the list of triggers can be can | |
186 | be examined in a shell script like this: | |
187 | case " $2 " in | |
188 | *" trigger-name-a "*) process-trigger-a ;; | |
189 | esac | |
190 | Generally each trigger name should be tested for separately, as the | |
191 | postinst will often be called for several triggers at once. | |
192 | ||
193 | Note that if a package both activates triggers in other packages, and | |
194 | is interested in triggers of its own, its postinst may run for trigger | |
195 | processing before the postinst(s) of the package(s) it has triggered. | |
196 | ||
197 | ||
198 | Timing guarantees, races, etc. | |
199 | ------------------------------ | |
200 | ||
201 | Activating a trigger will not have any immediate effect, although | |
202 | putative resulting status changes will show up in dpkg --status etc. | |
203 | (Putative because the actual status changes may depend on the state of | |
204 | trigger interests when dpkg processes the trigger activation into | |
205 | the status database, rather than that when dpkg --status is run.) | |
206 | ||
207 | A package is only guaranteed to become notified of a trigger | |
208 | activation if it is continuously interested in the trigger, and never | |
209 | in ‘config-failed’ or worse, during the period from when the trigger | |
210 | is activated until dpkg runs the package postinst (either due to | |
211 | --configure --pending, or at the end of the relevant run, as described | |
212 | above). Subsequent to activation and before notification, the | |
213 | interested package will not be considered in state ‘installed’, so | |
214 | long as the package remains interested, and the triggering package | |
215 | will not be considered ‘installed’. | |
216 | ||
217 | If the package is not in state ‘installed’, ‘triggers-pending’ or | |
218 | ‘triggers-awaited’ then pending triggers are not accumulated. | |
219 | However, if such a package (between ‘half-installed’ and | |
220 | ‘config-failed’ inclusive) declares some trigger interests then the | |
221 | triggering packages *will* await their configuration (which implies | |
222 | completion of any necessary trigger processing) or removal. | |
223 | ||
224 | It is not defined in what order triggers will run. dpkg will make | |
225 | some effort to minimize redundant work in the case where many packages | |
226 | have postinst trigger processing activating another package's triggers | |
227 | (for example, by processing triggers in fifo order during a single | |
228 | dpkg run). Cycles in the triggering graph are prohibited and will | |
229 | eventually, perhaps after some looping, be detected by dpkg and cause | |
230 | trigger processing to fail; when this happens one of the packages | |
231 | involved will be put in state ‘config-failed’ so that the trigger loop | |
232 | will not be reattempted. See “Cycle detection” below. | |
233 | ||
234 | ||
235 | Explicit triggers | |
236 | ----------------- | |
237 | ||
238 | Explicit triggers have names with the same syntax as package names, | |
239 | *but* should *not* normally be named identically to a package. | |
240 | ||
241 | When choosing an explicit trigger name it is usually good to include a | |
242 | relevant package name or some other useful identifier to help make the | |
243 | trigger name unique. On the other hand, explicit triggers should | |
244 | generally not be renamed just because the interested or triggering | |
245 | packages' names change. | |
246 | ||
247 | Explicit trigger names form part of the interface between packages. | |
248 | Therefore in case of wider use of any trigger the name and purpose | |
249 | should be discussed in the usual way and documented in the appropriate | |
250 | packaging guidelines (eg, in the distribution policy). | |
251 | ||
252 | ||
253 | File triggers | |
254 | ------------- | |
255 | ||
256 | File triggers have names of the form | |
257 | /path/to/directory/or/file | |
258 | and are activated when the specified filesystem object, or any object | |
259 | under the specified subdirectory, is created, updated or deleted by | |
260 | dpkg during package unpack or removal. The pathname must be absolute. | |
261 | ||
262 | File triggers should not generally be used without mutual consent. | |
263 | The use of a file trigger, and the name of the trigger used, should be | |
264 | stated in the distribution policy, so that a package which creates a | |
265 | relevant file in a maintainer script can activate the trigger explicitly. | |
266 | ||
267 | File triggers must definitely not be used as an escalation tool in | |
268 | disagreements between different packages as to the desired contents of | |
269 | the filesystem. Trigger activation due to a particular file should | |
270 | not generally modify that file again. | |
271 | ||
272 | Configuration files (whether dpkg-handled conffiles or not), or any | |
273 | other files which are modified at times other than package management, | |
274 | should not rely on file triggers detecting all modifications; dpkg | |
275 | triggers are not a general mechanism for filesystem monitoring. | |
276 | ||
277 | If there are or might be directory symlinks which result in packages | |
278 | referring to files by different names, then to be sure of activation | |
279 | all of the paths which might be included in packages should be listed. | |
280 | The path specified by the interested package is matched against the | |
281 | path included in the triggering package, not against the truename of | |
282 | the file as installed. Only textually identical filenames (or | |
283 | filenames where the interest is a directory prefix of the installed | |
284 | file) are guaranteed to match. | |
285 | ||
286 | A file trigger is guaranteed to be activated before the file in | |
287 | question is modified by dpkg; on the other hand, a file trigger might | |
288 | be activated even though no file was actually modified. Changes made | |
289 | by dpkg to the link count of a file, or to solely the inode number | |
290 | (ie, if dpkg atomically replaces it with another identical file), are | |
291 | not guaranteed to cause trigger activation. | |
292 | ||
293 | Because of the restriction on trigger names, it is not possible to | |
294 | declare a file trigger for a directory whose name contains whitespace, | |
295 | i18n characters, etc. Such a trigger should not be necessary. | |
296 | ||
297 | ||
298 | Package declarations regarding triggers | |
299 | --------------------------------------- | |
300 | ||
301 | See deb-triggers(5). | |
302 | ||
303 | Support future extension of the trigger name syntax with additional | |
304 | dpkg-generated triggers is as follows: a package which is interested | |
305 | in any unsupported trigger kinds cannot be configured (since such a | |
306 | package cannot be guaranteed to have these triggers properly activated | |
307 | by dpkg). Therefore no package can be interested in any unsupported | |
308 | trigger kinds and they can be freely activated (both by ‘activate’ and | |
309 | by dpkg-trigger). dpkg-deb will be changed to warn about unrecognized | |
310 | trigger names syntaxes and unrecognized trigger control directives. | |
311 | ||
312 | ||
313 | New command line interfaces to dpkg tools | |
314 | ----------------------------------------- | |
315 | ||
316 | See dpkg(1). | |
317 | ||
318 | Here is a summary of the behaviours: | |
319 | ||
320 | Command line Trigproc Trigproc Configure | |
321 | these any triggered | |
322 | ----------------------+---------------+---------------+----------------- | |
323 | --unpack no usually[1] none | |
324 | --remove n/a usually[1] none | |
325 | --install n/a usually[1] these | |
326 | --configure -a any needed usually[1] any needed | |
327 | --configure <some> if needed usually[1] must, or trigproc | |
328 | --triggers-only -a any needed usually[1] none | |
329 | --triggers-only <some> must usually not[1] none | |
330 | ||
331 | [1] can be specified explicitly by --triggers or --no-triggers | |
332 | ||
333 | ||
334 | See dpkg-trigger(1). | |
335 | ||
336 | A trigger may be activated explicitly with: | |
337 | dpkg-trigger [--by-package <package>] <name-of-trigger> | |
338 | dpkg-trigger --no-await <name-of-trigger> | |
339 | ||
340 | There will be no output to stdout, and none to stderr unless | |
341 | dpkg-trigger is unable to make a record of the trigger activation. | |
342 | ||
343 | NB that in the case of a file trigger the name of the trigger is | |
344 | needed, not the name of a file which would match the trigger. | |
345 | ||
346 | ||
347 | apt and aptitude | |
348 | ---------------- | |
349 | ||
350 | These must be taught about the new ‘triggers-awaited’ and | |
351 | ‘triggers-pending’ states. Packages in these states should be treated | |
352 | roughly like those in ‘unpacked’: the remedy is to run dpkg | |
353 | --configure. | |
354 | ||
355 | Normally apt and aptitude will not see packages in ‘triggers-pending’ | |
356 | since dpkg will generally attempt to run the triggers thus leaving the | |
357 | package in ‘config-failed’ or ‘installed’. | |
358 | ||
359 | Note that automatic package management tools which call dpkg (like apt | |
360 | and aptitude) should not attempt to configure individual packages in | |
361 | state ‘triggers-pending’ (or indeed ‘triggers-awaited’) with dpkg | |
362 | --triggers-only <package>... or dpkg --no-triggers --configure <package>..., | |
363 | or similar approaches. This might defeat dpkg's trigger cycle detection. | |
364 | ||
365 | A package management tool which will run dpkg --configure --pending at | |
366 | the end may use --no-triggers on its other dpkg runs. This would be | |
367 | more efficient as it allows more aggressive deferral (and hence more | |
368 | unification) of trigger processing. | |
369 | ||
370 | ||
371 | Error handling | |
372 | -------------- | |
373 | ||
374 | Packages should be written so that they DO NOT BREAK just because | |
375 | their pending triggers have not yet been run. It is allowed for the | |
376 | functionality relating to the unprocessed trigger to fail (ie, the | |
377 | package which is awaiting the trigger processing may be broken), but | |
378 | the remainder of the interested package must work normally. | |
379 | ||
380 | For example, a package which uses file triggers to register addons | |
381 | must cope with (a) an addon being dropped into the filesystem but not | |
382 | yet registered and (b) an addon being removed but not yet | |
383 | deregistered. In both of these cases the package's main functionality | |
384 | must continue to work normally; failure of the addon in question is | |
385 | expected, warning messages are tolerable, but complete failure of the | |
386 | whole package, or failures of other addons, are not acceptable. | |
387 | ||
388 | dpkg cannot ensure that triggers are run in a timely enough manner for | |
389 | pathological error behaviours to be tolerable. | |
390 | ||
391 | ||
392 | Where a trigger script finds bad data provided by a triggering | |
393 | package, it should generally report to stderr the problem with the bad | |
394 | data and exit nonzero, leaving the interested package in config-failed | |
395 | and the triggering package in triggers-awaited and thus signalling the | |
396 | problem to the user. | |
397 | ||
398 | Alternatively, in some situations it may be more desirable to allow | |
399 | the interested package to be configured even though it can only | |
400 | provide partial service. In this case clear information will have to | |
401 | be given in appropriate places about the missing functionality, and a | |
402 | record should be made of the cause of the errors. This option is | |
403 | recommended for situations where the coupling between the interested | |
404 | and triggering package is particularly loose; an example of such a | |
405 | loose coupling would be Python modules. | |
406 | ||
407 | ||
408 | ||
409 | WORKED EXAMPLE - SCROLLKEEPER | |
410 | ============================= | |
411 | ||
412 | Currently, every Gnome program which comes with some help installs the | |
413 | help files in /usr/share/gnome/help and then in the postinst runs | |
414 | scrollkeeper-update. scrollkeeper-update reads, parses and rewrites | |
415 | some large xml files in /var/lib/scrollkeeper; currently this | |
416 | occurs at every relevant package installation, upgrade or removal. | |
417 | ||
418 | When triggers are available, this will work as follows: | |
419 | ||
420 | * gnome-foobar will ship its «omf» file in /usr/share/omf as | |
421 | normal, but will not contain any special machinery to invoke | |
422 | scrollkeeper. | |
423 | ||
424 | * scrollkeeper will in its triggers control file say: | |
425 | interest /usr/share/omf | |
426 | and in its postinst say: | |
427 | scrollkeeper-update-now -q | |
428 | ||
429 | dpkg will arrange that this is run once at the end of each run | |
430 | where any documentation was updated. | |
431 | ||
432 | Note that it is not necessary to execute this only on particular | |
433 | postinst "$1" values; however, at the time of writing, scrollkeeper | |
434 | does this: | |
435 | ||
436 | if [ "$1" = "configure" ]; then | |
437 | printf "Rebuilding the database. This may take some time.\n" | |
438 | scrollkeeper-rebuilddb -q | |
439 | fi | |
440 | ||
441 | and to retain this behaviour, something along the following lines | |
442 | would be sensible: | |
443 | ||
444 | if [ "$1" = "configure" ]; then | |
445 | printf "Rebuilding the database. This may take some time.\n" | |
446 | scrollkeeper-rebuilddb -q | |
447 | else | |
448 | printf "Updating GNOME help database.\n" | |
449 | scrollkeeper-update-now -q | |
450 | fi | |
451 | ||
452 | * dh_scrollkeeper will only adjust the DTD declarations and no longer | |
453 | edit maintainer scripts. | |
454 | ||
455 | ||
456 | Full implementation of the transition plan defined below, for | |
457 | scrollkeeper, goes like this: | |
458 | ||
459 | 1. Update scrollkeeper: | |
460 | - Add a ‘triggers’ control archive file containing | |
461 | interest /usr/share/omf | |
462 | - Make the postinst modifications as described above. | |
463 | - Rename scrollkeeper-update to scrollkeeper-update-now | |
464 | - Provide a new wrapper script as scrollkeeper-update: | |
465 | #!/bin/sh | |
466 | set -e | |
467 | if type dpkg-trigger >/dev/null 2>&1 && \ | |
468 | dpkg-trigger /usr/share/omf; then | |
469 | exit 0 | |
470 | fi | |
471 | exec scrollkeeper-update-now "$@" | |
472 | ||
473 | 2. In gnome-policy chapter 2, “Use of scrollkeeper”, | |
474 | - delete the requirement that the package must depend on | |
475 | scrollkeeper | |
476 | - delete the requirement that the package must invoke | |
477 | scrollkeeper in the postinst and postrm | |
478 | - instead say: | |
479 | ||
480 | OMF files should be installed under /usr/share/omf in the | |
481 | usual way. A dpkg trigger is used to arrange to update the | |
482 | scrollkeeper documentation index automatically and no special | |
483 | care need be taken in packages which supply OMFs. | |
484 | ||
485 | If an OMF file is placed, modified or removed other than as | |
486 | a file installed in the ordinary way by dpkg, the dpkg file | |
487 | trigger «/usr/share/omf» should be activated; see the dpkg | |
488 | triggers specification for details. | |
489 | ||
490 | Existing packages which Depend on scrollkeeper (>= 3.8) | |
491 | because of dh_scrollkeeper or explicit calls to | |
492 | scrollkeeper-update should be modified not to Depend on | |
493 | scrollkeeper. | |
494 | ||
495 | 3. Update debhelper's dh_scrollkeeper not to edit maintainer | |
496 | scripts. One of dh_scrollkeeper or lintian should be changed to | |
497 | issue a warning for packages with scrollkeeper (>= 3.8) in the | |
498 | Depends control file line. | |
499 | ||
500 | 4. Remove the spurious dependencies on scrollkeeper, at our leisure. | |
501 | As a bonus, after this is complete it will be possible to remove | |
502 | scrollkeeper while keeping all of the documentation-supplying | |
503 | gnome packages installed. | |
504 | ||
505 | 5. If there are any packages which do by hand what dh_scrollkeeper | |
506 | does, change them not to call scrollkeeper-update and drop | |
507 | their dependency on scrollkeeper. | |
508 | ||
509 | This is not 100% in keeping with the full transition plan defined | |
510 | below: if a new gnome package is used with an old scrollkeeper, there | |
511 | is some possibility that the help will not properly be available. | |
512 | ||
513 | Unfortunately, dh_scrollkeeper doesn't generate the scrollkeeper | |
514 | dependency in the control file, which makes it excessively hard to get | |
515 | the dependency up to date. The bad consequences of the inaccurate | |
516 | dependencies are less severe than the contortions which would be | |
517 | required to deal with the problem. | |
518 | ||
519 | ||
520 | TRANSITION PLAN | |
521 | =============== | |
522 | ||
523 | ||
524 | Old dpkg to new dpkg | |
525 | -------------------- | |
526 | ||
527 | The first time a trigger-supporting dpkg is run on any system, it will | |
528 | activate all triggers in which anyone is interested, immediately. | |
529 | ||
530 | These trigger activations will not be processed in the same dpkg run, | |
531 | to avoid unexpectedly processing triggers while attempting an | |
532 | unrelated operation. dpkg --configure --pending (and not other dpkg | |
533 | operations) will run the triggers, and the dpkg postinst will warn the | |
534 | user about the need to run it (if this deferred triggers condition | |
535 | exists). (Any triggers activated or reactivated *after* this | |
536 | mass-activation will be processed in the normal way.) | |
537 | ||
538 | To use this correctly: | |
539 | * Packages which are interested in triggers, or which want to | |
540 | explicitly activate triggers, should Depend on the | |
541 | triggers-supporting version of dpkg. | |
542 | * Update instructions and tools should arrange to run | |
543 | dpkg --configure --pending | |
544 | after the install; this will process the pending triggers. | |
545 | ||
546 | dpkg's prerm will check for attempts to downgrade while triggers are | |
547 | pending and refuse. (Since the new dpkg would be installed but then | |
548 | refuse to read the status file.) In case this is necessary a separate | |
549 | tool will be provided which will: | |
550 | * Put all packages with any pending triggers into state | |
551 | ‘config-failed’ and remove the list of pending triggers. | |
552 | * Remove the list of awaited triggers from every package. This | |
553 | may cause packages to go from ‘triggers-awaited’ to ‘installed’ | |
554 | which is not 100% accurate but the best that can be done. | |
555 | * Remove /var/lib/dpkg/triggers (to put the situation to that which | |
556 | we would have seen if the trigger-supporting dpkg had never been | |
557 | installed). | |
558 | ||
559 | ||
560 | Higher-level programs | |
561 | --------------------- | |
562 | ||
563 | The new dpkg will declare versioned Conflicts against apt and aptitude | |
564 | and other critical package management tools which will be broken by | |
565 | the new Status field values. Therefore, the new higher-level tools | |
566 | will have to be deployed first. | |
567 | ||
568 | The new dpkg will declare versioned Breaks against any known | |
569 | noncritical package management tools which will be broken by the new | |
570 | Status field value. | |
571 | ||
572 | ||
573 | Transition hints for existing packages | |
574 | -------------------------------------- | |
575 | ||
576 | When a central (consumer) package defines a directory where other leaf | |
577 | (producer) packages may place files and/or directories, and currently | |
578 | the producer packages are required to run an «update-consumer» script | |
579 | in their postinst: | |
580 | 1. In the relevant policy, define a trigger name which is the name of | |
581 | the directory where the individual files are placed by producer | |
582 | packages. | |
583 | 2. Update the consumer package: | |
584 | * Declare an interest in the trigger. | |
585 | * Edit «update-consumer» so that if it is called without --real | |
586 | it does the following: | |
587 | if type dpkg-trigger >/dev/null 2>&1 && \ | |
588 | dpkg-trigger name-of-trigger; then | |
589 | exit 0 | |
590 | fi | |
591 | If this fails to cause «update-consumer» to exit, it should do | |
592 | its normal update processing. Alternatively, if it is more | |
593 | convenient, «update-consumer» could be renamed and supplanted with | |
594 | a wrapper script which conditionally runs the real | |
595 | «update-consumer». | |
596 | * In the postinst, arrange for the new ‘triggered’ invocation to | |
597 | run «update-consumer --real». The consumer package's postinst | |
598 | will already run «update-consumer» during configuration, and this | |
599 | should be retained and supplemented with the --real option (or | |
600 | changed to call the real script rather than the wrapper). | |
601 | 3. Update the producer packages: | |
602 | * In the postinst, remove the call to «update-consumer». | |
603 | * Change the dependency on consumer to be versioned, specifying a | |
604 | trigger-interested consumer. | |
605 | This can be done at our leisure. Ideally for loosely coupled | |
606 | packages this would be done only in the release after the one | |
607 | containing the triggers-interested consumer, to facilitate partial | |
608 | upgrades and backports. | |
609 | 4. After all producer packages have been updated according to step 3, | |
610 | «update-consumer» has become an interface internal to the consumer | |
611 | and need no longer be kept stable. If un-updated producers are | |
612 | still of interest, incompatible changes to «update-consumer» imply | |
613 | a versioned Breaks against the old producers. | |
614 | (See also “Transition plan”, below.) | |
615 | ||
616 | If there are several consumer packages all of which are interested in | |
617 | the features provided by producer packages, the current arrangements | |
618 | usually involve an additional central switchboard package (eg, | |
619 | emacsen-common). In this case: | |
620 | ||
621 | -- NOTE - this part of the transition plan is still a proof of | |
622 | concept and we might yet improve on it | |
623 | ||
624 | 1. Define the trigger name. | |
625 | 2. Update the switchboard to have any new functionality needed by the | |
626 | consumers in step 3 (2nd bullet). | |
627 | 3. Update the consumer packages: | |
628 | * Declare an interest in the trigger. | |
629 | * In the postinst, arrange for the new ‘trigger’ invocation to run | |
630 | the compilation/registration process. This may involve scanning | |
631 | for new or removed producers, and may involve new common | |
632 | functionality from the switchboard (in which case a versioned | |
633 | Depends is needed). | |
634 | * The old interface allowing the switchboard to run | |
635 | compilation/registration should be preserved, including | |
636 | calls to the switchboard to register this consumer. | |
637 | 4. When all consumers have been updated, update the switchboard: | |
638 | * Make the registration scripts called by producers try to | |
639 | activate the trigger and if that succeeds quit without | |
640 | doing any work (as for bullet 2 in the simple case above). | |
641 | * Versioned Breaks, against the old (pre-step-3) consumers. | |
642 | 5. After the switchboard has been updated, producers can be updated: | |
643 | * Remove the calls to the switchboard registration/compilation | |
644 | functions. | |
645 | * Change the dependency on the switchboard to a versioned one, | |
646 | specifying the one which Breaks old consumers. Alternatively, | |
647 | it may be the case that the switchboard is no longer needed (or | |
648 | not needed for this producer), in which case the dependency on | |
649 | the switchboard can be removed in favour of an appropriate | |
650 | versioned Breaks (probably, identical to that in the new | |
651 | switchboard). | |
652 | 6. After all the producers have been updated, the cruft in the | |
653 | consumers can go away: | |
654 | * Remove the calls to the switchboard's registration system. | |
655 | * Versioned Breaks against old switchboards, or versioned Depends | |
656 | on new switchboards, depending on whether the switchboard is | |
657 | still needed for other common functionality. | |
658 | 7. After all of the producers and consumers have been updated, the | |
659 | cruft in the switchboard can go away: | |
660 | * Remove the switchboard's registration system (but not obviously | |
661 | the common functionality from step 3, discussed above). | |
662 | * Versioned Breaks against pre-step-6 consumers and pre-step-5 | |
663 | producers. | |
664 | ||
665 | ||
666 | DISCUSSION | |
667 | ========== | |
668 | ||
669 | The activation of a trigger does not record details of the activating | |
670 | event. For example, file triggers do not inform the package of the | |
671 | filename. In the future this might be added as an additional feature, | |
672 | but there are some problems with this. | |
673 | ||
674 | ||
675 | Broken producer packages, and error reporting | |
676 | --------------------------------------------- | |
677 | ||
678 | Often trigger processing will involve a central package registering, | |
679 | compiling or generally parsing some data provided by a leaf package. | |
680 | ||
681 | If the central package finds problems with the leaf package data it is | |
682 | usually more correct for only the individual leaf package to be | |
683 | recorded as not properly installed. There is not currently any way to | |
684 | do this and there are no plans to provide one. | |
685 | ||
686 | The naive approach of giving the postinst a list of the triggering | |
687 | packages does not work because this information is not recorded in the | |
688 | right way (it might suffer from lacunae); enhancing the bookkeeping | |
689 | for this to work would be possible but it is far better simply to make | |
690 | the system more idempotent. See above for the recommended approach. | |
691 | ||
692 | ||
693 | ||
694 | ||
695 | INTERNALS | |
696 | ========= | |
697 | ||
698 | On-disk state | |
699 | ------------- | |
700 | ||
701 | A single file /var/lib/dpkg/triggers/File lists all of the filename | |
702 | trigger interests in the form | |
703 | /path/to/directory/or/file package | |
704 | ||
705 | For each explicit trigger in which any package is interested, | |
706 | a file /var/lib/dpkg/triggers/<name-of-trigger> is a list of | |
707 | the interested packages, one per line. | |
708 | ||
709 | These interest files are not updated to remove a package just because | |
710 | a state change causes it not to be interested in any triggers any more | |
711 | - they are updated when we remove or unpack. | |
712 | ||
713 | For each package which has pending triggers, the status file contains | |
714 | a Triggers-Pending field which contains the space-separated names of | |
715 | the pending triggers. For each package which awaits triggers the | |
716 | status file contains a Triggers-Awaited field which contains the | |
717 | *package* names of the packages whose trigger processing is awaited. | |
718 | See “Details - Overview table” above for the invariants which relate | |
719 | Triggers-Pending, Triggers-Awaited, and Status. | |
720 | ||
721 | During dpkg's execution, /var/lib/dpkg/triggers/Unincorp is a list of | |
722 | the triggers which have been requested by dpkg-trigger but not yet | |
723 | incorporated in the status file. Each line is a trigger name followed | |
724 | by one or more triggering package names. The triggering package name | |
725 | "-" is used to indicate one or more package(s) which did not need to | |
726 | await the trigger. | |
727 | ||
728 | /var/lib/dpkg/triggers/Lock is the fcntl lockfile for the trigger | |
729 | system. Processes hang onto this lock only briefly: dpkg-trigger | |
730 | to add new activations, or dpkg to incorporate activations (and | |
731 | perhaps when it updates interests). Therefore this lock is always | |
732 | acquired with F_GETLKW so as to serialize rather than fail on | |
733 | contention. | |
734 | ||
735 | ||
736 | Processing | |
737 | ---------- | |
738 | ||
739 | dpkg-trigger updates triggers/Unincorp, and does not read or write the | |
740 | status file or take out the dpkg status lock. dpkg (and dpkg-query) | |
741 | reads triggers/Unincorp after reading /var/lib/dpkg/status, and after | |
742 | running a maintainer script. If the status database is opened for | |
743 | writing then the data from Unincorp is moved to updates as | |
744 | Triggers-Pending and Triggers-Awaited entries and corresponding Status | |
745 | changes. | |
746 | ||
747 | This means that dpkg is guaranteed to reincorporate pending trigger | |
748 | information into the status file only 1. when a maintainer script has | |
749 | finished, or 2. when dpkg starts up with a view to performing some | |
750 | operation. | |
751 | ||
752 | When a package is unpacked or removed, its triggers control file will | |
753 | be parsed and /var/lib/dpkg/triggers/* updated accordingly. | |
754 | ||
755 | Triggers are run as part of configuration. dpkg will try to first | |
756 | configure all packages which do not depend on packages which are | |
757 | awaiting triggers, and then run triggers one package at a time in the | |
758 | hope of making useful progress. (This will involve a new ‘dependtry’ | |
759 | level in configure.c's algorithm.) The only constraint on the | |
760 | ordering of postinsts is only the normal Depends constraint, so the | |
761 | usual Depends cycle breaking will function properly. See “Cycle | |
762 | detection” below regarding cycles in the “A triggers B” relation. | |
763 | ||
764 | ||
765 | Processing - Transitional | |
766 | ------------------------- | |
767 | ||
768 | The case where a triggers-supporting dpkg is run for the first time is | |
769 | detected by the absence of /var/lib/dpkg/triggers/Unincorp. When the | |
770 | triggers-supporting dpkg starts up without this it will set each | |
771 | package's list of pending triggers equal to its interests (obviously | |
772 | only for packages which are in ‘installed’ or ‘triggers-pending’). | |
773 | This may result in a package going from ‘installed’ to | |
774 | ‘triggers-pending’ but it will not create the directory at this time. | |
775 | Packages marked as triggers-pending in this way will not be scheduled | |
776 | for trigger processing in this dpkg run. | |
777 | ||
778 | dpkg will also at this time create /var/lib/dpkg/triggers if | |
779 | necessary, triggers/File, triggers/Unincorp, and the per-trigger | |
780 | package lists in /var/lib/dpkg/triggers/<trigger-name>, so that future | |
781 | trigger activations will be processed properly. | |
782 | ||
783 | Only dpkg may create /var/lib/dpkg/triggers and only when it is | |
784 | holding the overall dpkg status lock. | |
785 | ||
786 | dpkg and/or dpkg-deb will be made to reject packages containing | |
787 | Triggers-Pending and Triggers-Awaited control file fields, to prevent | |
788 | accidents. | |
789 | ||
790 | ||
791 | Cycle detection | |
792 | --------------- | |
793 | ||
794 | In addition to dependency cycles, triggers raise the possibility of | |
795 | mutually triggering packages - a cycle detectable only dynamically, | |
796 | which we will call a “trigger cycle”. | |
797 | ||
798 | Trigger cycles are detected using the usual hare-and-tortoise | |
799 | approach. Each time after dpkg runs a postinst for triggers, dpkg | |
800 | records the set of pending triggers (ie, the set of activated <pending | |
801 | package, trigger name> tuples). If the hare set is a superset of the | |
802 | tortoise set, a cycle has been found. | |
803 | ||
804 | For guaranteed termination, it would be sufficient to declare a cycle | |
805 | only when the two sets are identical, but because of the requirement | |
806 | to make progress we can cut this short. Formally, there is supposed | |
807 | to be a complete ordering of pending trigger sets satisfying the | |
808 | condition that any set of pending triggers is (strictly) greater than | |
809 | all its (strict) subsets. Trigger processing is supposed to | |
810 | monotonically decrease the set in this ordering. (The set elements | |
811 | are <package, trigger name> tuples.) | |
812 | ||
813 | (See “Processing” above for discussion of dependency cycles.) |