Fix error message; arguments were swapped around.
[whenjobs.git] / README
1 Whenjobs is a powerful but simple cron replacement.
2
3 Two key advantages over cron are a simpler syntax for writing rules
4 and a powerful dependency system that lets one job depend on variables
5 set when other jobs run (allowing, for example, one job to run only
6 when another job has finished successfully).
7
8 Below is an example whenjobs script so you can get a feel for the
9 language.  Read the whenjobs(1) man page for full information.
10
11   ----------------------------------------------------------------------
12   (* Every 10 minutes, get the latest tagged version from the
13    * git repository.  The variable 'version' will be set to something
14    * like "v1.2.3", "v1.2.4", etc over time as new releases get
15    * tagged.
16    *)
17   every 10 minutes :
18   <<
19     cd /my/git/repo
20     tag=`git-describe --tags`
21     whenjobs --set version $tag
22   >>
23
24   (* When the 'version' variable changes (ie. a new release is
25    * tagged) try to build it.  'changes' is a function that compares
26    * the previous value of a variable from when this job last ran
27    * with the current value of a variable, and returns true if the
28    * previous and current values are different.
29    *)
30   when changes version :
31   <<
32     cd /my/git/buildrepo
33     git pull
34     git reset --hard $version
35     ./configure
36     make clean all check dist
37     whenjobs --set successful_local_build $version
38   >>
39
40   (* In parallel, build on a remote machine. *)
41   when changes version :
42   <<
43     ssh remote ./do_build $version
44     whenjobs --set successful_remote_build $version
45   >>
46
47   (* Only when the new release has been successfully built on local
48    * and remote, upload it to the website.
49    *)
50   when successful_local_build == version &&
51        successful_remote_build == version:
52   <<
53     cd /my/git/buildrepo
54     curl -T name-$success.tar.gz ftp://ftp.example.com/upload/
55   >>
56   ----------------------------------------------------------------------
57
58 To get started with whenjobs, edit your script:
59
60   whenjobs -e
61
62 or list the current script:
63
64   whenjobs -l
65
66 You must run 'whenjobsd' (the whenjobs daemon) as the local user.
67 Each user must run their own daemon.  You can query the state of the
68 daemon of start it using the whenjobs command line tool:
69
70   whenjobs --daemon-start
71   whenjobs --daemon-status
72   whenjobs --daemon-stop
73
74 If you want the daemon to start when the machine is booted, add the
75 following line to /etc/rc.local (replace 'username' with your
76 username):
77
78   su username -c /usr/sbin/whenjobsd
79
80 Whenjobs is an open source project distributed under the GNU General
81 Public License, version 2 or at your option any later version.  Read
82 the file 'COPYING' for the full license.
83
84 The home page is:
85 http://people.redhat.com/~rjones/whenjobs
86
87 Send patches or suggestions to Richard Jones <rjones@redhat.com>.