File: libtool.info,  Node: Cross compiling,  Next: File name conversion,  Prev: Archivers,  Up: Platform quirks

15.3.5 Cross compiling
----------------------

Most build systems support the ability to compile libraries and
applications on one platform for use on a different platform, provided a
compiler capable of generating the appropriate output is available.  In
such cross compiling scenarios, the platform where the libraries or
applications are compiled is called the “build platform”, while the
platform where the libraries or applications are intended to be used or
executed is called the “host platform”.  *note The GNU Build System:
(automake)GNU Build System, of which libtool is a part, supports cross
compiling via arguments passed to the configure script: ‘--build=...’
and ‘--host=...’.  However, when the build platform and host platform
are very different, libtool is required to make certain accommodations
to support these scenarios.

   In most cases, because the build platform and host platform differ,
the cross-compiled libraries and executables can't be executed or tested
on the build platform where they were compiled.  The testsuites of most
build systems will often skip any tests that involve executing such
foreign executables when cross-compiling.  However, if the build
platform and host platform are sufficiently similar, it is often
possible to run cross-compiled applications.  Libtool's own testsuite
often attempts to execute cross-compiled tests, but will mark any
failures as _skipped_ since the failure might simply be due to the
differences between the two platforms.

   In addition to cases where the host platform and build platform are
extremely similar (e.g.  ‘i586-pc-linux-gnu’ and ‘i686-pc-linux-gnu’),
there is another case where cross-compiled host applications may be
executed on the build platform.  This is possible when the build
platform supports an emulation or API-enhanced environment for the host
platform.  One example of this situation would be if the build platform
were MinGW, and the host platform were Cygwin (or vice versa).  Both of
these platforms can actually operate within a single Windows instance,
so Cygwin applications can be launched from a MinGW context, and vice
versa--provided certain care is taken.  Another example would be if the
build platform were GNU/Linux on an x86 32bit processor, and the host
platform were MinGW. In this situation, the Wine
(http://www.winehq.org/) environment can be used to launch Windows
applications from the GNU/Linux operating system; again, provided
certain care is taken.

   One particular issue occurs when a Windows platform such as MinGW,
Cygwin, or MSYS is the host or build platform, while the other platform
is a Unix-style system.  In these cases, there are often conflicts
between the format of the file names and paths expected within host
platform libraries and executables, and those employed on the build
platform.

   This situation is best described using a concrete example: suppose
the build platform is GNU/Linux with canonical triplet
‘i686-pc-linux-gnu’.  Suppose further that the host platform is MinGW
with canonical triplet ‘i586-pc-mingw32’.  On the GNU/Linux platform
there is a cross compiler following the usual naming conventions of such
compilers, where the compiler name is prefixed by the host canonical
triplet (or suitable alias).  (For more information concerning canonical
triplets and platform aliases, see *note Specifying Target Triplets:
(autoconf)Specifying Target Triplets. and *note Canonicalizing:
(autoconf)Canonicalizing.) In this case, the C compiler is named
‘i586-pc-mingw32-gcc’.

   As described in *note Wrapper executables::, for the MinGW host
platform libtool uses a wrapper executable to set various environment
variables before launching the actual program executable.  Like the
program executable, the wrapper executable is cross-compiled for the
host platform (that is, for MinGW). As described above, ordinarily a
host platform executable cannot be executed on the build platform, but
in this case the Wine environment could be used to launch the MinGW
application from GNU/Linux.  However, the wrapper executable, as a host
platform (MinGW) application, must set the ‘PATH’ variable so that the
true application's dependent libraries can be located--but the contents
of the ‘PATH’ variable must be structured for MinGW. Libtool must use
the Wine file name mapping facilities to determine the correct value so
that the wrapper executable can set the ‘PATH’ variable to point to the
correct location.

   For example, suppose we are compiling an application in ‘/var/tmp’ on
GNU/Linux, using separate source code and build directories:

     /var/tmp/foo-1.2.3/app/              (application source code)
     /var/tmp/foo-1.2.3/lib/              (library source code)
     /var/tmp/BUILD/app/                  (application build objects here)
     /var/tmp/BUILD/lib/                  (library build objects here)

   Since the library will be built in ‘/var/tmp/BUILD/lib’, the wrapper
executable (which will be in ‘/var/tmp/BUILD/app’) must add that
directory to ‘PATH’ (actually, it must add the directory named OBJDIR
under ‘/var/tmp/BUILD/lib’, but we'll ignore that detail for now).
However, Windows does not have a concept of Unix-style file or directory
names such as ‘/var/tmp/BUILD/lib’.  Therefore, Wine provides a mapping
from Windows file names such as ‘C:\Program Files’ to specific
Unix-style file names.  Wine also provides a utility that can be used to
map Unix-style file names to Windows file names.

   In this case, the wrapper executable should actually add the value

     Z:\var\tmp\BUILD\lib

to the ‘PATH’.  libtool contains support for path conversions of this
type, for a certain limited set of build and host platform combinations.
In this case, libtool will invoke Wine's ‘winepath’ utility to ensure
that the correct ‘PATH’ value is used.  *Note File name conversion::.