branch master updated: libtool: Documentation refers to demo directory that no longer exists

[Ileana Dumitrescu]

This is an automated email from the git hooks/post-receive script.

ildumi pushed a commit to branch master
in repository libtool.

The following commit(s) were added to refs/heads/master by this push:
     new 7f254d96 libtool: Documentation refers to demo directory that no 
longer exists
7f254d96 is described below

commit 7f254d9682077a96452124859c8b7bd6e27c0691
Author: Ileana Dumitrescu <ileanadumitrescu95@gmail.com>
AuthorDate: Wed Mar 6 22:03:17 2024 +0200

    libtool: Documentation refers to demo directory that no longer exists
    
    The libtool documentation included mention of an old test framework.
    The documentation has been reworked to indicate the current test
    framework used by libtool, where the tests/*demo directories have been
    replaced with tests/*demo.at Autotest files.
    
    * doc/libtool.texi: Clarifies where the example files originate.
    * TODO: Remove TODO item related to tests/*demo directories.
---
 TODO             |   4 -
 doc/libtool.texi | 515 ++++++++-----------------------------------------------
 2 files changed, 70 insertions(+), 449 deletions(-)

diff --git a/TODO b/TODO
index 33b53353..0a10f699 100644
--- a/TODO
+++ b/TODO
@@ -124,10 +124,6 @@ GNU Libtool
 2.2. test suite
 ---------------
 
-* Rewrite the whole thing in Autotest.  This will enable us to remove
-  all the tests/*demo noise, and duplication; and thus speed up bootstrap
-  and make writing new tests a whole lot more pleasant.
-
 * We should include tests with reloadable objects in the testsuite.
 
 * Write a test case for linkage with gnu ld scripts (per 2004-08-25 patch
diff --git a/doc/libtool.texi b/doc/libtool.texi
index aa965888..000cf2f7 100644
--- a/doc/libtool.texi
+++ b/doc/libtool.texi
@@ -433,14 +433,19 @@ An Ultrix 4.2 platform with only static libraries.
 A NetBSD/i386 1.2 platform with shared libraries.
 @end table
 
-You can follow these examples on your own platform, using the
-preconfigured libtool script that was installed with libtool
-(@pxref{Configuring}).
+Source files for the following examples are taken from the Autotest file
+@file{tests/demo.at}.  The files can be extracted by running a demo test and
+preserving the artifacts:
 
-Source files for the following examples are taken from the @file{demo}
-subdirectory of the libtool distribution.  Assume that we are building a
-library, @file{libhello}, out of the files @file{foo.c} and
-@file{hello.c}.
+@example
+burger$ make check TESTSUITEFLAGS="-d -k 'preloaded static library'"
+burger$ cp -r tests/testsuite.dir/027 demo/
+@end example
+
+You can follow these examples on your own platform, using the preconfigured
+libtool script that was installed with libtool (@pxref{Configuring}).  Assume
+that we are building a library, @file{libhello}, out of the files @file{foo.c}
+and @file{hello.c}.
 
 Note that the @file{foo.c} source file uses the @code{cos} math library
 function, which is usually found in the standalone math library, and not
@@ -5179,435 +5184,27 @@ determine what the problem is, and how to resolve it.
 @section The libtool test suite
 @cindex test suite
 
-Libtool comes with two integrated sets of tests to check that your build
-is sane, that test its capabilities, and report obvious bugs in the
-libtool program.  These tests, too, are constantly evolving, based on
-past problems with libtool, and known deficiencies in other operating
-systems.
+Libtool comes with an integrated set of tests to check that your build is sane,
+that test its capabilities, and report obvious bugs in the libtool program.  
The
+test suite is based on Autotest from Autoconf (@pxref{testsuite Invocation, ,
+Generating Test Suites with Autotest, autoconf, The Autoconf Manual}).  These
+tests, too, are constantly evolving, based on past problems with libtool, and
+known deficiencies in other operating systems.
 
-As described in the @file{README} file, you may run @kbd{make -k check}
-after you have built libtool (possibly before you install it)
-to make sure that it meets basic functional requirements.
+As described in the @file{README} file, you may run @kbd{make -k check} after
+you have built libtool (possibly before you install it) to make sure that it
+meets basic functional requirements.
 
 @menu
-* Test descriptions::           The contents of the old test suite.
+* Test descriptions::           The contents of the test suite.
 * When tests fail::             What to do when a test fails.
 @end menu
 
 @node Test descriptions
 @subsection Description of test suite
 
-Here is a list of the current programs in the old test suite, and what
-they test for:
-
-@table @file
-
-@item cdemo-conf.test
-@itemx cdemo-make.test
-@itemx cdemo-exec.test
-@itemx cdemo-static.test
-@itemx cdemo-static-make.test
-@itemx cdemo-static-exec.test
-@itemx cdemo-shared.test
-@itemx cdemo-shared-make.test
-@itemx cdemo-shared-exec.test
-@itemx cdemo-undef.test
-@itemx cdemo-undef-make.test
-@itemx cdemo-undef-exec.test
-@pindex cdemo-conf.test
-@pindex cdemo-make.test
-@pindex cdemo-exec.test
-@pindex cdemo-static.test
-@pindex cdemo-static-make.test
-@pindex cdemo-static-exec.test
-@pindex cdemo-shared.test
-@pindex cdemo-shared-make.test
-@pindex cdemo-shared-exec.test
-@pindex cdemo-undef.test
-@pindex cdemo-undef-make.test
-@pindex cdemo-undef-exec.test
-These programs check to see that the @file{tests/cdemo} subdirectory of
-the libtool distribution can be configured and built correctly.
-
-The @file{tests/cdemo} subdirectory contains a demonstration of libtool
-convenience libraries, a mechanism that allows build-time static
-libraries to be created, in a way that their components can be later
-linked into programs or other libraries, even shared ones.
-
-The tests matching @file{cdemo-*make.test} and @file{cdemo-*exec.test}
-are executed three times, under three different libtool configurations:
-@file{cdemo-conf.test} configures @file{cdemo/libtool} to build both
-static and shared libraries (the default for platforms that support
-both), @file{cdemo-static.test} builds only static libraries
-(@samp{--disable-shared}), and @file{cdemo-shared.test} builds only
-shared libraries (@samp{--disable-static}).
-
-The test @file{cdemo-undef.test} tests the generation of shared
-libraries with undefined symbols on systems that allow this.
-
-@item demo-conf.test
-@itemx demo-make.test
-@itemx demo-exec.test
-@itemx demo-inst.test
-@itemx demo-unst.test
-@itemx demo-static.test
-@itemx demo-static-make.test
-@itemx demo-static-exec.test
-@itemx demo-static-inst.test
-@itemx demo-static-unst.test
-@itemx demo-shared.test
-@itemx demo-shared-make.test
-@itemx demo-shared-exec.test
-@itemx demo-shared-inst.test
-@itemx demo-shared-unst.test
-@itemx demo-nofast.test
-@itemx demo-nofast-make.test
-@itemx demo-nofast-exec.test
-@itemx demo-nofast-inst.test
-@itemx demo-nofast-unst.test
-@itemx demo-pic.test
-@itemx demo-pic-make.test
-@itemx demo-pic-exec.test
-@itemx demo-nopic.test
-@itemx demo-nopic-make.test
-@itemx demo-nopic-exec.test
-@pindex demo-conf.test
-@pindex demo-make.test
-@pindex demo-exec.test
-@pindex demo-inst.test
-@pindex demo-unst.test
-@pindex demo-static.test
-@pindex demo-static-make.test
-@pindex demo-static-exec.test
-@pindex demo-static-inst.test
-@pindex demo-static-unst.test
-@pindex demo-shared.test
-@pindex demo-shared-make.test
-@pindex demo-shared-exec.test
-@pindex demo-shared-inst.test
-@pindex demo-shared-unst.test
-@pindex demo-nofast.test
-@pindex demo-nofast-make.test
-@pindex demo-nofast-exec.test
-@pindex demo-nofast-inst.test
-@pindex demo-nofast-unst.test
-@pindex demo-pic.test
-@pindex demo-pic-make.test
-@pindex demo-pic-exec.test
-@pindex demo-nopic.test
-@pindex demo-nopic-make.test
-@pindex demo-nopic-exec.test
-These programs check to see that the @file{tests/demo} subdirectory of
-the libtool distribution can be configured, built, installed, and
-uninstalled correctly.
-
-The @file{tests/demo} subdirectory contains a demonstration of a trivial
-package that uses libtool.  The tests matching @file{demo-*make.test},
-@file{demo-*exec.test}, @file{demo-*inst.test} and
-@file{demo-*unst.test} are executed four times, under four different
-libtool configurations: @file{demo-conf.test} configures
-@file{demo/libtool} to build both static and shared libraries,
-@file{demo-static.test} builds only static libraries
-(@option{--disable-shared}), and @file{demo-shared.test} builds only
-shared libraries (@option{--disable-static}).
-@file{demo-nofast.test} configures @file{demo/libtool} to
-disable the fast-install mode (@option{--enable-fast-install=no}).
-@file{demo-pic.test} configures @file{demo/libtool} to
-prefer building PIC code (@option{--with-pic}), @file{demo-nopic.test}
-to prefer non-PIC code (@option{--without-pic}).
-
-@item demo-deplibs.test
-@pindex demo-deplibs.test
-Many systems cannot link static libraries into shared libraries.
-libtool uses a @code{deplibs_check_method} to prevent such cases.
-This tests checks whether libtool's @code{deplibs_check_method}
-works properly.
-
-@item demo-hardcode.test
-@pindex demo-hardcode.test
-On all systems with shared libraries, the location of the library can be
-encoded in executables that are linked against it @pxref{Linking
-executables}.  This test checks under what conditions your system
-linker hardcodes the library location, and guarantees that they
-correspond to libtool's own notion of how your linker behaves.
-
-@item demo-relink.test
-@itemx depdemo-relink.test
-@pindex demo-relink.test
-@pindex depdemo-relink.test
-These tests check whether variable @code{shlibpath_overrides_runpath} is
-properly set.  If the test fails, it will indicate what the variable should
-have been set to.
-
-@item demo-noinst-link.test
-@pindex demo-noinst-link.test
-Checks whether libtool will not try to link with a previously installed
-version of a library when it should be linking with a just-built one.
-
-@item depdemo-conf.test
-@itemx depdemo-make.test
-@itemx depdemo-exec.test
-@itemx depdemo-inst.test
-@itemx depdemo-unst.test
-@itemx depdemo-static.test
-@itemx depdemo-static-make.test
-@itemx depdemo-static-exec.test
-@itemx depdemo-static-inst.test
-@itemx depdemo-static-unst.test
-@itemx depdemo-shared.test
-@itemx depdemo-shared-make.test
-@itemx depdemo-shared-exec.test
-@itemx depdemo-shared-inst.test
-@itemx depdemo-shared-unst.test
-@itemx depdemo-nofast.test
-@itemx depdemo-nofast-make.test
-@itemx depdemo-nofast-exec.test
-@itemx depdemo-nofast-inst.test
-@itemx depdemo-nofast-unst.test
-@pindex depdemo-conf.test
-@pindex depdemo-make.test
-@pindex depdemo-exec.test
-@pindex depdemo-inst.test
-@pindex depdemo-unst.test
-@pindex depdemo-static.test
-@pindex depdemo-static-make.test
-@pindex depdemo-static-exec.test
-@pindex depdemo-static-inst.test
-@pindex depdemo-static-unst.test
-@pindex depdemo-shared.test
-@pindex depdemo-shared-make.test
-@pindex depdemo-shared-exec.test
-@pindex depdemo-shared-inst.test
-@pindex depdemo-shared-unst.test
-@pindex depdemo-nofast.test
-@pindex depdemo-nofast-make.test
-@pindex depdemo-nofast-exec.test
-@pindex depdemo-nofast-inst.test
-@pindex depdemo-nofast-unst.test
-These programs check to see that the @file{tests/depdemo} subdirectory
-of the libtool distribution can be configured, built, installed, and
-uninstalled correctly.
-
-The @file{tests/depdemo} subdirectory contains a demonstration of
-inter-library dependencies with libtool.  The test programs link some
-interdependent libraries.
-
-The tests matching @file{depdemo-*make.test}, @file{depdemo-*exec.test},
-@file{depdemo-*inst.test} and @file{depdemo-*unst.test} are executed
-four times, under four different libtool configurations:
-@file{depdemo-conf.test} configures @file{depdemo/libtool} to build both
-static and shared libraries, @file{depdemo-static.test} builds only static
-libraries (@option{--disable-shared}), and @file{depdemo-shared.test} builds
-only shared libraries (@option{--disable-static}).
-@file{depdemo-nofast.test} configures @file{depdemo/libtool} to
-disable the fast-install mode (@option{--enable-fast-install=no}).
-
-@item mdemo-conf.test
-@itemx mdemo-make.test
-@itemx mdemo-exec.test
-@itemx mdemo-inst.test
-@itemx mdemo-unst.test
-@itemx mdemo-static.test
-@itemx mdemo-static-make.test
-@itemx mdemo-static-exec.test
-@itemx mdemo-static-inst.test
-@itemx mdemo-static-unst.test
-@itemx mdemo-shared.test
-@itemx mdemo-shared-make.test
-@itemx mdemo-shared-exec.test
-@itemx mdemo-shared-inst.test
-@itemx mdemo-shared-unst.test
-@pindex mdemo-conf.test
-@pindex mdemo-make.test
-@pindex mdemo-exec.test
-@pindex mdemo-inst.test
-@pindex mdemo-unst.test
-@pindex mdemo-static.test
-@pindex mdemo-static-make.test
-@pindex mdemo-static-exec.test
-@pindex mdemo-static-inst.test
-@pindex mdemo-static-unst.test
-@pindex mdemo-shared.test
-@pindex mdemo-shared-make.test
-@pindex mdemo-shared-exec.test
-@pindex mdemo-shared-inst.test
-@pindex mdemo-shared-unst.test
-These programs check to see that the @file{tests/mdemo} subdirectory of
-the libtool distribution can be configured, built, installed, and
-uninstalled correctly.
-
-The @file{tests/mdemo} subdirectory contains a demonstration of a
-package that uses libtool and the system independent dlopen wrapper
-@file{libltdl} to load modules.  The library @file{libltdl} provides a
-dlopen wrapper for various platforms (POSIX)
-including support for dlpreopened modules (@pxref{Dlpreopening}).
-
-The tests matching @file{mdemo-*make.test}, @file{mdemo-*exec.test},
-@file{mdemo-*inst.test} and @file{mdemo-*unst.test} are executed
-three times, under three different libtool configurations:
-@file{mdemo-conf.test} configures @file{mdemo/libtool} to build both
-static and shared libraries, @file{mdemo-static.test} builds only static
-libraries (@option{--disable-shared}), and @file{mdemo-shared.test} builds
-only shared libraries (@option{--disable-static}).
-
-@item mdemo-dryrun.test
-@pindex mdemo-dryrun.test
-This test checks whether libtool's @option{--dry-run} mode works properly.
-
-@item mdemo2-conf.test
-@itemx mdemo2-exec.test
-@itemx mdemo2-make.test
-@pindex mdemo2-conf.test
-@pindex mdemo2-exec.test
-@pindex mdemo2-make.test
-These programs check to see that the @file{tests/mdemo2} subdirectory of
-the libtool distribution can be configured, built, and executed
-correctly.
-
-The @file{tests/mdemo2} directory contains a demonstration of a package
-that attempts to link with a library (from the @file{tests/mdemo}
-directory) that itself does dlopening of libtool modules.
-
-@item link.test
-@pindex link.test
-This test guarantees that linking directly against a non-libtool static
-library works properly.
-
-@item link-2.test
-@pindex link-2.test
-This test makes sure that files ending in @file{.lo} are never linked
-directly into a program file.
-
-@item nomode.test
-@pindex nomode.test
-Check whether we can actually get help for libtool.
-
-@item objectlist.test
-@pindex objectlist.test
-Check that a nonexistent objectlist file is properly detected.
-
-@item pdemo-conf.test
-@itemx pdemo-make.test
-@itemx pdemo-exec.test
-@itemx pdemo-inst.test
-@pindex pdemo-conf.test
-@pindex pdemo-make.test
-@pindex pdemo-exec.test
-@pindex pdemo-inst.test
-These programs check to see that the @file{tests/pdemo} subdirectory of
-the libtool distribution can be configured, built, and executed
-correctly.
-
-The @file{pdemo-conf.test} lowers the @code{max_cmd_len} variable in the
-generated libtool script to test the measures to evade command line
-length limitations.
-
-@item quote.test
-@pindex quote.test
-This program checks libtool's metacharacter quoting.
-
-@item sh.test
-@pindex sh.test
-Checks for some nonportable or dubious or undesired shell constructs in
-shell scripts.
-
-@item suffix.test
-@pindex suffix.test
-When other programming languages are used with libtool (@pxref{Other
-languages}), the source files may end in suffixes other than @file{.c}.
-This test validates that libtool can handle suffixes for all the file
-types that it supports, and that it fails when the suffix is invalid.
-
-@item tagdemo-conf.test
-@itemx tagdemo-make.test
-@itemx tagdemo-exec.test
-@itemx tagdemo-static.test
-@itemx tagdemo-static-make.test
-@itemx tagdemo-static-exec.test
-@itemx tagdemo-shared.test
-@itemx tagdemo-shared-make.test
-@itemx tagdemo-shared-exec.test
-@itemx tagdemo-undef.test
-@itemx tagdemo-undef-make.test
-@itemx tagdemo-undef-exec.test
-@pindex tagdemo-conf.test
-@pindex tagdemo-make.test
-@pindex tagdemo-exec.test
-@pindex tagdemo-static.test
-@pindex tagdemo-static-make.test
-@pindex tagdemo-static-exec.test
-@pindex tagdemo-shared.test
-@pindex tagdemo-shared-make.test
-@pindex tagdemo-shared-exec.test
-@pindex tagdemo-undef.test
-@pindex tagdemo-undef-make.test
-@pindex tagdemo-undef-exec.test
-These programs check to see that the @file{tests/tagdemo} subdirectory
-of the libtool distribution can be configured, built, and executed
-correctly.
-
-The @file{tests/tagdemo} directory contains a demonstration of a package
-that uses libtool's multi-language support through configuration tags.
-It generates a library from C++ sources, which is then linked to a C++
-program.
-
-@item f77demo-conf.test
-@itemx f77demo-make.test
-@itemx f77demo-exec.test
-@itemx f77demo-static.test
-@itemx f77demo-static-make.test
-@itemx f77demo-static-exec.test
-@itemx f77demo-shared.test
-@itemx f77demo-shared-make.test
-@itemx f77demo-shared-exec.test
-@pindex f77demo-conf.test
-@pindex f77demo-make.test
-@pindex f77demo-exec.test
-@pindex f77demo-static.test
-@pindex f77demo-static-make.test
-@pindex f77demo-static-exec.test
-@pindex f77demo-shared.test
-@pindex f77demo-shared-make.test
-@pindex f77demo-shared-exec.test
-These programs check to see that the @file{tests/f77demo} subdirectory
-of the libtool distribution can be configured, built, and executed
-correctly.
-
-The @file{tests/f77demo} tests test Fortran 77 support in libtool by
-creating libraries from Fortran 77 sources, and mixed Fortran and C
-sources, and a Fortran 77 program to use the former library, and a C
-program to use the latter library.
-
-@item fcdemo-conf.test
-@itemx fcdemo-make.test
-@itemx fcdemo-exec.test
-@itemx fcdemo-static.test
-@itemx fcdemo-static-make.test
-@itemx fcdemo-static-exec.test
-@itemx fcdemo-shared.test
-@itemx fcdemo-shared-make.test
-@itemx fcdemo-shared-exec.test
-@pindex fcdemo-conf.test
-@pindex fcdemo-make.test
-@pindex fcdemo-exec.test
-@pindex fcdemo-static.test
-@pindex fcdemo-static-make.test
-@pindex fcdemo-static-exec.test
-@pindex fcdemo-shared.test
-@pindex fcdemo-shared-make.test
-@pindex fcdemo-shared-exec.test
-These programs check to see that the @file{tests/fcdemo} subdirectory
-of the libtool distribution can be configured, built, and executed
-correctly.
-
-The @file{tests/fcdemo} is similar to the @file{tests/f77demo}
-directory, except that Fortran 90 is used in combination with the
-@samp{FC} interface provided by Autoconf and Automake.
 
-@end table
-
-The new, Autotest-based test suite uses keywords to classify certain
-test groups:
+The test suite uses keywords to classify certain test groups:
 
 @table @samp
 @item CXX
@@ -5659,32 +5256,60 @@ Windows.  Conversely, the target 
@samp{check-interactive} runs the
 complement of tests and might require closing popup windows about DLL
 load errors on Windows.
 
+Here is a list of the some of the current files in the test suite, and what
+they test for:
+
+@table @file
+
+@item @file{tests/cdemo.at}
+Tests include a demonstration of libtool convenience libraries, a mechanism 
that
+allows build-time static libraries to be created, in a way that their 
components
+can be later linked into programs or other libraries, even shared ones.
+
+@item @file{tests/demo.at}
+Tests include a demonstration of a trivial package that uses libtool.  The 
tests
+include scenarios to build both static and shared libraries, only static
+libraries, only shared libraries, disabling fast-install mode, building PIC
+code, and building non-PIC code.
+
+@item @file{tests/depdemo.at}
+Tests include a demonstration of inter-library dependencies with libtool.  The
+test programs link some interdependent libraries under different scenarios.
+
+@item @file{tests/mdemo.at}
+Tests include a demonstration of a package that uses libtool and the system
+independent dlopen wrapper @file{libltdl} to load modules.  The library
+@file{libltdl} provides a dlopen wrapper for various platforms (POSIX) 
including
+support for dlpreopened modules (@pxref{Dlpreopening}).
+
+@item @file{tests/tagdemo.at}
+Tests include a demonstration of a package that uses libtool's multi-language
+support through configuration tags.  It generates a library from C++ sources,
+which is then linked to a C++ program.
+
+@item @file{tests/f77demo.at}
+Tests test Fortran 77 support in libtool by creating libraries from Fortran 77
+sources, and mixed Fortran and C sources, and a Fortran 77 program to use the
+former library, and a C program to use the latter library.
+
+@item @file{tests/fcdemo.at}
+Tests are similar to the @file{tests/f77demo.at} tests, except that Fortran 90
+is used in combination with the @samp{FC} interface provided by Autoconf and
+Automake.
+
+@end table
 
 @node When tests fail
 @subsection When tests fail
 @cindex failed tests
 @cindex tests, failed
 
-When the tests in the old test suite are run via @command{make check},
-output is caught in per-test @file{tests/@var{test-name}.log} files
-and summarized in the @file{test-suite.log} file.  The exit status of each
-program tells the @file{Makefile} whether or not the test succeeded.
-
-If a test fails, it means that there is either a programming error in
-libtool, or in the test program itself.
-
-To investigate a particular test, you may run it directly, as you would
-a normal program.  When the test is invoked in this way, it produces
-output that may be useful in determining what the problem is.
-
-The new, Autotest-based test suite produces as output a file
-@file{tests/testsuite.log} that contains information about failed
-tests.
-
-You can pass options to the test suite through the @command{make}
-variable @env{TESTSUITEFLAGS} (@pxref{testsuite Invocation, ,
-The Autoconf Manual, autoconf, The Autoconf Manual}).
+The Autotest-based test suite produces as output a file
+@file{tests/testsuite.log} that contains information about failed tests.
 
+You can pass options to the test suite through the @command{make} variable
+@env{TESTSUITEFLAGS} (@pxref{testsuite Invocation, , Making testsuite Scripts,
+autoconf, The Autoconf Manual}).
 
 @node Reporting bugs
 @section Reporting bugs