Re: [PATCH] Document and test LT_DEBUGWRAPPER cwrapper macro

[Ralf Wildenhues]

Hi Charles,

* Charles Wilson wrote on Sun, Jun 21, 2009 at 08:25:00PM CEST:
> Ralf Wildenhues wrote:
> > * Charles Wilson wrote on Fri, Jun 19, 2009 at 07:55:03PM CEST:
> >>   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.)

Why is it intended to be ephemeral?  What do we gain from removing it
besides more implementational complexity through --lt-dump-script?
(This is an honest question.  I'm probably just away from the code too
long to know the answer right away.  Thanks.)

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

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

Thanks for explaining.  The paragraph is ok, but the term "target
executable" is not; in GNU toolchain lingo, target is only relevant
when you create a cross compiler.  Please use something like "program
executable" or so.  And I agree with you that the final sentence should
be something like

  The wrapper executable then launches the program.

> >> +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!")

I don't like that we document that we have pathlist conversion
functions.  (I also have issues with the actual functions, but let's
discuss that in the thread where you posted the patch.)  I guess it's
ok to state that we convert paths, but I think we should limit the
documentation to what the user should have to know.

Aside, `$host' looks a bit ugly.  The GCC just writes plain `host'; I'm
not sure whether that is sufficiently clear at this point in the Libtool
manual, but using the dollar sign is definitely not the best thing.
Maybe using terms like `host system' or `executable for the host system'
is a better choice?

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

Sure, that would be consistent.  Of course, it is an incompatible
change, and requires a NEWS entry.

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

So then this part would only be added as part of a patch to add
--lt-debug.

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

Well, what direction do you prefer?  Is --lt-debug good enough for you?

Thanks,
Ralf