command line tool to examine and set variables:
$ whenjobs --variables
- load=0.9
+ JOBSERIAL=297
+ libguestfs_build_local=1.17.16
+ libguestfs_commit=7e32d892d76a31f55e2a4151902623b9949e3efa
+ libguestfs_dist=1.17.16
+ libguestfs_release=1.17.16
+ libguestfs_stable_build_local=1.16.10
+ libguestfs_stable_commit=27433a0a335301441b1eb6244ba425c2c44b2d99
+ libguestfs_stable_dist=1.16.10
+ libguestfs_stable_release=1.16.10
+ libguestfs_stable_version=1.16.10
+ libguestfs_version=1.17.16
$ whenjobs --set cat=sushi
$ whenjobs --get cat
sushi
-The act of setting a variable (using I<--set>) can trigger jobs to run.
+Note: The act of setting a variable (using I<--set>) can trigger jobs
+to run.
+
+You can also list out what jobs are running:
+
+ $ whenjobs --jobs
+ 287 libguestfs-stable: fedora 16
+ running in: /tmp/whenjobsa2afc44fd757465f95438309f1a51609
+ started at: 2012-03-13 10:59:37
+
+and you can 'tail' the output of running jobs which is useful for
+debugging:
+
+ $ whenjobs --tail 287
+ Uploading: 147496271972717053d46b82a07435ca libguestfs-1.16.10.tar.gz
+
+You can start and cancel jobs manually:
+
+ $ whenjobs --start 'libguestfs: poll'
+ $ whenjobs --cancel 287
=head1 OPTIONS
Print the value of a variable.
+=item B<-help>
+
+=item B<--help>
+
+Display brief usage and exit.
+
=item B<--job-names>
List the names of all loaded jobs (whether they are running or not).
When using I<--type> and multiple variables, the type changes the
remaining command line parameters until the next I<--type>, eg:
- whenjobs --set cat=sushi --type float weight=3.5 --type string food=fish
+ whenjobs --set cat=sushi \
+ --type float weight=3.5 \
+ --type string food=fish
(C<cat> and C<food> are strings, and C<weight> is a float).
=item B<--test> variable=value [variable=value ...]
This works the same way as the I<--set> option, but the difference is
-that the variables are set. Instead, it lists out the jobs that
+that the variables are not set. Instead, it lists out the jobs that
I<would> run, I<if> the variables were updated to these new values.
The variables are not actually updated, and the jobs are not actually
=item B<--upload>
-Compile the jobs script and upload it to the daemon, without editing.
+Compile the jobs file(s) and upload it to the daemon, without editing.
Note that the I<--edit> option does this automatically. Furthermore,
when the daemon is started it checks for a jobs script and loads it if
found.
+See also L</MULTIPLE JOBS FILES> below.
+
=item B<--variables>
Display all the variables and their values, in the format C<name=value>.
Display the name and version of the program and exit.
-=item B<-help>
+=item B<--whisper> variable=value [variable=value ...]
-=item B<--help>
+This works the same way as the I<--set> option, but with the
+difference that jobs' when clauses are not reevaluated. In other
+words, the variables are set, but "quietly" so as not to trigger any
+jobs to run.
-Display brief usage and exit.
+Note that this can lead to some unexpected results: one case is a
+job such as:
+
+ when changed a || changed b : << ... >>
+
+If C<a> is changed using I<--whisper>, then the job will not run.
+
+But later on, if C<b> is set but to the same value that it already has
+(ie. not changed), the job will run because the whole when-clause is
+reevaluated and C<a> is found to have changed since the last run of
+the job.
=back
>>
where C<E<lt>exprE<gt>> is a I<when expression>, described below.
-Don't forget the colon character between the period expression and the
+Don't forget the colon character between the expression and the
shell script.
A when statement is a job which runs when the conditions described in
=back
+=head1 MULTIPLE JOBS FILES
+
+The whenjobs I<-e> and I<-l> options edit and list a file called
+C<$HOME/.whenjobs/jobs.ml>.
+
+You can also edit C<$HOME/.whenjobs/jobs.ml> by other means (eg. your
+own editor). After editing, to recompile and upload it, use:
+
+ whenjobs --upload
+
+When you have lots of jobs, it is convenient to split the jobs across
+multiple files. Any C<*.ml> files located in C<$HOME/.whenjobs> can
+be used (with some restrictions on filenames -- see below). These are
+compiled and loaded into the daemon using the I<--upload> command.
+
+To create multiple jobs files, you cannot use the I<-e> or I<-l>
+options. Instead you have to create them yourself in
+C<$HOME/.whenjobs>, and when you have finished creating or editing
+them, upload them.
+
+=head2 FILENAME RESTRICTIONS ON JOBS FILES
+
+In OCaml, a file called C<jobs.ml> corresponds to an OCaml module
+called C<Jobs> (note the capitalization). OCaml module names can only
+contain ASCII alphanumeric characters, underscore, and C<'> (single
+quote), and they must begin with an alphabetic character. The same
+rules apply to jobs files.
+
+Furthermore, various OCaml module names are reserved (eg. C<Map>,
+C<List>). It is therefore better to prefix any names with something
+specific to your application.
+
+Examples of legal filenames are:
+
+ foo.ml
+ app_foo.ml
+ app_123.ml
+ jobs.ml
+
+Examples of illegal filenames are:
+
+ ann.txt # must end with .ml
+ 123.ml # must begin with alphabetic
+ app!.ml # must contain alphanumeric or underscore
+ app-foo.ml # must contain alphanumeric or underscore
+ map.ml # reserved module name
+
=head1 FILES
git.annexia.org / whenjobs.git / blobdiff