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.
  37 Leading and trailing whitespace
  38 and everything after the first B<#> on any line will be trimmed, and
  39 empty lines will be ignored.
  40
  41 The trigger control directives currently supported are:
  42
  43 =over
  44
  45 =item B<interest> I<trigger-name>
  46
  47 =item B<interest-await> I<trigger-name>
  48
  49 =item B<interest-noawait> I<trigger-name>
  50
  51 Specifies that the package is interested in the named trigger.
  52 All
  53 triggers in which a package is interested must be listed using this
  54 directive in the triggers control file.
  55
  56 The “await” variants put the triggering package in triggers-awaited
  57 state depending on how the trigger was activated.
  58 The “noawait” variant does not put the triggering packages in
  59 triggers-awaited state, even if the triggering package declared an
  60 “await” activation (either with an B<activate-await> or B<activate>
  61 directive, or by using the B<dpkg-trigger> B<--no-await>
  62 command-line option).
  63 The “noawait” variant should be used when the functionality provided
  64 by the trigger is not crucial.
  65
  66 =item B<activate> I<trigger-name>
  67
  68 =item B<activate-await> I<trigger-name>
  69
  70 =item B<activate-noawait> I<trigger-name>
  71
  72 Arranges that changes to this package's state will activate the
  73 specified trigger.
  74 The trigger will be activated at the start of
  75 the following operations: unpack, configure, remove (including for
  76 the benefit of a conflicting package), purge and deconfigure.
  77
  78 The “await” variants only put the triggering package in triggers-awaited
  79 state if the interest directive is also “await”.
  80 The “noawait” variant never puts the triggering packages in
  81 triggers-awaited state.
  82 The “noawait” variant should be used when the functionality provided
  83 by the trigger is not crucial.
  84
  85 If this package disappears during the unpacking of another package
  86 the trigger will be activated when the disappearance is noted
  87 towards the end of the unpack.
  88 Trigger processing, and transition
  89 from triggers-awaited to installed, does not cause activations.
  90 In the case of unpack, triggers mentioned in both the old and new
  91 versions of the package will be activated.
  92
  93 =back
  94
  95 Unknown directives are an error which will prevent installation of the
  96 package.
  97
  98 The “-noawait” variants should always be favored when possible since
  99 triggering packages are not put in triggers-awaited state and can thus
 100 be immediately configured without requiring the processing of the trigger.
 101 If the triggering packages are dependencies of other upgraded packages,
 102 it will avoid an early trigger processing run and make it possible
 103 to run the trigger only once as one of the last steps of the upgrade.
 104
 105 The “-noawait” variants are supported since dpkg 1.16.1, and
 106 will lead to errors if used with an older dpkg.
 107
 108 The “-await” alias variants are supported since dpkg 1.17.21, and
 109 will lead to errors if used with an older dpkg.
 110
 111 When a package provides an B<interest-noawait> directive, any activation
 112 will set the triggering package into “noawait” mode, regardless of the
 113 awaiting mode requested by the activation (either “await” or “noawait”).
 114 When a package provides an B<interest> or B<interest-await> directive,
 115 any activation will set the triggering package into “await” or “noawait“
 116 depending on how it was activated.
 117
 118 =head1 SEE ALSO
 119
 120 L<dpkg-trigger(1)>,
 121 L<dpkg(1)>,
 122 B<%PKGDOCDIR%/spec/triggers.txt>.