libtool-patches
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[PATCH] Document wrapper changes.


From: Charles Wilson
Subject: [PATCH] Document wrapper changes.
Date: Sun, 12 Jul 2009 18:49:06 -0400

* 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
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,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.
 
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.
+
+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
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
 
-- 
1.6.3.2





reply via email to

[Prev in Thread] Current Thread [Next in Thread]