X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/fc3419efe4d92bfa202543376995977c6a3171e9..7cf1204d999cb020c05709435c638a0d3b7924f4:/tools/tesh/tesh.1

diff --git a/tools/tesh/tesh.1 b/tools/tesh/tesh.1
index 38c1d4e8cd..3c55b70808 100644
--- a/tools/tesh/tesh.1
+++ b/tools/tesh/tesh.1
@@ -1,4 +1,8 @@
-.\" Manpage for tesh
+.\" Manpage for tesh, the TEsting SHell.
+.\" 
+.\" To read it locally (when not installed): 
+.\"   man ./tesh.1
+.\"
 .TH tesh 1 "10 Oct 2012" "1.0" "tesh man page"
 .SH NAME
 tesh \- testing shell
@@ -6,17 +10,19 @@ tesh \- testing shell
 .B tesh
 [\fIOPTION\fR]... [\fIFILE\fR]...
 .SH DESCRIPTION
-This is the TESH tool. It constitutes a testing shell, ie a sort of shell specialized to run tests. The list of actions to take is parsed from files files called testsuite. 
+This is the TESH tool. It constitutes a testing shell, ie a sort of shell specialized to run tests. The list of actions to take is parsed from files files called testsuite.
 .SH OPTIONS
-  --cd some/directory: ask tesh to switch the working directory before
-                       launching the tests
-  --setenv var=value: set a specific environment variable
+  --cd some/directory : ask tesh to switch the working directory before
+                        launching the tests
+  --setenv var=value  : set a specific environment variable
+  --cfg arg           : add parameter --cfg=arg to each command line
+  --enable-coverage   : ignore output lines starting with "profiling:"
 .SH TESH FILE SYNTAX
 Here is the syntax of these files:
 
 The kind of each line is given by the first char (the second char should be
 blank and is ignored):
- 
+
  `$' command to run in foreground
  `&' command to run in background
  `<' input to pass to the command
@@ -94,36 +100,49 @@ cannot timeout.
 .SH OUTPUT
 By default, the commands output is matched against the one expected,
 and an error is raised on discrepancy. Metacommands to change this:
- "output ignore"  -> output completely discarded 
+ "output ignore"  -> output completely discarded
  "output display" -> output displayed (but not verified)
  "output sort"    -> sorts the display before verifying it (see below)
 .SH SORTING OUTPUT
-Sorting the output seems to be a strange idea, but it is mandatory in
-SimGrid since the processes run out of order at any scheduling point
-(ie, every processes ready to run at simulated time t run in
-parallel). To ensure that the simulator outputs still match, we have
-to sort the output back before comparing it. 
-
-We expect the simulators to run with that log formatting argument:
-   -log=root.fmt:[%10.6r]%e(%i:%P@%h)%e%m%n
-Then, tesh sorts string on the 19 first chars only, and is stable when
-line beginnings are equal. This should ensure that:
- (1) tesh is effective (no false positive, no false negative)
- (2) scheduling points are separated from each other 
- (3) at each scheduling point, processes are separated from each other 
- (4) the order of what a given process says at a given scheduling
-     point is preserved.
-     
-This is of course very SimGrid oriented, breaking the generality of
-tesh, but who cares, actually?     
-
-If you want to change the length of the prefix used for the sort,
-simply specify it after the output sort directive, like this:
-
-! output sort 22
+
+SimGrid is designed to produce perfectly reproducible results, so its
+output can usualy be compared without any preprocessing. This is not
+true anymore when the user activates parallel execution: User
+processes are run in parallel at each timestamp, and the output is not
+reproducible anymore. Until you sort the lines.
+
+If you ask for 
+.B ! output sort
+then tesh will sort the whole lines. But it really complicates the
+analysis of the error detected: the logical order of the output is
+defeated by the lexicographical sort. 
+
+The solution is to ask for
+.B ! output sort 19
+instead to sort only on the prefix of the line. Indeed, we run our simulation
+tests with the flag: 
+  --log=root.fmt:[%10.6r]%e(%i:%P@%h)%e%m%n
+
+Then, the previous command sorts  lines on the first 19 chars, that is
+exactly the length of the prefix indicating the timestamp and the
+process. That's exactly what we need:
+ - Every timestamps remain separated, as it should; 
+ - In each timestamp, the output order of processes become
+   reproducible: that's the lexicographical order of their name;
+ - For each process, the order of its execution is preserved: its
+   messages within a given timestamp are not reordered.
+
+That way, tesh can do its job (no false positive, no false negative)
+despite the unpredictable order of executions of processes within a
+timestamp, and reported errors remain easy to analyze (execution of a
+given process preserved).
+
+This is of course very SimGrid oriented, but could even be usable by
+others, who knows?
+
 .SH ENVIRONMENT
 You can add some content to the tested processes environment with the
 setenv metacommand. It works as expected. For example:
   "setenv PATH=/bin"
 .SH BUGS
-No known bugs.
+No known bugs.