@need 3200

@node Driving Process Automation with arch Hooks
@chapter Driving Process Automation with arch Hooks

In some circumstances, it is very useful to trigger actions upon the
detection of changes to an archive.  For example, you might want to
send an email notification whenever new revisions are checked in.


This process occurs through arch by use of hooks. Each time that arch
performs a command that modifies an archive, arch will attempt to 
run ~/.arch-params/hook, which must be set as executable.


Aguments given to the hook
        $1 : action performed (e.g. @geindex commit
@dfn{commit})


Environment Variables 

@need 3200

@section Arguments Given to hook

Whenever arch performs a command that affects an archive, arch will run 
hook with the first argument set as the action performed. If I user runs
a command (such as make-archive) then hook will be called multiple times
with multiple arguments (such as make-archive, make-category, make branch
and make-version)


The arguments that may be seen are: 


@noindent
import, commit, tag, make-archive, make-category, make-branch and
make-version.




@need 3200

@section Environment Variables Passed to hook

Tla also passes certain variables to the hook when appropriate. Variables
passed by Tla are prefaced with ARCH_. Variables that may be passed include:


Name            : ARCH_ARCHIVE
Description     : The archive involved in the action
Seen            : all actions
Example : lord@@emf.net--2003-example


Name            : ARCH_CATEGORY
Description     : Name of category created
Seen            : make-category
Example : hello-world


Name            : ARCH_BRANCH 
Description     : Name of branch being created
Seen            : make-branch
Example : mainline


Name            : ARCH_VERSION
Description     : Name of version being created
Seen            : make-version
Example : @code{0}.1


Name            : ARCH_REVISION
Descriptoin     : Name of revision involved
Seen            : import, tag, commit
Example : patch-6


Name            : ARCH_LOCATION
Description     : Location of archive being created
Seen            : make-archive 
Example : /usr/lord/@code{archives}/2003-example


Name            : ARCH_TREE_ROOT
Description     : 
Seen            : commit, import
Example : /home/lord/wd


Name            : ARCH_TAGGED_ARCHIVE 
Description     :
Seen            : tag
Example :


Name            : ARCH_TAGGED_REVISION
Description     : 
Seen            :
Example :




@need 3200

@section An Example of Using hook
@example
@group
     #!/bin/sh
@end group
@group
@end group
@end example
@example
@group
     if [ "$1" == "commit" ]; then
        tla push-mirror lord@@emf.net--2003-example \
           lord@@emf.net--2003-example-MIRROR;
        fi
@end group
@group
@end group
@end example



@need 3200

@section A more complex Examples of Using hook
@example
@group
     #!/bin/sh
@end group
@group
@end group
@end example
@example
@group
     case "$1" in
        commit)
           case "$ARCH_CATEGORY" in
              hello-world)
                 case "$ARCH_BRANCH" in
@end group
@group
                   mainline)
                        RELEASETYPE="stable"
@end group
@group
                   ;;
                   devel)
                      RELEASETYPE="unstable"
                   ;;
                   *)
@end group
@group
@end group
@end example
@example
@group
                 echo "The $RELEASETYPE version of Hello, World been upgraded. \
                    New versions are available at ftp.hello.com" |\
                    mailto hello-users@@hello.com -s "Hello upgraded"
              ;;
              goodbye-world)
@end group
@group
                 case "$ARCH_BRANCH" in
                   mainline)
                        RELEASETYPE="stable"
                   ;;
                   devel)
@end group
@group
                      RELEASETYPE="unstable"
                   ;;
                      RELEASETYPE="[unknown]"
                   *)
                 esac;
@end group
@group
                 echo "The stable version of Goodbye, Cruel World been upgraded. \
                    New versions are available at ftp.hello.com" |\
@end group
@group
                    mailto hello-users@@hello.com -s "Hello upgraded"
              ;;
            esac
        ;;
     esac
@end group
@group
@end group
@end example



@need 3200

@section Robustness Issues with hook

Unfortunately, some fundamental physical properties of the universe
make it impossible for arch to guarantee that hook will be
invoked only once for each new category, branch, version, or revision.
A (presumably rare) well timed interrupt or system failure can cause
@code{notify} to invoke actions more than once for a given change to the
archive. 


Consequently, actions should be designed to be robust against that
eventuality.


Additionally, if arch has been run concurrantly, then the hook may run
concurrantly as well. This means that projects using hook should take
care that hook is capable of running with simultaneous copies.







