[Xen-devel] [OSSTEST PATCH 04/15] sg-run-job: Document run-ts and spawn-ts argument syntaxes

[Ian Jackson <ian.jackson@xxxxxxxxxxxxx>]

Signed-off-by: Ian Jackson <Ian.Jackson@xxxxxxxxxxxxx>
---
v2: More accurate explanation of ! in IFFAIL; and mention $ok.
---
 sg-run-job | 97 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 97 insertions(+)

diff --git a/sg-run-job b/sg-run-job
index 4b98e2b..b820642 100755
--- a/sg-run-job
+++ b/sg-run-job
@@ -146,6 +146,103 @@ proc testid_matches_globs {testid globs} {
 
 #---------- test script handling ----------
 
+#   spwan-ts    IFFAIL TESTID SCRIPT-ARGS...
+#
+#       Spawns the test script as a test step, and leaves it running.
+#       Returns token to pass to reap-ts.
+#
+#   reap-ts     TOKEN [WANTSTATUS]
+#
+#       Waits for the test script to finish.
+#
+#       The step status is set to "pass" (if the script exits zero) or
+#       IFFAIL (otherwise).  (But it is not set if the script,
+#       or something else, already set it to "aborted" or "broken".)
+#
+#       Return value is true if that step status matches the glob
+#       WANTSTATUS (which defaults to "pass").  Test failures do not
+#       become Tcl exceptions and do not affect other test execution.
+#
+#   run-ts      IFFAIL TESTID SCRIPT-ARGS...
+#
+#       Runs the test script, waiting for it to finish.
+#       The step status is set as for reap-ts.
+#
+#       If that step status is not "pass", throws a Tcl exception.
+#
+#       Normally (eg, within the recipe), an exception causes the job
+#       to be stopped as a failure (and proceed to log collection).
+#       Specifically:
+#               "ok" is set to "0" (which prevents most other
+#                    general steps from running)
+#               The job status is set to IFFAIL.
+#
+#   per-host-ts IFFAIL TESTID SCRIPT-ARGS...
+#
+#       Runs the script (as a separate step) for each test host ident.
+#       The host ident is appended to SCRIPT-ARGS.  (SCRIPT-ARGS
+#       should contain an even number of + items for proper testid
+#       generation.)
+#
+#       The scripts are run in parallel for all host idents.
+#
+#       If any of the step statuses is not "pass", sets the job
+#       status to IFFAIL and stops the job as a failure (as above).
+#
+#       per-host-ts does nothing if the job is no longer $ok
+#       (subject to IFFAIL starting with !, see below)
+#
+#  IFFAIL can be
+#
+#           [-][!].
+#           [-][!]STATUS
+#
+#       where STATUS is the job/step status to be used if the step
+#       status is not as expected, and the special meanings are:
+#
+#           -      Only for run-ts; suprresses exception on failure.
+#           !      Run this even if the job is being truncated.
+#                  (for per-host-ts, even if the job is no longer $ok)
+#           .      Shorthand for "fail"
+#
+#  TESTID specifies the unique ID for this test step.
+#
+#       The testid must be unique within the job; but for steps which
+#       actual tests (ie, which might be subject to regression
+#       analsysis, or bisection) must be stable - ie, it must not
+#       change due to races nor due to future osstest changes.
+#       Normally this is acheived by computing it from the
+#       SCRIPT-ARGS by specifying something involving "=" or "/@".
+#
+#       TESTID is processed with some substitutions (in this order):
+#
+#       =   at the start is replaced with "SCRIPTBASIS/@"
+#           where SCRIPTBASIS is the first entry in SCRIPT-ARGS
+#           with ts- removed.
+#
+#       *   as the whole TESTID is replaced with "SCRIPTBASIS/@(*)"
+#       
+#       /@  anywhere is replaced with "/ARG/ARG..."
+#           (ie, "/ARG" for each ARG in SCRIPT-ARGS after the
+#           script name, but see note about "+" in SCRIPT-ARGS,
+#           below.)
+#
+#       (*) at the end is replaced by (STEPNO)
+#           where STEPNO is the step number within the job (which
+#           is unique within the job, but not stable).
+#
+#  SCRIPT-ARGS is the script name and its arguments, but is also
+#  subject to some special processing:
+#
+#       The script name should not include the ./ which is necessary
+#       to find the script in the current directory.  This will be
+#       added implicitly.
+#
+#       An argument which is precisely "+" toggles whether the
+#       subsequent items in SCRIPT-ARGS are added to the expansion of
+#       /@ in TESTID.  (The "+" itself is not added to the arguments
+#       or the testid.)
+
 proc run-ts {iffail args} {
     set wantstatus pass
     if {[regsub {^-} $iffail {} iffail]} { set wantstatus * }
-- 
2.1.4


_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
https://lists.xen.org/xen-devel