Ralf Wildenhues wrote:
> * Charles Wilson wrote on Fri, Jun 19, 2009 at 07:55:03PM CEST:
>> 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,
they aren't. so, strike one.
> or the wrapper is not created for
> executables that don't link against uninstalled libraries (are they?),
they aren't. so, strike two.
> they should not be documented. Or we even take them out.
Ok, only two strikes. But they're out anyway. I'll post a patch to do so.
> 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.
I'll do that first, before revising and reposting the documentation
patch. I still think these env-manipulation features can be useful, but
as they haven't proven so yet, there's no reason to keep them around
"just in case". If we need 'em later, they're in the repo.
>> 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?
In some cases (cross-builds, until we get all that straightened out), it
is useful to use a script wrapper itself on $build, to launch the target
(in WINE? remotely?) I know that when the cwrapper.exe is, for whatever
reason, not launching the target, manually doing cwrapper.exe
--lt-dump-script, and then using that script directly, can help debug
problems. Sure, if it happens it means there's a bug in the cwrapper,
OR a misconfiguration in the user's (emulation?) environment, but...how
can you track it down without subdividing the problem a little?
--lt-dump-script helps you do that.
(the shwrapper in .libs/ is intended to be ephemeral, and as an
implementation detail may be deleted after the link is completed.)
> 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.
It's platform-specific *debug* support, for a platform-specific behavior
(the cwrapper). See below vis. runtime debugging.
>> 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
>> -...@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.
>
> 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.
>>
>> +...@menu
>> +* Wrapper executables:: Wrapper executables for certain platforms.
>
> some platforms
Ack.
>> +...@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 win32 such as cygwin
>
> Windows (see standards.info for a rationale)
> Cygwin
Ack.
>> +and mingw, use a wrapper executable rather than a wrapper script. It
>
> MinGW
Ack.
>> +performs the same function, but is necessary so that @code{make}
>
> @command{make}
Ack.
>> +rules for target executables (whose names end in @code{$(EXEEXT)})
>> +are satisfied. Recall that the actual target executable is created
>> +in @value{objdir} as @co...@value{objdir}/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.
OK.
> 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.
Right.
>> +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.
OK.
>> +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?
It's important because I'm d*mn tired of explaining it to various users
over and over. I want to be able to point to the documentation. Now, if
you're only complaining about the last sentence's reference to
exec()/_spawn() -- sure, that's totally unnecessary.
>> +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.
What statement is false? If it's wrong, then I don't understand
something in the wrapper, and I wrote most of it (unless you're getting
pedantic about "what if $build == $host? then you can't say 'must be in
$host format, not $build format' because both are the same! Nah! Nah!")
>> +Obviously, the wrapper executable itself is quite complex (more so
>> +than the wrapper script).
>
> Please remove this sentence.
OK.
>> 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 ...
Ok...
> 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?
No. I can easily do that; the code is already structured to make that
possible. But isn't this adding another platform-specific behavior? Or
do you want me to add --lt-debug to the shwrapper, as well?
>> +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-}/
Ack. However, if we remove --lt-dump-script and do not add --lt-debug,
then the whole section could go away, because there would be no --lt-
options.
>> +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
OK.
>> +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.
Ack.
> The testsuite additions look ok to me if we keep the -DLT_DEBUGWRAPPER
> thing, you could commit them as a separate patch.
...or revise to test explicitly the --lt-debug switch, if you'd prefer
to go that direciton.
Thanks for the review. I'll wait for your response before beginning any
revisions.
--
Chuck
