Re: [PATCH] Document and test LT_DEBUGWRAPPER cwrapper macro

[Ralf Wildenhues]

Hello Charles,

* Charles Wilson wrote on Fri, Jun 19, 2009 at 07:55:03PM CEST:
> * tests/cwrapper.test: Add new test for -DLT_DEBUGWRAPPER.
> * 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, command line options, and LT_DEBUGWRAPPER
> macro.
> ---
> A repost of this patch:
> http://lists.gnu.org/archive/html/libtool-patches/2009-01/msg00168.html
> 
> FWIW, I plan to expand on the [Wrapper executables for programs]
> documentation after (assuming) the cross-compile stuff goes in.
> 
> Now there has been some reluctance about this patch in the past;
> presumably worry about documenting the --lt- options somehow cements
> them as an API that must be forever supported

Yes, this is a problem.

> (and also perhaps
> because the wrapper *script* doesn't support these options, so
> why have arg differences between the two wrapper implementations?)

Yes, this is another problem.  We should not add to platform specific
semantics more than necessary.  As long as the environment variable
flags are not supported everywhere, or the wrapper is not created for
executables that don't link against uninstalled libraries (are they?),
they should not be documented.  Or we even take them out.

Taking them out would be ok with me.  If you do it, be sure to do it in
a separate commit so that they can be re-added if/when they are
supported for all uninstalled programs on all systems.

>   1) remove all of those bits from the documentation
>   2) only document the --lt-dump-script option

What should --lt-dump-script be documented for?  What use do you
consider this useful for a libtool user?

I'd consider documenting --lt-dump-script the cementation of a bad API.
This shouldn't be needed by the user, and it encourages more platform-
specific code on the user end.

>   3) remove all those bits, AND remove their implementation
>      a) might be troublesome as --lt-dump-script is quite useful,
>         AND we still use it explicitly within libtool
>   4) only document the --lt-dump-script-option, AND remove
>      the implementations of the other --lt- options.
>   5) Add a blurb to the documentation that "--lt- options to
>      the cwrapper are unstable and subject to change".
>   6) Add all --lt-* "implementations" to the wrapper script
>   7) Add --lt-dump-script "implementation" to the wrapper script
> If changes to this patch must be made, then I lean towards #2 or #5.
> #4 might also be ok, since those functions haven't proven useful over
> the past year, plus it would shrink the size of ltmain.sh quite a bit.

> --- 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.

OK.

> @@ -845,6 +846,97 @@ 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 certain platforms.

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 win32 such as cygwin

Windows (see standards.info for a rationale)
Cygwin

> +and mingw, use a wrapper executable rather than a wrapper script. It

MinGW

> +performs the same function, but is necessary so that @code{make}

@command{make}

> +rules for target executables (whose names end in @code{$(EXEEXT)})
> +are satisfied. Recall that the actual target executable is created
> +in @value{objdir} as @address@hidden/program_name.exe} on

This fact is an implementation detail.  I think it is ok to document it,
but only with the addition that it is an implementation detail and may
be changed.  When an uninstalled program is executed, it might actually
end up being .libs/lt-PROGRAM$EXEEXT that is being executed, for example
(I don't think this happens on w32, but then again, this is not
something that we want to promise, or not promise).  It is something
that users detect when printing argv[0], of course.

> +these platforms.  If a wrapper script were used, then the build
> +directory would contain @code{program_name}, @emph{not} 
> @code{program_name.exe}.
> +Thus, @code{make} would never believe that the target executable had
> +been created, leading to continual and useless relinking.  (We could
> +name the wrapper script @code{program_name.exe} on these platforms, but it
> +is not a good idea to lie to win32 in this way).

Please don't write what we could do, and what would happen.  Just write
what happens.  For example, I'd write above as

  ...
  and MinGW, use a wrapper executable rather than a wrapper script. It
  performs the same function, but allows to satisfy the @command{make}
  rules for the target executable, which ends in @code{$(EXEEXT)}.
  The actual target executable is created below @value{objdir}, its name
  will end in @code{$(EXEEXT)} and may or may not contain an @code{lt-}
  prefix.

and remove the rest of the paragraph.

> +Therefore, these platforms use a wrapper executable to set various
> +environment values so that the target executable may locate its
> +shared libraries. The wrapper executable then launches the target
> +executable using a (possibly $host-dependent) function, such as
> +exec() or _spawn().

Why is this important for the user?

> +Note that the wrapper executable, like the target executable, is a
> +$host program, not a $build program. Therefore, the path to the
> +target executable must be expressed in the native format of the
> +$host, not that of $build. Similarly, the environment variable
> +values --- and even the name of the specific environment variables
> +to adjust --- are $host-specific and should be in $host, not $build,
> +format. For this reason, libtool contains a number of path and
> +pathlist conversion functions for various $host/$build combinations,
> +where $host is one of those platforms where a wrapper executable is
> +needed.

But this paragraph isn't completely true either.

> +Obviously, the wrapper executable itself is quite complex (more so
> +than the wrapper script).

Please remove this sentence.

> If something goes wrong, it is useful to
> +debug its operation. This can be enabled by recompiling the wrapper
> +executable itself as follows:

I'd just write the above as:

  The wrapper executable provides a debug mode ...

but actually I'd just patch the wrapper executable to allow for
debugging at run time, and kill this debug mode.  Do we have a
pending patch for this already?

> +Finally, the wrapper executable supports a number of command line
> +options. All of these options are in the @code{--lt-} namespace, and

s/are in the @code{--lt-} namespace/begin with @code{--lt-}/

> +if present they and their arguments will be removed from the argument
> +list passed on to the target executable.  Therefore, the target
> +executable may not employ command line options in the @code{--lt-}

that begin with

> +namespace. (In fact, the wrapper executable will detect any command
> +line options in the @code{--lt-} namespace and abort with an error
> +message if the option is recognized).  If this presents a problem,
> +please contact the libtool team at @email{bug-libtool@@gnu.org}.

Libtool.


The testsuite additions look ok to me if we keep the -DLT_DEBUGWRAPPER
thing, you could commit them as a separate patch.

Cheers,
Ralf