Re: [PATCH] Path conversion documentation

[Charles Wilson]

On 8/30/2010 2:48 PM, Ralf Wildenhues wrote:
> * Charles Wilson wrote on Mon, Aug 30, 2010 at 01:50:12AM CEST:
> > OK to push?
>
> Looks fine to me too, only one or two issues are not markup or typo
> nits (but I have been very nitpicky below).

I expected that.  This is really only a first draft with little in the 
way of editing. I'm surprised at how few nits, or even major criticisms, 
there are.

> Thanks for writing this,

Sure.  Hopefully it also provides an appropriate spot (subsubsection 
under Platform quirks:Cross compiling) for a discussion of sysroot.

> > --- a/doc/libtool.texi
> > +++ b/doc/libtool.texi
> > @@ -223,6 +223,8 @@ Platform quirks
> >   * Reloadable objects::          Binding object files together.
> >   * Multiple dependencies::       Removing duplicate dependent libraries.
> >   * Archivers::                   Programs that create static archives.
> > +* Cross compiling::             Issues that arise when cross compiling.
> > +* File name/path conversion::   Converting filenames between platforms.
>
> FWIW, I would  s/\/path//  but only because I find the result more
> readable and as informative.

Ack. Should filenames be 'file names', as well?

> > @@ -5875,6 +5879,383 @@ must be used to ``bless'' the created library before 
> > linking against it,
> >   with the @kbd{ranlib address@hidden command.  Some systems, like Irix,
> >   use the @code{ar ts} command, instead.
> >
> > address@hidden Cross compiling
> > address@hidden Cross compiling
> > address@hidden cross compile
> > +
> > +Most build systems support the ability to compile libraries and applications
> > +on one platform (the @code{$build} system) for use on a different platform (the
>
> I don't much like variable references that include the $, because that
> ties you to a particular language, whereas here, you are talking about
> concepts rather than languages.  standards.texi just use 'the build
> system'.  Here, since you're defining the term, you could use
> @dfn{build system} or maybe @emph, and later on just use it without
> markup.

Yeah, I really didn't know how to indicate that I'm talking both of a 
concept, and some variable that libtool itself is sensitive to. I tried 
@var, but that just looked wrong.  This is a good place to introduce 
terms; I'll use @dfn and reword as recommended in the texinfo docu:

> Use the command only in passages whose purpose is to
> introduce a term which will be used again or which the reader ought to
> know.  Mere passing mention of a term for the first time does not
> deserve address@hidden'.

> > address@hidden system) -- provided a compiler capable of generating the
>
> Likewise for `host system', and instances below.

Ack.

> > +appropriate output is available.  The GNU Build System
> > address@hidden://www.gnu.org/software/hello/manual/automake/GNU-Build-System.html},
>
> @uref please, and how about putting `GNU Build System' in the second
> argument of @uref, and in the first argument, replacing all single
> slashes with /@/ so they are line-wrapped nicely in the PDF.
>
> Actually, why not make this a normal inter-manual reference like
> @ref{GNU Build System,, The GNU Build System, automake, The Automake
> Manual}
>
> that way it will render well in all outputs?

OK. The problem with @ref is that it *must* be followed by a . or , 
This is not a problem in this instance, but it is a problem in others.

> > +foriegn executables when cross-compiling.  However, if the @code{$build} and
>
> foreign

Ack.

> > +operate within a single Win32 instance, so Cygwin applications can be launched
>
> Either s/Win32/w32/  globally in your patch, or use Windows, as
> recommended by the GCS.

I'll use Windows (even though it will drive RMS crazy) -- except when 
referring to the libtool function names.

> > +from a MinGW context, and vice versa -- provided certain care is taken. Another
> > +example would be if @code{$build} were linux on an @samp{x86} 32bit processor,
>
> Either GNU/Linux, or you write out a full triple like above.

Ack.

> > +and @code{$host} were MinGW.  In this situation, the WINE
> > address@hidden://www.winehq.org/} environment can be used to launch "Win32"
>
> @uref{http://www.winehq.org/, Wine}, and s/WINE/Wine/ globally

WINE is an acronym, in classic recursive style: WINE Is Not an Emulator. 
 But, it does appear the upstream folks have stopped capitalizing it, so...

I noticed one other thing at the winehq site:

> Myth 9: "Wine is for Linux only"
> OK, as of now Wine does not run on many platforms: just Linux, MacOS
> X, FreeBSD and Solaris. Still, this is not 'Linux only'.

I guess I'll need to reword a few things.

> No need to double-quote Win32 here, and if there were, literal
> double-quotes are almost always wrong in texinfo; that's what ``these''
> are for.

Ack.

> > +applications from the linux operating system; again, provided certain care is
>
> GNU/Linux

Ack.

> > +taken.
> > +
> > +One particular issue occurs when a Win32 platform such as MinGW, Cygwin, MSYS,
> > +or MSVC is the @code{$host} or @code{$build}, while the other platform is a 
> > unix
>
> Unix should be capitalized here and below, and I think you mean
> `Unix-style' here.

OK.

> > +This situation is best described using a concrete example: suppose the
> > address@hidden is linux -- (specifically, @code{i686-pc-linux-gnu}), and the
>
> Here's the first time you are /almost/ speaking of @code{build} rather
> than the concept of a build system.
> s/linux/GNU\/Linux/
> @samp{i686-pc-linux-gnu}  for consistency with above.

OK.

> > address@hidden is MinGW (specifically, @code{i586-pc-mingw32}).  On the linux
>
> GNU/Linux

OK. (Wasn't there a big discussion about how GNU should be represented? 
@abbr{GNU} vs GNU vs...  How'd that ever turn out?)

> > +system, there exists a cross compiler, following the usual naming conventions
> > +of such compilers, where the compiler name is prefixed by the @code{$host}
> > +triple.  In this case, the C compiler is named @samp{i586-pc-mingw32-gcc}.
>
> You are not distinguishing between the canonical triplet and between
> alias names.  I'm not sure if we need to go into details; maybe cross
> references to the 'Specifying Target Triplets' and 'Canonicalizing'
> nodes of the Autoconf manual are sufficient.

I'll reword and add the @refs.

> > +As described in the @pxref{Wrapper executables} section, the MinGW @code{$host}
>
> @ref not @pxref.  The latter is for inside parentheses and prints a
> "see", whereas the former doesn't.  For details see 'info texinfo
> --index pxref'.  More instances below.

But since @ref must be terminated with a . or ,  I guess I'd need to 
reword so the reference is treated as a noun rather than an adjective 
(on 'section')?

+As described in @ref{Wrapper executables}, the MinGW ...

> > +to launch the MinGW application from linux.  However, the wrapper executable,
>
> GNU/Linux

Ack.

> > +as a @code{$host} (MinGW) application, must set the @var{$PATH} variable so
>
> @env{PATH}, more instances below.  @var is strictly for metasyntactic
> variables (that is those which you can always replace by X or X_i for
> some integer i, without losing the meaning of the text; IOW, the actual
> name you chose for the variable is not relevant outside the manual).

I see.

> > +that the true application's dependent libraries can be located -- but the
> > +contents of the @var{$PATH} variable must be structured for MinGW. Libtool
> > +must must use the WINE path mapping facilities to determined the correct
>
> s/must must/needs to/
> to determine

Yes, I'd actually already found an fixed this one (and a few other 
typos) before you or Peter reported them, but more eyes is good.

> > +For example, suppose we are compiling an application in @samp{/var/tmp} on
>
> @file{/var/tmp}
>
> > +linux:
>
> GNU/Linux

Ack.

> > address@hidden
> > +/var/tmp/foo/src/ (application code)
> > +/var/tmp/foo/lib/ (library code)
> > address@hidden example
>
> What does this example code describe?  You don't state that these are
> directories, and you don't state whether they belong to, say, the source
> tree, the build tree, or some install tree.

Yes, I was trying to elide over all those details.  I can be a lot more 
specific, but it'll get (even more) wordy.

> > +Since the library will be built in @samp{.../foo/lib}, the wrapper executable
>
> @file, more instances below.
>
> > +must add that value to @var{$PATH} (actually, to @var{$objdir} under
>
> @var{objdir} is actually acceptable since the manual explicitly defines
> that variable somewhere earlier.
>
> > address@hidden/foo/lib}, but we'll ignore that for now).  However, Win32 does 
> > not
> > +have a concept of paths such as @samp{/var/tmp/foo/lib}; so, WINE provides
>
> s/paths/Unix-style file names/  ?

Already fixed :-)

> > +to the @var{$PATH}.  libtool contains support for path conversion of this
> > +type, for a certain limited set of @code{$build}/@code{$host} combinations. In
>
> build and host combinations

Right.

> > +this case, libtool will invoke WINE's @code{winepath} utility to ensure that
> > +the correct @var{$PATH} value is used.  For more information,
> > address@hidden name/path conversion}.
> > +
> > address@hidden File name/path conversion
> > address@hidden File name/path conversion
> > address@hidden filename conversion
> > address@hidden path conversion
> > +
> > +In certain situations, libtool must convert file names and paths between
> > +formats appropriate to different platforms. Usually this occurs when
>
> Please two spaces after end-of-sentence.

Yeesh. And after spending years training myself NOT to do that anymore...

> > +cross-compiling, and affects only the ability to launch @code{$host}
> > +executables on the @code{$build} platfrom using an emulation or API
>
> platform
>
> > +enhancement environment such as WINE.  Failure to convert paths
> > +(@pxref{Path Conversion Failure}) will cause a warning to be issued, but
> > +rarely causes the build to fail -- and should have no affect on the compiled
>
> `fail---and' is the US English way to write this.
> effect

OK. (I'd prefer to write \mdash, but this ain't TeX).

> > +results, once installed properly on the @code{$host} system. For more
> > +information, @pxref{Cross compiling}.
> > +
> > +However, path conversion may also occur in another scenario: when using a
>
> s/path/file name/

Already fixed...

> > address@hidden Cygwin @tab MinGW (w32)
> > address@hidden @pxref{Cygwin/w32 Path Conversion}
>
> That'll be interesting to see whether doc tools cope well with references
> inside tables.

You're _supposed_ to be able to do it. And, at least, the .info file 
seemed ok.

> > address@hidden Requires @var{LT_CYGPATH}. @pxref{LT_CYGPATH}. Provided for 
> > testing
>
> @env{LT_CYGPATH}, multiple instances.

Ack.

> > +purposes only.
> > +
> > address@hidden Linux + WINE @tab Cygwin
> > address@hidden Requires both WINE and @var{LT_CYGPATH}, but currently 
> > non-functional.
>
> I'd omit the ", but currently non-functional".  Such comments go out of
> date quickly and are usually not garbage-collected even if the failure
> is due to something in the same package and not in external software.
> Alternatively, qualify the comment, e.g.: ..., but does not yet work
> with Cygwin 27.38 and Wine 99.97.

OK.

> > +* Native MinGW Path Conversion::   MSYS path conversion idiosyncracies
>
> s/path/file name/

Already fixed...

> idiosyncrasies

Ack.

> > +* Cygwin/w32 Path Conversion::     Using cygpath to convert Cygwin paths
>
> @command{cygpath} here and below

I see.

> > +When an MSYS shell launches a native w32 executable (as opposed to other
> > address@hidden executables), it uses a system of hueristics to detect any
>
> heuristic

Thanks.

> > address@hidden that can be used to convert file names and paths between
>
> @command{cygpath}, multiple instances

OK.

> > +the two representations.  In a correctly configured Cygwin installation,
> > address@hidden is always present, and is in the @var{$PATH}.
> > +
> > +Libtool uses @samp{cygpath} to convert from Cygwin (unix) paths to w32 format
> > +when @code{$build} is Cygwin and @code{$host} is MinGW or MSVC.
>
> For Peter's remark I suggest just using  s/MinGW or MSVC/MinGW/  here.

OK.  I wasn't sure how much (if anything) to say about MSVC, since 
Peter's patch series has only been partially merged so far, and I'm not 
sure any of what HAS been merged is really MSVC-specific...

> > +WINE @url{http://www.winehq.org} provides an interpretation environment for
>
> @uref as above

OK.

> > +if the @code{binfmt} extension is enabled.
>
> I'd just write binfmt without @code, but not sure.

NP.

> > +Cygwin executables, such as @samp{sed}, @samp{cp}, etc.  If the @code{$build}
>
> @command{sed}, @command{cp}

Right.

> > +environment had this directory in its @var{$PATH}, then these cygwin versions
>
> Cygwin, multiple instances

Yeesh, I thought I caught those...

> > +tables" specified in<CYGROOT-N>/etc/fstab. Each each installation's
>
> @address@hidden/etc/fstab}   ?  More instances below.

Sounds good.

> > address@hidden utility automatically deduces the appropriate /etc/fstab file.
>
> @file{/etc/fstab}

Right.

> > address@hidden tool should have been used, via WINE, to properly install
>
> @command{setup.exe}

Ack.

> > +Cygwin into the WINE file system (and registry).
> > +
> > +Unfortunately, WINE support for Cygwin is intermittent.  Recent releases of
> > +Cygwin (1.7 and above) appear to require more Win32 API support than WINE
> > +provides at present; most Cygwin applications fail to execute. This includes
>
> s/\. /.  /    more instances below.

Sigh...

> > address@hidden itself.  Hence, it is best @emph{not} to use the LT_CYGPATH
> > +machinery in libtool when performing linux to Cygwin cross-compiles. Similarly,
> > +it is best @emph{not} to enable the Linux @emph{binfmt} support, because while
> > +WINE will fail to execute the compiled cygwin applications, it will do so
> > +while returning a status code of success. This tends to confuse build systems
>
> a bit awkward; how about "it will still exit with status zero"?

OK.

> BTW, has it been reported upstream?

Not yet.  I'm not even sure it's a failure of Wine, or binfmt, or an 
actual design (mis)feature.  I mean, *wine* succeeded: it ran, and did 
exactly what it was designed to do: emulate the Windows system and 
launch a PE image.  It's not Wine's fault that the PE image itself 
loaded some DLLs that didn't provide the necessary APIs...

*I* would return non-zero status, but then I don't know reasoning behind 
the current behavior -- if it isn't simply a bug.

> > +called a "Cygwin to MinGW" cross compile.  The current (and standard)
>
> ``Cygwin to MinGW''

OK.

> > +definition is where there exists compiler that produces native w32 libraries
>
> s/where/when/  ?
> s/exists/is a/  ?

I think I rewrote this bit already, but I'll check.

> > +and applications, but which itself is a cygwin application -- just as any
>
> s/ -- /, /

This too.

> > +other cross compile setup would do.
> > +
> > +However, historically there were two other definitions, which we will refer
> > +to as the @emph{fake} one, and the @emph{lying} one.
> > +
> > +In the @emph{fake} Cygwin to MinGW cross compile case, you actually use the
>
> s/ the//

OK.

> > +a native MinGW compiler, but you do so from within a Cygwin environment:
> > +
> > address@hidden
> > +cygwin$ export PATH="/c/MinGW/bin:address@hidden@}"
>
> $i?

Fixed.

> I suggest @kbd instead of faking a prompt.

OK. (Can you /do/ that inside @example?)

> > +cygwin$ configure --build=i686-pc-cygwin \
> > +       --host=mingw32 \
> > +       NM=/c/MinGW/bin/nm.exe
> > address@hidden example
> > +
> > +In this way, the build system "knows" that you are cross compiling, and the
>
> ``knows''

OK.

> > +path conversion logic will be used.  However, because the tools
> > +(@samp{mingw32-gcc}, @samp{nm}, @samp{ar}) used are actually native
>
> @command

Right.

> > +w32 applications, they will not understand any Cygwin (that is, unix-ish)
> > +absolute paths passed as command line arguments (and, unlike MSYS, Cygwin
>
> s/paths/file names/

I think I already fixed this, too.

> > +does not automatically convert such arguments).  However, so long as only
>
> Is "so long as" as right as "as long as"?  (sorry for the pun)

http://grammar.ccc.commnet.edu/grammar/grammarlogs2/grammarlogs359.htm
> "As long as" means "during the whole time that" and "so long as"
> means "provided that" or "only if,"...

I can go ahead and replace it with "provided that" just to avoid 
confusion...


> > +relative paths are used in the build system, and non-w32-supported unix
>
> s/paths/file names/

Right.

> > address@hidden
> > +cygwin$ export PATH="/c/MinGW/bin:address@hidden@}"
> > +cygwin$ configure --build=i686-pc-mingw32 \
> > +       --host=i686-pc-mingw32 \
> > +       --disable-dependency-tracking
> > address@hidden example
> > +
>
> @noindent

???
I don't understand.


> > +because otherwise the MinGW gcc will generate dependency files that contain
>
> GCC when speaking about the compiler collection, @command{gcc} when
> speaking about a specific C compiler command.

OK.

> > +There have also always been a number of other details required for the
> > address@hidden case to operate correctly, such as the use of so-called
> > address@hidden mounts}:
>
> @dfn or @emph, not @samp.

OK.  (Can you think of better names; something a little less...informal 
and pejorative?)

> > address@hidden
> > +#<cygwin-root>/etc/fstab
>
> @var{cygwin-root}

Right.

> > +D:/foo    /foo     some_fs binary 0 0
> > +D:/bar    /bar     some_fs binary 0 0
> > +E:/grill  /grill   some_fs binary 0 0
> > address@hidden example
> > +
> > +In this way, top-level directories of each drive are available
> > +using identical names within cygwin.
> > +
> > +Note that you also need to ensure that the standard unix directories
> > +(like /bin, /lib, /usr, /etc) appear in the root of a drive. This means
>
> @file here and below.

OK.

> > +that you must install cygwin itself into the C:/ root directory (or D:/,
> > +or E:/, etc) -- instead of the recommended installation into C:/cygwin/.
> > +
> > +In addition, all paths used in the build system must be relative, symlinks
>
> s/paths/file names/

OK.

> > +should not be used within the source or build directory trees, and all
> > address@hidden options to @samp{gcc} except @code{-MMD} must be avoided.
>
> @option{-M*}
> @option{-MMD}

D'oh.

> This is not easy to achieve with Automake, as it will happily use some
> of these options.

Are you suggesting I should add the above commentary---as long as we're 
being opinionated, anyway:

> > +
> > +This is quite a fragile setup, but it has been in historical use, and so is
> > +documented here.

Thanks for the review.

--
Chuck