add libtool --mode=finish mode for sysroot

* doc/libtool.texi (Finish mode): Document behavior when *.la files
are passed.
* libltdl/config/ltmain.m4sh (func_mode_finish): Eliminate sysroot
or `=' signs representing it from files in $libs.
* tests/sysroot.at (SYSROOT_TESTS): Test for presence of sysroot
references before running libtool --mode=finish, and for absence
afterwards.

1 files changed, 12 insertions, 6 deletions

diff --git a/doc/libtool.texi b/doc/libtool.texi
index 914bd1d8..4b256bf0 100644
--- a/doc/libtool.texi
+++ b/doc/libtool.texi
@@ -1721,12 +1721,18 @@ commands are also completed.
 @cindex finish mode
 @cindex mode, finish
 
-@dfn{Finish} mode helps system administrators install libtool libraries
-so that they can be located and linked into user programs.
-
-Each @var{mode-arg} is interpreted as the name of a library directory.
-Running this command may require superuser privileges, so the
-@option{--dry-run} option may be useful.
+@dfn{Finish} mode has two functions.  One is to help system administrators
+install libtool libraries so that they can be located and linked into
+user programs.  To invoke this functionality, pass the name of a library
+directory as @var{mode-arg}.  Running this command may require superuser
+privileges, and the @option{--dry-run} option may be useful.
+
+The second is to facilitate transferring libtool libraries to a native
+compilation environment after they were built in a cross-compilation
+environment.  Cross-compilation environments may rely on recent libtool
+features, and running libtool in finish mode will make it easier to
+work with older versions of libtool.  This task is performed whenever
+the @var{mode-arg} is a @samp{.la} file.
 
 @node Uninstall mode
 @section Uninstall mode