2010-02-21 Charles Wilson <...>
Document wrapper changes.
* NEWS: Indicate new feature and incompatibility.
* doc/libtool.texi [Linking executables]: Mention wrapper
executables, in addition to wrapper scripts. Add menu
referencing subsection 'Wrapper executables for programs'.
[Wrapper executables for programs]: New subsection. Documents
cwrapper rationale and command line options.
NEWS | 11
doc/libtool.texi | 59
2 files changed, 68 insertions(+), 2 deletions(-)
This is slightly modified from the version here:
http://lists.gnu.org/archive/html/libtool-patches/2009-07/msg00015.html
because I've removed some verbiage describing path-translation logic. As
the 'cwrapper cross compile support' patch hasn't yet been committed,
the wrapper doesn't yet DO path-translation, so that's a bit premature.
I've saved that documentation, and will combine it with the
cross-compile patch when we get to that point.
>> However, Ralf said:
>>> I'd consider documenting --lt-dump-script the cementation of
>>> a bad API.
>> So, as a compromise we could could modify this documentation patch
>> to just not /document/ that option, while retaining all the other
>> documentation/discussion of the w-exe and the --lt-debug option.
>
> More discussion of this, please? I'm certainly willing to update the
> patch, but...I need a go/no-go.
72 hour clock...
This is currently being tested in conjunction with two other patches;
will report results in a consolidated separate message.
--
Chuck
diff --git a/NEWS b/NEWS
index d41db5e..61638fd 100644
--- a/NEWS
+++ b/NEWS
@@ -16,6 +16,17 @@ New in 2.2.8 2010-??-??: git version 2.2.7a, Libtool team:
runs on Windows with popup windows in the middle, and `check-interactive'
for the complement set of tests.
- New link mode flag -bindir to specify the location for installed PE DLLs.
+ - Wrapper scripts and wrapper executables for programs linked against
+ uninstalled shared libraries now support command-line options --lt-debug
+ and --lt-dump-script.
+
+* Important incompatible changes:
+
+ - The wrapper command line option support described above introduces the
+ following incompatibility: the wrapper will remove any command line
+ options that begin with '--lt-*' from the argument list before launching
+ (uninstalled) programs. Any '--lt-*' option on the command line not
+ recognized by the wrapper will result in an error.
* Changes in supported systems or compilers:
diff --git a/doc/libtool.texi b/doc/libtool.texi
index 482e635..aa29db8 100644
--- a/doc/libtool.texi
+++ b/doc/libtool.texi
@@ -790,8 +790,9 @@ Note that libtool added the necessary run-time path flag, as well as
@cindex wrapper scripts for programs
@cindex program wrapper scripts
Notice that the executable, @code{hell}, was actually created in the
-...@file{@value{objdir}} subdirectory. Then, a wrapper script was created
-in the current directory.
+...@file{@value{objdir}} subdirectory. Then, a wrapper script (or, on
+certain platforms, a wrapper executable @pxref{Wrapper executables}) was
+created in the current directory.
Since libtool created a wrapper script, you should use libtool to
install it and debug it too. However, since the program does not depend
@@ -845,6 +846,60 @@ price of being dynamic is eight kilobytes, and the payoff is about four
kilobytes. So, having a shared @file{libhello} won't be an advantage
until we link it against at least a few more programs.
+...@menu
+* Wrapper executables:: Wrapper executables for some platforms.
+...@end menu
+
+...@node Wrapper executables
+...@subsection Wrapper executables for programs
+...@cindex wrapper executables for programs
+...@cindex program wrapper executables
+
+Some platforms, notably those hosted on Windows such as Cygwin
+and MinGW, use a wrapper executable rather than a wrapper script
+to ensure proper operation of programs linked by libtool against
+uninstalled shared libraries. The wrapper executable thus performs
+the same function as the wrapper script used on other platforms, but
+allows to satisfy the @command{make} rules for the program, whose
+name ends in @code{$(EXEEXT)}. The actual program executable is
+created below @value{objdir}, and its name will end in @code{$(EXEEXT)}
+and may or may not contain an @code{lt-} prefix. This wrapper
+executable sets various environment values so that the program
+executable may locate its (uninstalled) shared libraries, and then
+launches the program executable.
+
+The wrapper executable provides a debug mode, enabled by passing the
+command-line option @code{--lt-debug} (see below). When executing in
+debug mode, diagnostic information will be printed to @code{stderr}
+before the program executable is launched.
+
+Finally, the wrapper executable supports a number of command line
+options that may be useful when debugging the operation of the wrapper
+system. All of these options begin with @code{--lt-}, and if present
+they and their arguments will be removed from the argument list passed
+on to the program executable. Therefore, the program executable may not
+employ command line options that begin with @code{--lt-}. (In fact, the
+wrapper executable will detect any command line options that begin with
+...@code{--lt-} and abort with an error message if the option is not
+recognized). If this presents a problem, please contact the Libtool
+team at @email{bug-libtool@@gnu.org}.
+
+These command line options include:
+
+...@table @option
+...@item --lt-dump-script
+Causes the wrapper to print a copy of the wrapper @emph{script}
+to @code{stdout}, and exit.
+
+...@item --lt-debug
+Causes the wrapper to print diagnostic information to @code{stdout},
+before launching the program executable.
+
+...@end table
+
+For consistency, both the wrapper @emph{script} and the wrapper
+...@emph{executable} support these options.
+
@node Debugging executables
@section Debugging executables
