diff --git a/ChangeLog b/ChangeLog index 6dde890..9d8ced9 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,17 @@ 2010-02-21 Charles Wilson <...> + Document wrapper changes. + * NEWS: Indicate new feature and incompatibility. + * doc/libtool.texi [detailmenu]: Add reference to subsection + 'Wrapper executables for programs', in Platform Quirks category. + [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. + +2010-02-21 Charles Wilson <...> + Add --lt-* options to shell wrapper * libltdl/config/ltmain.m4sh (func_emit_wrapper): Call func_parse_lt_options early. Use func_exec_program. 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..8a191df 100644 --- a/doc/libtool.texi +++ b/doc/libtool.texi @@ -212,6 +212,7 @@ Platform quirks * Reloadable objects:: Binding object files together. * Multiple dependencies:: Removing duplicate dependent libraries. * Archivers:: Programs that create static archives. +* Wrapper executables:: Wrapper executables for some platforms. @end detailmenu @end menu @@ -790,8 +791,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 +847,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 uninstalled programs address@hidden wrapper executables for uninstalled 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 uninstalled 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