Francois Gouget : winetest: Move the scripts documentation to the usage message.

Alexandre Julliard julliard at winehq.org
Mon Apr 12 16:11:19 CDT 2021


Module: tools
Branch: master
Commit: f71c9c67285218933537f768be6741b7e64acb1e
URL:    https://source.winehq.org/git/tools.git/?a=commit;h=f71c9c67285218933537f768be6741b7e64acb1e

Author: Francois Gouget <fgouget at codeweavers.com>
Date:   Mon Apr 12 11:16:25 2021 +0200

winetest: Move the scripts documentation to the usage message.

Signed-off-by: Francois Gouget <fgouget at codeweavers.com>
Signed-off-by: Alexandre Julliard <julliard at winehq.org>

---

 winetest/build-index | 34 +++++++++++++++++---------
 winetest/dissect     | 69 +++++++++++++++++++++++++++++-----------------------
 winetest/gather      | 60 +++++++++++++++++++++++++--------------------
 3 files changed, 95 insertions(+), 68 deletions(-)

diff --git a/winetest/build-index b/winetest/build-index
index 94453f4..01533c4 100755
--- a/winetest/build-index
+++ b/winetest/build-index
@@ -1,6 +1,7 @@
 #!/usr/bin/perl
 #
 # Copyright 2008 Alexandre Julliard <julliard at winehq.org>
+# Copyright 2014-2021 Francois Gouget
 #
 # This library is free software; you can redistribute it and/or
 # modify it under the terms of the GNU Lesser General Public
@@ -15,9 +16,6 @@
 # You should have received a copy of the GNU Lesser General Public
 # License along with this library; if not, write to the Free Software
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
-#
-# This program creates the global index of all the builds for which we have
-# WineTest result data.
 
 use strict;
 use warnings;
@@ -175,14 +173,28 @@ if (defined $usage)
         error("try '$name0 --help' for more information\n");
         exit $usage;
     }
-    print "Usage: $name0 [--workdir DIR] [--help]\n";
-    print "\n";
-    print "Processes the build summaries to generate the global index.\n";
-    print "\n";
-    print "Where:\n";
-    print "  --workdir DIR   Specifies the directory containing the winetest website\n";
-    print "                  files.\n";
-    print "  --help          Shows this usage message.\n";
+    print <<EOF;
+Usage: $name0 [--workdir DIR] [--help]
+
+Processes the build summaries to generate the global index and per-test
+index pages.
+
+Where:
+  --workdir DIR     Specifies the directory containing the winetest website
+                    files. Can be omitted if set in winetest.conf.
+  --help            Shows this usage message.
+
+Actions:
+  $name0 should be called after the gather script has updated all the builds.
+
+Generated files:
+  \$workdir/data/index.html
+  \$workdir/data/tests/TEST:UNIT.html
+
+Exit:
+  0 - success
+  2 - usage error
+EOF
     exit 0;
 }
 
diff --git a/winetest/dissect b/winetest/dissect
index 43b2754..d6ce316 100755
--- a/winetest/dissect
+++ b/winetest/dissect
@@ -2,7 +2,7 @@
 #
 # Copyright (C) 2004 Ferenc Wagner
 # Copyright (C) 2008 Alexandre Julliard
-# Copyright (C) 2017, 2019 Francois Gouget
+# Copyright (C) 2008-2021 Francois Gouget
 #
 # This library is free software; you can redistribute it and/or
 # modify it under the terms of the GNU Lesser General Public
@@ -17,25 +17,6 @@
 # You should have received a copy of the GNU Lesser General Public
 # License along with this library; if not, write to the Free Software
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
-#
-# This program looks for a WineTest report file matching queue/rep*/report,
-# takes it apart in its directory while also creating summary.txt. If an error
-# occurs the directory is renamed to errXXXXX to avoid future attempts at
-# processing this report.
-# If everything goes flawlessly the whole directory is renamed (based on the
-# information learned in the process) to data/BUILD/VERSION_TAG_DIGIT
-# where DIGIT is for resolving name clashes and data/BUILD/outdated is
-# created to signal the change in the given build.
-#
-# To test this script:
-# - Put a test report in queue/rep1/report
-# - Run ./dissect
-# - Examine the result in data/
-#
-# Exit: 0 - successfully processed a report, call again
-#       1 - failed to process a report, call again
-#       2 - there was nothing to do
-#       3 - fatal error, something went utterly wrong
 
 use strict;
 use warnings;
@@ -183,16 +164,44 @@ if (defined $usage)
         error("try '$name0 --help' for more information\n");
         exit $usage;
     }
-    print "Usage: $name0 [--workdir DIR] [--update REPORT] [--help]\n";
-    print "\n";
-    print "Processes a test report to generate the corresponding HTML files.\n";
-    print "\n";
-    print "Where:\n";
-    print "  --workdir DIR   Specifies the directory containing the winetest website\n";
-    print "                  files.\n";
-    print "  --update REPORT Updates the HTML files of the specified test report. Note that\n";
-    print "                  it must have already been moved into place.\n";
-    print "  --help          Shows this usage message.\n";
+    print <<EOF;
+Usage: $name0 [--workdir DIR] [--update REPORT] [--help]
+
+Processes a test report to generate the corresponding HTML files.
+
+Where:
+  --workdir DIR     Specifies the directory containing the winetest website
+                    files. Can be omitted if set in winetest.conf.
+  --update REPORT   Updates the HTML files of the specified test report. Note
+                    that it must have already been moved into place.
+  --help            Shows this usage message.
+
+Actions:
+  $name0 looks for a WineTest report file matching queue/rep*/report,
+  takes it apart in its directory while also creating summary.txt. If an error
+  occurs the directory is renamed to errXXXXX to avoid future attempts at
+  processing this report.
+
+  If everything goes flawlessly the whole directory is renamed (based on the
+  information learned in the process) to data/BUILD/PLATFORM_TAG_DIGIT
+  where DIGIT is for resolving name clashes and data/BUILD/outdated is
+  created to signal the change in the given build.
+
+Generated files:
+  \$workdir/queue/errXXXXX/error
+  \$workdir/queue/errXXXXX/summary.txt
+  or
+  \$workdir/data/BUILD/outdated
+  \$workdir/data/BUILD/PLATFORM_TAG_DIGIT/summary.txt
+  \$workdir/data/BUILD/PLATFORM_TAG_DIGIT/report.html
+  \$workdir/data/BUILD/PLATFORM_TAG_DIGIT/TEST:UNIT.html
+
+Exit:
+  0 - successfully processed a report, call again
+  1 - failed to process a report, call again
+  2 - there was nothing to do or usage error
+  3 - fatal error, something went utterly wrong
+EOF
     exit 0;
 }
 
diff --git a/winetest/gather b/winetest/gather
index 79bea91..1a61b0c 100755
--- a/winetest/gather
+++ b/winetest/gather
@@ -1,6 +1,7 @@
 #!/usr/bin/perl
 #
 # Copyright (C) 2004 Ferenc Wagner
+# Copyright (C) 2008-2021 Francois Gouget
 #
 # This library is free software; you can redistribute it and/or
 # modify it under the terms of the GNU Lesser General Public
@@ -15,24 +16,6 @@
 # You should have received a copy of the GNU Lesser General Public
 # License along with this library; if not, write to the Free Software
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
-#
-# This program looks for builds that have received new reports. These are
-# identified by the presence of a file matching data/*/outdated.
-# It then creates an index.html file in the same directory and removes the
-# outdated file.
-#
-# It is thus intended to run as a second stage invoked by the winetest.cron
-# script. Races and concurrency problems must be dealt with on that higher
-# level.
-#
-# To test this script:
-# - After running dissect, run ./gather
-# - Examine the result in data/
-#
-# Exit: 0 - successfully processed a build, call again
-#       1 - should not happen
-#       2 - there was nothing to do
-#       3 - fatal error, something went utterly wrong
 
 use strict;
 use warnings;
@@ -265,15 +248,38 @@ if (defined $usage)
         error("try '$name0 --help' for more information\n");
         exit $usage;
     }
-    print "Usage: $name0 [--workdir DIR] [--update BUILDDIR] [--help]\n";
-    print "\n";
-    print "Processes a build's report summaries to create the build's index files.\n";
-    print "\n";
-    print "Where:\n";
-    print "  --workdir DIR     Specifies the directory containing the winetest website\n";
-    print "                    files.\n";
-    print "  --update BUILDDIR Updates the HTML files of the specified build directory.\n";
-    print "  --help          Shows this usage message.\n";
+    print <<EOF;
+Usage: $name0 [--workdir DIR] [--update BUILD] [--help]
+
+Identifies one build that received new reports and updates its summary and
+HTML index files.
+
+Where:
+  --workdir DIR     Specifies the directory containing the winetest website
+                    files. Can be omitted if set in winetest.conf.
+  --update BUILD    Forcefully refreshes the specified build directory.
+                    BUILD should be a full path. If an outdated file is
+                    present, it is removed.
+  --help            Shows this usage message.
+
+Actions:
+  The build to process is identified by the presence of the data/*/outdated
+  file generated by the dissect script. That file is removed after all
+  processing is done. It is up to the caller to invoke $name0 as many times as
+  necessary and to deal with any concurrency issues.
+
+Generated files:
+  \$workdir/data/BUILD/summary.txt
+  \$workdir/data/BUILD/total.txt
+  \$workdir/data/BUILD/index.html
+  \$workdir/data/BUILD/index_GROUP.html
+
+Exit:
+  0 - successfully processed a build, call again
+  1 - should not happen
+  2 - there was nothing to do or usage error
+  3 - fatal error, something went utterly wrong
+EOF
     exit 0;
 }
 




More information about the wine-cvs mailing list