added trigger docs

CVS patchset: 2050
CVS date: 1998/03/27 17:11:43

diff --git a/CHANGES b/CHANGES
index f37c13a..bd000ee 100644 (file)
--- a/CHANGES
+++ b/CHANGES
@@ -8,6 +8,7 @@
        - fixed many command line options which got broke by changes
          for non-gcc compilers
        - added trigger support in install code
+       - added doc/triggers
 
 2.4.103 -> 2.4.104:
        - fixed popt/Makefile.in to use CPP from configure

diff --git a/docs/triggers b/docs/triggers
new file mode 100644 (file)
index 0000000..d72dbd8
--- /dev/null
+++ b/docs/triggers
@@ -0,0 +1,115 @@
+TRIGGERS
+========
+
+Trigerrs provide a well-defined method for packages to interact with one
+another at package install and uninstall time. They are an extension
+of the normal installation scripts (i.e. %pre) which allows one package
+(the "source" of the trigger package [which I often think of as the 
+"triggered package"]) to execute an action when the installation status
+of another package (the "target" of the trigger) changes.
+
+A Simple Example
+----------------
+
+Say the package "mymailer" needs an /etc/mymailer/mailer symlink which points
+to the mail transport agent to use. If sendmail is installed, the link should
+point to /usr/bin/sendmail, but it vmail is installed, the link should 
+instead point to /usr/bin/vmail. If both packages are present, we don't care
+where the link points (realisticaly, sendmail and vmail should conflict
+with one another), while if neither package is installed the link should
+not exist at all.
+
+This can be accomplished by mymailer providing trigger scripts which 
+move the symlink when any of the following occurs:
+
+       1) sendmail is installed
+       2) vmail is installed
+       3) sendmail is removed
+       4) vmail is removed
+
+The first two of these scripts would look like this:
+
+       %triggerin -- sendmail
+       ln -sf /usr/bin/sendmail /etc/mymailer/mailer
+
+       %triggerin -- vmail
+       ln -sf /usr/bin/vmail /etc/mymailer/mailer
+
+These are two installation triggers, triggered by one of sendmail or vmail.
+They are run when:
+
+       1) mymailer is already installed, and sendmail is installed or
+          upgraded
+       2) mymailer is already installed, and vmail is installed or
+          upgraded
+       3) sendmail is already installed, and mymailer is installed or
+          upgraded
+       4) vmail is already installed, and mymailer is installed or
+          upgraded
+
+For the upgrading, the strategy is a little different. Rather then
+setting the link to point to the trigger, the link is set to point to
+the *other* mailer (if it exists), as follows:
+
+       %triggerun -- sendmail
+       [ $2 = 0 ] || exit 0
+       if [ -f /usr/bin/vmail ]; then
+               ln -sf /usr/bin/vmail /etc/mymailer/mailer
+       else
+               rm -f /etc/mymailer/mailer
+
+       fi
+
+       %triggerun -- vmail
+       [ $2 = 0 ] || exit 0
+       if [ -f /usr/bin/sendmail ]; then
+               ln -sf /usr/bin/sendmail /etc/mymailer/mailer
+       else
+               rm -f /etc/mymailer/mailer
+
+       fi
+
+       %postun
+       [ $1 = 0 ] && rm -f /etc/mymailer/mailer
+
+These trigger scripts get run when:
+
+       1) sendmail is installed, and mymailer is removed
+       2) vmail is installed, and mymailer is removed
+       3) mymailer is installed, and sendmail gets removed
+       4) mymailer is installed, and vmail gets removed
+
+The %postun insures that /etc/mymailer/mailer is removed when mymailer
+is removed (triggers get run at the same time as %preun scripts, so 
+doing this in the %postun is safe). Note that the triggers are testing
+$2 to see if any action should occur. Recall that the $1 passed to regular
+scripts contains the number of instances of the package which will be 
+installed when the operation has completed. $1 for triggers is exactly
+the same -- it is the number of instances of the source (or triggered)
+package which will remain when the trigger has completed. Similarly, $2
+is the number of instances of the target package which will remain. In
+this case, if any of the targets will remain after the uninstall, the
+trigger doesn't do anything (as it's probably being triggered by an
+upgrade).
+
+Trigger Syntax
+--------------
+
+Trigger specifications are of the form:
+
+       %trigger{un|in} {-n} {subpackage} {-p <program>} -- <trigger>
+
+The -n and -p arguments are the same as for %post scripts, except that
+only a single argument may be given to -p (for %post type scripts, a
+full command line, with arguments, may be specified). The <trigger>
+portion is syntactically equivalent to a "Requires" specification (version
+numbers may be used). If multiple items are given (comma separated), the
+trigger is run when *any* of those conditions becomes true (the , can be
+read as "or"). For example:
+
+       %triggerin -n package -p /usr/bin/perl -- fileutils > 3.0, perl < 1.2
+       print "I'm in my trigger!\n";
+
+Will put a trigger in package 'package' which runs when the installation
+status of either fileutils > 3.0 or perl < 1.2 is changed. The script will
+be run through /usr/bin/perl rather then /bin/sh (which is the default).