Re: patch-7: README.alpha update

[Ralf Wildenhues]

Hi Gary,

* Gary V. Vaughan wrote on Wed, Dec 14, 2005 at 02:00:55PM CET:
> Ralf Wildenhues wrote:
> >6 wasn't the last one then..
> 
> ;-)  There is never a last one! :-p

Nope.  The last couple of weeks have also re-filled the queue of
things-yet-to-fix..

> >* Ralf Wildenhues wrote on Sun, Dec 04, 2005 at 03:56:15PM CET:
> >
> >> README/README.alpha updates on how to use the new testsuite, and
> >> how to report failures it may show,
> >
> >OK to apply?
> 
> With one nit fixed:
> 
>   - I guess you don't use emacs?  Can you refill at column 72 to
>     match the rest of the files before you commit please?

Hmm.  To avoid me hitting this ever again, can I add vi(m) modelines 
to the files (README, README.alpha, ChangeLog)?  Does the emacs variable
stuff:

> $ tail -n 4 README
> Local Variables:
> mode: text
> fill-column: 72
> End:

have to be right at the end?  At most N lines away from it?  (modelines
search is adjustable; default I believe is 5 first and 5 last lines).

Applied the patch fixed as shown below.

Cheers,
Ralf

        * README.alpha (Reporting bugs): Suggest to also bootstrap the
        libltdl subdirectory -- the Makefile will enforce it anyway.
        (The Test Suite): Renamed to..
        (The Test Suites): ..this.  Introduce the new Autotest test
        suite, how to run each one individually, and what to report.
        * README (The Test Suite): Likewise.

Index: README
===================================================================
RCS file: /cvsroot/libtool/libtool/README,v
retrieving revision 1.22
diff -u -r1.22 README
--- README      4 Dec 2005 14:40:43 -0000       1.22
+++ README      16 Dec 2005 16:49:11 -0000
@@ -28,55 +28,77 @@
 2. Reporting Bugs
 =================
 
-If you have any suggestions or bug reports, or you wish to port
-libtool to a new platform, please send electronic mail to the libtool
-mailing list <address@hidden> or bug reports to <address@hidden>.
-Be sure to send us your information from the end of the help message
-given by `./libtool --help'.
+If you have any suggestions or bug reports, or you wish to port libtool
+to a new platform, please send electronic mail to the libtool mailing
+list <address@hidden> or bug reports to <address@hidden>.  Be sure
+to send us your information from the end of the help message given by
+`./libtool --help'.
+
+
+3. The Test Suites
+==================
+
+Libtool comes with two integrated sets of tests to check that your build
+is sane.  You can run both test suites like this:
+
+  make check TESTSUITE_FLAGS=-V
+  make check-local
+
+The tests of the old test suite run in groups in the various demo
+subdirectories, so if one of the tests early in a group FAILs, the rest
+of the tests in that group will be SKIPped.  If you see a FAIL further
+into a group, even if a test with the same name PASSes in another test
+group, you need to take note of the name of the first test in the group
+if you want to rerun the group with FAILures to get verbose output.
+
+To run a test group of the old test suite in isolation (say, you think
+you have fixed a bug, but don't want to rerun the entire suite), you can
+do it like this:
 
+  make check TESTS='cdemo-static.test cdemo-make.test cdemo-exec.test' \
+            TESTSUITE_FLAGS=-V
 
-3. The Test Suite
-=================
+Providing that you have a FAIL from the most recent group from a
+particular demo directory (like the cdemo-static.test group above), you
+can explore the state of the directory to help with debugging.
 
-Libtool comes with an integrated set of tests to check that your build
-is sane.  You can run the entire suite like this:
+If you wish to report a test group failure to the libtool list, you need
+to send the verbose output of the FAILing group, along with the
+information from the end of `$(top_builddir)/libtool --help' to the bug
+report mailing list, <address@hidden> with a subject line that
+includes the string `[TEST FAILURE]'.  From a Bourne compatible shell,
+you can generate verbose test output like this:
 
-  make check
+  VERBOSE=yes make check \
+  TESTS='cdemo-static.test cdemo-make.test cdemo-exec.test' \
+  TESTSUITE_FLAGS=-V | tee cdemo-static-group.log
 
-The tests run in groups in the various demo subdirectories, so if one
-of the tests early in a group FAILs, the rest of the tests in that
-group will be SKIPPED.  If you see a FAIL further into a group, even
-if a test with the same name PASSes in another test group, you need to
-take note of the name of the first test in the group if you want to
-rerun the group with FAILures to get verbose output.
+In order to enable debug shell tracing, use VERBOSE=debug instead of
+VERBOSE=yes.
 
-To run a test group in isolation (say, you think you have fixed a bug,
-but don't want to rerun the entire suite), you can do it like this:
 
-  make check TESTS='cdemo-static.test cdemo-make.test cdemo-exec.test'
+In the long run, Libtool will move to using only the new,
+Autotest-driven testsuite.  Its usage is documented in
 
-Providing that you have a FAIL from the most recent group from a
-particular demo directory (like the cdemo-static.test group above), you
-can explore the state of the directory to help with debugging.
+  info Autoconf 'testsuite Invocation'
 
-If you wish to report a test group failure to the libtool list, you
-need to send the verbose output of the FAILing group, along with the
-information from the end of `$(top_builddir)/libtool --help' to the
-bug report mailing list, <address@hidden>.  From a Bourne
-compatible shell, you can generate verbose test output like this:
+but simple help may also be obtained through
 
-  VERBOSE=yes make check \
-  TESTS='cdemo-static.test cdemo-make.test cdemo-exec.test' \
-  | tee cdemo-static-group.log
+  make check-local TESTSUITE_FLAGS='--help'
+
+For verbose output, add the flag `-v', for running only a subset of the
+independent tests, merely specify them by number or by keyword, both of
+which are displayed with the `--list' flag.
 
-In order to enable debug shell tracing, use VERBOSE=debug
-instead of VERBOSE=yes.
+If you wish to report test failures to the libtool list, you need to
+send the file `tests/testsuite.log' to the bug report mailing list,
+<address@hidden>.
 
 4. Version Numbering
 ====================
 
-People have complained that they find the version numbering scheme
-under which libtool is released confusing... so we've changed it!
+People have complained that they find the version numbering scheme under
+which libtool is released confusing... so we've changed it!
 
 It works like this:
 
Index: README.alpha
===================================================================
RCS file: /cvsroot/libtool/libtool/README.alpha,v
retrieving revision 1.5
diff -u -r1.5 README.alpha
--- README.alpha        4 Dec 2005 14:40:43 -0000       1.5
+++ README.alpha        16 Dec 2005 16:49:11 -0000
@@ -16,21 +16,21 @@
 2. Reporting Bugs
 =================
 
-If this distribution doesn't work for you, before you report the problem,
-please try upgrading to the latest version from CVS first:
+If this distribution doesn't work for you, before you report the
+problem, please try upgrading to the latest version from CVS first:
 
   export CVS_RSH=ssh
   cvs -z3 -d :ext:address@hidden:/cvsroot/libtool co libtool
   cd libtool
   ./bootstrap
 
-The `bootstrap' script sets up the source directory for you to hack, though
-it may take quite some time to run.  To use it, you need a recent (maybe yet
-to be released) version of both Autoconf and Automake.  If you don't
-intend to run the test suite, you can speed up the `bootstrap' step by
-an order of magnitude if you call it like this instead:
+The `bootstrap' script sets up the source directory for you to hack,
+though it may take quite some time to run.  To use it, you need a recent
+(maybe yet to be released) version of both Autoconf and Automake.  If
+you don't intend to run the test suite, you can speed up the `bootstrap'
+step by an order of magnitude if you call it like this instead:
 
-  reconfdirs=. ./bootstrap
+  reconfdirs='. libltdl' ./bootstrap
 
 If your bug is not fixed in the latest version, please send a full
 report to <address@hidden>, including the information from the end
@@ -38,25 +38,28 @@
 of any failed test groups (as described below).
 
 
-3. The Test Suite
-=================
+3. The Test Suites
+==================
 
-Libtool comes with an integrated set of tests to check that your build
-is sane.  You can run the entire suite like this:
+Libtool comes with two integrated sets of tests to check that your build
+is sane.  You can run both test suites like this:
 
-  make check
+  make check TESTSUITE_FLAGS=-V
+  make check-local
 
-The tests run in groups in the various demo subdirectories, so if one
-of the tests early in a group FAILs, the rest of the tests in that
-group will be SKIPPED.  If you see a FAIL further into a group, even
-if a test with the same name PASSes in another test group, you need to
-take note of the name of the first test in the group if you want to
-rerun the group with FAILures to get verbose output.
+The tests of the old test suite run in groups in the various demo
+subdirectories, so if one of the tests early in a group FAILs, the rest
+of the tests in that group will be SKIPped.  If you see a FAIL further
+into a group, even if a test with the same name PASSes in another test
+group, you need to take note of the name of the first test in the group
+if you want to rerun the group with FAILures to get verbose output.
+
+To run a test group of the old test suite in isolation (say, you think
+you have fixed a bug, but don't want to rerun the entire suite), you can
+do it like this:
 
-To run a test group in isolation (say, you think you have fixed a bug,
-but don't want to rerun the entire suite), you can do it like this:
-
-  make check TESTS='cdemo-static.test cdemo-make.test cdemo-exec.test'
+  make check TESTS='cdemo-static.test cdemo-make.test cdemo-exec.test' \
+            TESTSUITE_FLAGS=-V
 
 Providing that you have a FAIL from the most recent group from a
 particular demo directory (like the cdemo-static.test group above), you
@@ -71,10 +74,28 @@
 
   VERBOSE=yes make check \
   TESTS='cdemo-static.test cdemo-make.test cdemo-exec.test' \
-  | tee cdemo-static-group.log
+  TESTSUITE_FLAGS=-V | tee cdemo-static-group.log
+
+In order to enable debug shell tracing, use VERBOSE=debug instead of
+VERBOSE=yes.
+
+
+In the long run, Libtool will move to using only the new,
+Autotest-driven testsuite.  Its usage is documented in
+
+  info Autoconf 'testsuite Invocation'
+
+but simple help may also be obtained through
+
+  make check-local TESTSUITE_FLAGS='--help'
+
+For verbose output, add the flag `-v', for running only a subset of the
+independent tests, merely specify them by number or by keyword, both of
+which are displayed with the `--list' flag.
 
-In order to enable debug shell tracing, use VERBOSE=debug
-instead of VERBOSE=yes.
+If you wish to report test failures to the libtool list, you need to
+send the file `tests/testsuite.log' to the bug report mailing list,
+<address@hidden>.
 
 -- 
 Copyright (C) 2004 Free Software Foundation, Inc.