* 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. --- This patch adds documentation for the new wrapper command line options (which apply to both the wrapper /script/ and to the wrapper /executable/). However, because the options are of primary interest with respect to the wrapper exes, I've kept the documentation in the page specific for those, with a note that the script also supports the options.
In this patch series, I've kept the --lt-dump-script option for now, and even added support for that option to the wrapper script. I think the option is useful, and I agree that symmetry between w-script and w-exe is important. 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. There are four patches in this series: 1. Remove unneeded functions and options from cwrapper committed: 75765d58c38c55ef069ef100732c1e978f4151a6 2. [PATCH] Enable runtime cwrapper debugging; add tests http://lists.gnu.org/archive/html/libtool-patches/2009-06/msg00039.html pending... 3. [PATCH] Add --lt-* options to shell wrapper (just posted. Hasn't propagated to the archive yet, so no URL. Obviously, still pending...) 4. [PATCH] Document wrapper changes (this post. Obviously no URL yet, and also obviously pending...) Together, these four obsolete and (I hope) address all of the comments for [PATCH] Document and test LT_DEBUGWRAPPER cwrapper macro http://lists.gnu.org/archive/html/libtool-patches/2009-06/msg00031.html as well as addressing the comments recieved so far in review of #2. I'm posting #3 and #4 on the off chance that, for whatever reasons, approval for #2 has been held up waiting for these two promised patches. NEWS | 11 ++++++++ doc/libtool.texi | 69 ++++++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 78 insertions(+), 2 deletions(-) diff --git a/NEWS b/NEWS index 5a57891..64f27b6 100644 --- a/NEWS +++ b/NEWS @@ -12,6 +12,17 @@ New in 2.2.8 2009-??-??: git version 2.2.7a, Libtool team: - New libtool command line flag --no-verbose, which disables only the extra "verbose" output messages and has no effect on the default informational messages. + - 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 a7872c6..8fa6f59 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,70 @@ 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. + +Note that the wrapper, like the program, is an executable for the +host platform, not for the build platform. Therefore, the path to the +program executable must be expressed in the native format of the +host platform, not that of the build platform. Similarly, the environment +variable values --- and even the name of the specific environment +variables to adjust --- are specific to the host platform, and should be +in the host platform's expected format. For this reason, Libtool converts +paths for various combinations of host- and build- platform, where the +host platform is one of those for which a wrapper executable is needed. + +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 -- 1.6.3.2