man/deb-triggers.pod

   1 # dpkg manual page - deb-triggers(5)
   2 #
   3 # Copyright © 2008, 2013-2015 Guillem Jover <guillem@debian.org>
   4 # Copyright © 2011, 2014 Raphaël Hertzog <hertzog@debian.org>
   5 #
   6 # This is free software; you can redistribute it and/or modify
   7 # it under the terms of the GNU General Public License as published by
   8 # the Free Software Foundation; either version 2 of the License, or
   9 # (at your option) any later version.
  10 #
  11 # This is distributed in the hope that it will be useful,
  12 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 # GNU General Public License for more details.
  15 #
  16 # You should have received a copy of the GNU General Public License
  17 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
  18
  19 =encoding utf8
  20
  21 =head1 NAME
  22
  23 deb-triggers - package triggers
  24
  25 =head1 SYNOPSIS
  26
  27 B<debian/triggers>, B<debian/>I<binary-package>B<.triggers>,
  28 B<DEBIAN/triggers>
  29
  30 =head1 DESCRIPTION
  31
  32 A package declares its relationship to some trigger(s) by including
  33 a I<triggers> file in its control archive (i.e. I<DEBIAN/triggers>
  34 during package creation).
  35
  36 This file contains directives, one per line. Leading and trailing whitespace
  37 and everything after the first B<#> on any line will be trimmed, and
  38 empty lines will be ignored.
  39
  40 The trigger control directives currently supported are:
  41
  42 =over
  43
  44 =item B<interest> I<trigger-name>
  45
  46 =item B<interest-await> I<trigger-name>
  47
  48 =item B<interest-noawait> I<trigger-name>
  49
  50 Specifies that the package is interested in the named trigger. All
  51 triggers in which a package is interested must be listed using this
  52 directive in the triggers control file.
  53
  54 The “await” variants put the triggering package in triggers-awaited
  55 state depending on how the trigger was activated.
  56 The “noawait” variant does not put the triggering packages in
  57 triggers-awaited state, even if the triggering package declared an
  58 “await” activation (either with an B<activate-await> or B<activate>
  59 directive, or by using the B<dpkg-trigger> B<--no-await>
  60 command-line option).
  61 The “noawait” variant should be used when the functionality provided
  62 by the trigger is not crucial.
  63
  64 =item B<activate> I<trigger-name>
  65
  66 =item B<activate-await> I<trigger-name>
  67
  68 =item B<activate-noawait> I<trigger-name>
  69
  70 Arranges that changes to this package's state will activate the
  71 specified trigger. The trigger will be activated at the start of
  72 the following operations: unpack, configure, remove (including for
  73 the benefit of a conflicting package), purge and deconfigure.
  74
  75 The “await” variants only put the triggering package in triggers-awaited
  76 state if the interest directive is also “await”.
  77 The “noawait” variant never puts the triggering packages in
  78 triggers-awaited state.
  79 The “noawait” variant should be used when the functionality provided
  80 by the trigger is not crucial.
  81
  82 If this package disappears during the unpacking of another package
  83 the trigger will be activated when the disappearance is noted
  84 towards the end of the unpack. Trigger processing, and transition
  85 from triggers-awaited to installed, does not cause activations.
  86 In the case of unpack, triggers mentioned in both the old and new
  87 versions of the package will be activated.
  88
  89 =back
  90
  91 Unknown directives are an error which will prevent installation of the
  92 package.
  93
  94 The “-noawait” variants should always be favored when possible since
  95 triggering packages are not put in triggers-awaited state and can thus
  96 be immediately configured without requiring the processing of the trigger.
  97 If the triggering packages are dependencies of other upgraded packages,
  98 it will avoid an early trigger processing run and make it possible
  99 to run the trigger only once as one of the last steps of the upgrade.
 100
 101 The “-noawait” variants are supported since dpkg 1.16.1, and
 102 will lead to errors if used with an older dpkg.
 103
 104 The “-await” alias variants are supported since dpkg 1.17.21, and
 105 will lead to errors if used with an older dpkg.
 106
 107 When a package provides an B<interest-noawait> directive, any activation
 108 will set the triggering package into “noawait” mode, regardless of the
 109 awaiting mode requested by the activation (either “await” or “noawait”).
 110 When a package provides an B<interest> or B<interest-await> directive,
 111 any activation will set the triggering package into “await” or “noawait“
 112 depending on how it was activated.
 113
 114 =head1 SEE ALSO
 115
 116 B<dpkg-trigger>(1),
 117 B<dpkg>(1),
 118 B<%PKGDOCDIR%/spec/triggers.txt>.