source/README.6cross

   1 (This file was generated by makeinfo and splitinfo.gawk.)
   2 (Released under the old-style GNU documentation license;
   3  see sources or other output files for full text.)
   4
   5 8 Cross compilation
   6 *******************
   7
   8 In a cross compilation a "build" system is used to create binaries to be
   9 executed on a "host" system with different hardware and/or operating
  10 system.
  11
  12    In simple cases, the build system can execute binaries for the host
  13 system.  This typically occurs for bi-arch systems where, e.g.,
  14 'i386-linux' binaries can run on 'x86_64-linux' systems and 'win32'
  15 binaries can run on 'win64' systems.  Although sometimes called "native
  16 cross", technically this is not cross compilation at all.  In most such
  17 cases it suffices to specify suitable compiler flags.  It might be
  18 useful to add the configure option '--build=HOST' to get the correct
  19 canonical host name, but note that this should _not_ be '--host=HOST'
  20 (*note (autoconf)Hosts and Cross-Compilation::).
  21
  22    In order to build, e.g., 32-bit binaries with 'clang' on a 64-bit
  23 MacOSX system one could use:
  24
  25      TL_BUILD_ENV="CC='clang -arch i386' \
  26        CXX='clang++ -arch i386' \
  27        OBJCXX='clang++ -arch i386'" \
  28        ./Build --build=i386-apple-darwin
  29
  30 8.1 Cross configuring
  31 =====================
  32
  33 In a standard cross compilation, binaries for the host system cannot
  34 execute on the build system and it is necessary to specify the configure
  35 options '--host=HOST' and '--build=BUILD' with two different values.
  36
  37    Building binaries requires suitable "cross" tools, e.g., compiler,
  38 linker, and archiver, and perhaps a "cross" version of 'pkg-config' and
  39 similar to locate host system libraries.  Autoconf expects that these
  40 cross tools are given by their usual variables or found under their
  41 usual name prefixed with 'HOST-'.  Here a list of such tools and
  42 corresponding variables:
  43
  44      ar                AR
  45      freetype-config   FT2_CONFIG
  46      g++               CXX
  47      gcc               CC
  48      icu-config        ICU_CONFIG
  49      objdump           OBJDUMP
  50      pkg-config        PKG_CONFIG
  51      ranlib            RANLIB
  52      strip             STRIP
  53
  54 In order to, e.g., build 'mingw32' binaries on 'x86_64-linux' with a
  55 cross compiler found as 'i386-pc-mingw32-gcc' one would specify
  56
  57      --host=i386-pc-mingw32 --build=x86_64-linux-gnu
  58
  59 or perhaps
  60
  61      --host=mingw32 --build=x86_64-linux CC=i386-pc-mingw32-gcc
  62
  63 but this latter, especially, might require adding 'CXX' and others.
  64
  65    Configure arguments such as 'CFLAGS=...' refer to the cross compiler.
  66 If necessary, you can specify compilers and flags for the few auxiliary
  67 C and C++ programs required for the build process as configure arguments
  68
  69      BUILDCC=...
  70      BUILDCPPFLAGS=...
  71      BUILDCFLAGS=...
  72      BUILDCXX=...
  73      BUILDCXXFLAGS=...
  74      BUILDLDFLAGS=...
  75
  76 8.2 Cross problems
  77 ==================
  78
  79 The fact that binaries for the host system cannot be executed on the
  80 build system causes some problems.
  81
  82    One problem is that configure tests using 'AC_RUN_IFELSE' can compile
  83 and link the test program but cannot execute it.  Such tests should be
  84 avoided if possible and otherwise must supply a pessimistic test result.
  85
  86    Another problem arises if the build process must execute some
  87 (auxiliary or installable) programs.  Auxiliary programs can be placed
  88 into a subdirectory that is configured natively as is done for
  89 'texk/web2c/web2c', 'texk/dvipsk/squeeze', and 'texk/xdvik/squeeze'.
  90 The module 'libs/freetype2' uses the value of 'CC_BUILD', 'BUILD-gcc',
  91 'gcc', or 'cc' as compiler for the auxiliary program.
  92
  93    Building LuaTeX (or LuaJITTeX) uses the auxiliary program 'txt2zlib'
  94 to create 'pdflua.c' and, if necessary, update the distributed version
  95 of that file.  In a cross compilation we simply use that distributed
  96 file.
  97
  98    The situation for installable programs needed by the build process is
  99 somewhat different.  A quite expensive possibility, chosen for the ICU
 100 libraries in module 'libs/icu', is to first compile natively for the
 101 build system and in a second step to use these (uninstalled) programs
 102 during the cross compilation.
 103
 104    This approach would also be possible for the tools such as 'tangle'
 105 used in the module 'texk/web2c' to build the WEB programs, but that
 106 would require first building a native 'kpathsea' library.  To avoid this
 107 complication, cross compilation of the WEB or CWEB programs requires
 108 sufficiently recent installed versions of 'tangle', 'ctangle',
 109 'otangle', and 'tie'.
 110
 111    Building 'xindy' requires running the host system 'clisp' binary,
 112 thus cross compilation is not possible.
 113