X-Git-Url: http://git.annexia.org/?a=blobdiff_plain;f=tools%2Fwhenjobs.pod;h=acc1d9414d588639af62360bdaf2d0dc32a1dab8;hb=de72662854c3db9365296dd45cade2253910be7f;hp=85da381eaa671a288593e451dc1164fb77b0e5be;hpb=7724a64945c4f485780ed052de17793287e1935b;p=whenjobs.git diff --git a/tools/whenjobs.pod b/tools/whenjobs.pod index 85da381..acc1d94 100644 --- a/tools/whenjobs.pod +++ b/tools/whenjobs.pod @@ -79,12 +79,41 @@ Variables are stored (per-user) in the daemon. You can use the 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 @@ -127,6 +156,12 @@ C is used. 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). @@ -186,7 +221,9 @@ operation. 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 and C are strings, and C is a float). @@ -215,11 +252,13 @@ The output is a list of job names that would run. =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 below. + =item B<--variables> Display all the variables and their values, in the format C. @@ -230,11 +269,24 @@ Display all the variables and their values, in the format C. 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 +when job such as: + + when changed a || changed b : << ... >> + +If C is changed using I<--whisper>, then the job will not run. + +But later on, if C 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 is found to have changed since the last run of +the job. =back @@ -810,6 +862,53 @@ fields: =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 corresponds to an OCaml module +called C (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, +C). 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