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 address@hidden@value{objdir}} subdirectory. Then, a wrapper script was created -in the current directory. address@hidden@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. address@hidden +* Wrapper executables:: Wrapper executables for some platforms. address@hidden menu + address@hidden Wrapper executables address@hidden Wrapper executables for programs address@hidden wrapper executables for programs address@hidden 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 address@hidden 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: + address@hidden @option address@hidden --lt-dump-script +Causes the wrapper to print a copy of the wrapper @emph{script} +to @code{stdout}, and exit. + address@hidden --lt-debug +Causes the wrapper to print diagnostic information to @code{stdout}, +before launching the program executable. + address@hidden table + +For consistency, both the wrapper @emph{script} and the wrapper address@hidden support these options. + @node Debugging executables @section Debugging executables