whenjobs initial version.

[whenjobs.git] / README

diff --git a/README b/README
new file mode 100644 (file)
index 0000000..d3444ef
--- /dev/null
+++ b/README
@@ -0,0 +1,87 @@
+Whenjobs is a powerful but simple cron replacement.
+
+Two key advantages over cron are a simpler syntax for writing rules
+and a powerful dependency system that lets one job depend on variables
+set when other jobs run (allowing, for example, one job to run only
+when another job has finished successfully).
+
+Below is an example whenjobs script so you can get a feel for the
+language.  Read the whenjobs(1) man page for full information.
+
+  ----------------------------------------------------------------------
+  (* Every 10 minutes, get the latest tagged version from the
+   * git repository.  The variable 'tag' will be set to something
+   * like "v1.2.3", "v1.2.4", etc over time as new releases get
+   * tagged.
+   *)
+  every 10 minutes :
+  <<
+    cd /my/git/repo
+    tag=`git-describe --tags`
+    whenjobs --set version $tag
+  >>
+
+  (* When the 'version' variable changes (ie. a new release is
+   * tagged) try to build it.  'changes' is a function that compares
+   * the previous value of a variable from when this job last ran
+   * with the current value of a variable, and returns true if the
+   * previous and current values are different.
+   *)
+  when changes version :
+  <<
+    cd /my/git/buildrepo
+    git pull
+    git reset --hard $version
+    ./configure
+    make clean all check dist
+    whenjobs --set successful_local_build $version
+  >>
+
+  (* In parallel, build on a remote machine. *)
+  when changes version :
+  <<
+    ssh remote ./do_build $version
+    whenjobs --set successful_remote_build $version
+  >>
+
+  (* Only when the new release has been successfully built on local
+   * and remote, upload it to the website.
+   *)
+  when successful_local_build == version &&
+       successful_remote_build == version:
+  <<
+    cd /my/git/buildrepo
+    curl -T name-$success.tar.gz ftp://ftp.example.com/upload/
+  >>
+  ----------------------------------------------------------------------
+
+To get started with whenjobs, edit your script:
+
+  whenjobs -e
+
+or list the current script:
+
+  whenjobs -l
+
+You must run 'whenjobsd' (the whenjobs daemon) as the local user.
+Each user must run their own daemon.  You can query the state of the
+daemon of start it using the whenjobs command line tool:
+
+  whenjobs --daemon-start
+  whenjobs --daemon-status
+  whenjobs --daemon-stop
+
+If you want the daemon to start when the machine is booted, add the
+following line to /etc/rc.local (replace 'username' with your
+username):
+
+  su username -c /usr/sbin/whenjobsd
+
+Whenjobs is an open source project distributed under the GNU General
+Public License, version 2 or at your option any later version.  Read
+the file 'COPYING' for the full license.
+
+The home page is:
+http://people.redhat.com/~rjones/whenjobs
+
+Send patches or suggestions to Richard Jones <rjones@redhat.com>.