diff options
Diffstat (limited to 'Build/source/doc/tlbuild.texi')
-rw-r--r-- | Build/source/doc/tlbuild.texi | 317 |
1 files changed, 161 insertions, 156 deletions
diff --git a/Build/source/doc/tlbuild.texi b/Build/source/doc/tlbuild.texi index a3b638edc4c..806bff77e9c 100644 --- a/Build/source/doc/tlbuild.texi +++ b/Build/source/doc/tlbuild.texi @@ -2,7 +2,7 @@ @setfilename tlbuild.info @set version 2018 -@set month-year February 2018 +@set month-year April 2018 @set mytitle Building @TeX{} Live (@value{version}) @settitle @value{mytitle} @@ -88,7 +88,6 @@ For an overview of this manual, @pxref{Introduction}. * Installing:: How and where installation happens (or not). * Layout and infrastructure:: Autoconf macros, etc., in detail. * Configure options:: List of all configure options. -* Cross compilation:: Building on host X for target Y. * Coding conventions:: Conventions to follow. * Continuous integration:: Automated build testing. * install-tl:: The @TL{} installer. @@ -336,6 +335,7 @@ supported (sorry). * Build in parallel:: Simultaneous @code{make} processes. * Build distribution:: Making a distribution tarball. * Build one package:: Example of working on just one program. +* Cross compilation:: Building on host X for target Y. @end menu @@ -514,6 +514,153 @@ otherwise, individual packages may use something different. You can explicitly specify the compilers to be used with the environment variables @code{CC}, @code{CXX}, and @code{OBJCXX}. +@node Cross compilation +@section Cross compilation + +@cindex cross compilation +In a cross compilation a @dfn{build} system is used to create +binaries to be executed on a @dfn{host} system with different +hardware and/or operating system. + +@cindex native cross compilation +In simple cases, the build system can execute binaries for the host +system. This typically occurs for bi-arch systems where, e.g., +@code{i386-linux} binaries can run on @code{x86_64-linux} systems and +@code{win32} binaries can run on @code{win64} systems. Although +sometimes called ``native cross'', technically this is not cross +compilation at all. In most such cases it suffices to specify +suitable compiler flags. It might be useful to add the configure +option @code{--build=@var{host}} to get the correct canonical host +name, but note that this should @emph{not} be @code{--host=@var{host}} +(@pxref{Hosts and Cross-Compilation,,, autoconf, GNU Autoconf}). + +In order to build, e.g., 32-bit binaries with @command{clang} on a 64-bit +MacOSX system one could use: + +@example +TL_BUILD_ENV="CC='clang -arch i386' \ + CXX='clang++ -arch i386' \ + OBJCXX='clang++ -arch i386'" \ + ./Build --build=i386-apple-darwin +@end example + +@menu +* Cross configuring:: Configuring for cross compilation. +* Cross problems:: Cross compilation problems. +@end menu + +@node Cross configuring +@subsection Cross configuring + +@cindex cross compilation configuring +@cindex configuring, for cross compilation + +@vindex --host=@var{host} +@vindex --build=@var{host} +In a standard cross compilation, binaries for the host system cannot +execute on the build system and it is necessary to specify the +configure options @code{--host=@var{host}} and +@code{--build=@var{build}} with two different values. + +Building binaries requires suitable ``cross'' tools, e.g., compiler, +linker, and archiver, and perhaps a ``cross'' version of +@code{pkg-config} and similar to locate host system libraries. +Autoconf expects that these cross tools are given by their usual +variables or found under their usual name prefixed with +@code{@var{host}-}. Here a list of such tools and corresponding +variables: + +@example +@code{ar} AR +@code{freetype-config} FT2_CONFIG +@code{g++} CXX +@code{gcc} CC +@code{icu-config} ICU_CONFIG +@code{objdump} OBJDUMP +@code{pkg-config} PKG_CONFIG +@code{ranlib} RANLIB +@code{strip} STRIP +@end example + +@cindex @code{mingw32} +@noindent In order to, e.g., build @code{mingw32} binaries on +@code{x86_64-linux} with a cross compiler found as +@file{i386-pc-mingw32-gcc} one would specify + +@example +--host=i386-pc-mingw32 --build=x86_64-linux-gnu +@end example + +@noindent or perhaps + +@example +--host=mingw32 --build=x86_64-linux CC=i386-pc-mingw32-gcc +@end example + +@noindent but this latter, especially, might require adding @code{CXX} and others. + +Configure arguments such as @code{CFLAGS=@dots{}} refer to the cross +compiler. If necessary, you can specify compilers and flags for the +few auxiliary C and C++ programs required for the build process as +configure arguments + +@vindex BUILDCC@r{,} BUILDCFLAGS@r{, @dots{}} +@example +BUILDCC=@dots{} +BUILDCPPFLAGS=@dots{} +BUILDCFLAGS=@dots{} +BUILDCXX=@dots{} +BUILDCXXFLAGS=@dots{} +BUILDLDFLAGS=@dots{} +@end example + +@node Cross problems +@subsection Cross problems + +@cindex cross compilation problems + +The fact that binaries for the host system cannot be executed on the +build system causes some problems. + +One problem is that configure tests using @code{AC_RUN_IFELSE} can +compile and link the test program but cannot execute it. Such tests +should be avoided if possible and otherwise must supply a pessimistic +test result. + +@pindex squeeze +@pindex web2c @r{program} +@cindex @code{freetype} cross compiling +@vindex CC_BUILD +Another problem arises if the build process must execute some +(auxiliary or installable) programs. Auxiliary programs can be placed +into a subdirectory that is configured natively as is done for +@file{texk/web2c/web2c}, @file{texk/dvipsk/squeeze}, and +@file{texk/xdvik/squeeze}. The module @file{libs/freetype2} uses the +value of @code{CC_BUILD}, @file{@var{build}-gcc}, @file{gcc}, or +@file{cc} as the compiler for the auxiliary program. + +@cindex ICU cross compiling +The situation for installable programs needed by the build process is +somewhat different. A rather expensive possibility, chosen for the ICU +libraries in module @file{libs/icu}, is to first compile natively for +the build system and in a second step to use these (uninstalled) +programs during the cross compilation. + +@pindex tangle +@pindex ctangle +@pindex otangle +@pindex tie +This approach would also be possible for the tools such as +@file{tangle} used in the module @file{texk/web2c} to build the WEB +programs, but that would require first building a native +@code{kpathsea} library. To avoid this complication, cross +compilation of the WEB or CWEB programs requires sufficiently recent +installed versions of @file{tangle}, @file{ctangle}, @file{otangle}, +and @file{tie}. + +@cindex @code{xindy} cross compiling impossible +Building @code{xindy} requires running the host system @file{clisp} +binary, thus cross compilation is not possible. @node Installing @chapter Installing @@ -2196,157 +2343,6 @@ commands used, e.g., to build the @code{xindy} documentation. @end vtable -@node Cross compilation -@chapter Cross compilation - -@cindex cross compilation -In a cross compilation a @dfn{build} system is used to create -binaries to be executed on a @dfn{host} system with different -hardware and/or operating system. - -@cindex native cross compilation -In simple cases, the build system can execute binaries for the host -system. This typically occurs for bi-arch systems where, e.g., -@code{i386-linux} binaries can run on @code{x86_64-linux} systems and -@code{win32} binaries can run on @code{win64} systems. Although -sometimes called ``native cross'', technically this is not cross -compilation at all. In most such cases it suffices to specify -suitable compiler flags. It might be useful to add the configure -option @code{--build=@var{host}} to get the correct canonical host -name, but note that this should @emph{not} be @code{--host=@var{host}} -(@pxref{Hosts and Cross-Compilation,,, autoconf, GNU Autoconf}). - -In order to build, e.g., 32-bit binaries with @command{clang} on a 64-bit -MacOSX system one could use: - -@example -TL_BUILD_ENV="CC='clang -arch i386' \ - CXX='clang++ -arch i386' \ - OBJCXX='clang++ -arch i386'" \ - ./Build --build=i386-apple-darwin -@end example - -@menu -* Cross configuring:: Configuring for cross compilation. -* Cross problems:: Cross compilation problems. -@end menu - - -@node Cross configuring -@section Cross configuring - -@cindex cross compilation configuring -@cindex configuring, for cross compilation - -@vindex --host=@var{host} -@vindex --build=@var{host} -In a standard cross compilation, binaries for the host system cannot -execute on the build system and it is necessary to specify the -configure options @code{--host=@var{host}} and -@code{--build=@var{build}} with two different values. - -Building binaries requires suitable ``cross'' tools, e.g., compiler, -linker, and archiver, and perhaps a ``cross'' version of -@code{pkg-config} and similar to locate host system libraries. -Autoconf expects that these cross tools are given by their usual -variables or found under their usual name prefixed with -@code{@var{host}-}. Here a list of such tools and corresponding -variables: - -@example -@code{ar} AR -@code{freetype-config} FT2_CONFIG -@code{g++} CXX -@code{gcc} CC -@code{icu-config} ICU_CONFIG -@code{objdump} OBJDUMP -@code{pkg-config} PKG_CONFIG -@code{ranlib} RANLIB -@code{strip} STRIP -@end example - -@cindex @code{mingw32} -@noindent In order to, e.g., build @code{mingw32} binaries on -@code{x86_64-linux} with a cross compiler found as -@file{i386-pc-mingw32-gcc} one would specify - -@example ---host=i386-pc-mingw32 --build=x86_64-linux-gnu -@end example - -@noindent or perhaps - -@example ---host=mingw32 --build=x86_64-linux CC=i386-pc-mingw32-gcc -@end example - -@noindent but this latter, especially, might require adding @code{CXX} and others. - -Configure arguments such as @code{CFLAGS=@dots{}} refer to the cross -compiler. If necessary, you can specify compilers and flags for the -few auxiliary C and C++ programs required for the build process as -configure arguments - -@vindex BUILDCC@r{,} BUILDCFLAGS@r{, @dots{}} -@example -BUILDCC=@dots{} -BUILDCPPFLAGS=@dots{} -BUILDCFLAGS=@dots{} -BUILDCXX=@dots{} -BUILDCXXFLAGS=@dots{} -BUILDLDFLAGS=@dots{} -@end example - - -@node Cross problems -@section Cross problems - -@cindex cross compilation problems - -The fact that binaries for the host system cannot be executed on the -build system causes some problems. - -One problem is that configure tests using @code{AC_RUN_IFELSE} can -compile and link the test program but cannot execute it. Such tests -should be avoided if possible and otherwise must supply a pessimistic -test result. - -@pindex squeeze -@pindex web2c @r{program} -@cindex @code{freetype} cross compiling -@vindex CC_BUILD -Another problem arises if the build process must execute some -(auxiliary or installable) programs. Auxiliary programs can be placed -into a subdirectory that is configured natively as is done for -@file{texk/web2c/web2c}, @file{texk/dvipsk/squeeze}, and -@file{texk/xdvik/squeeze}. The module @file{libs/freetype2} uses the -value of @code{CC_BUILD}, @file{@var{build}-gcc}, @file{gcc}, or -@file{cc} as the compiler for the auxiliary program. - -@cindex ICU cross compiling -The situation for installable programs needed by the build process is -somewhat different. A rather expensive possibility, chosen for the ICU -libraries in module @file{libs/icu}, is to first compile natively for -the build system and in a second step to use these (uninstalled) -programs during the cross compilation. - -@pindex tangle -@pindex ctangle -@pindex otangle -@pindex tie -This approach would also be possible for the tools such as -@file{tangle} used in the module @file{texk/web2c} to build the WEB -programs, but that would require first building a native -@code{kpathsea} library. To avoid this complication, cross -compilation of the WEB or CWEB programs requires sufficiently recent -installed versions of @file{tangle}, @file{ctangle}, @file{otangle}, -and @file{tie}. - -@cindex @code{xindy} cross compiling impossible -Building @code{xindy} requires running the host system @file{clisp} -binary, thus cross compilation is not possible. - - @node Coding conventions @chapter Coding conventions @@ -2498,7 +2494,14 @@ mirror of the sources that is pushed to Github is updated (currently) at 30 minute intervals, and only the last commit pushed is tested on Travis-CI. -@subheading Transfer from Subversion to Github +@menu +* Transfer from Subversion to Github:: +* Automatic update of the Git mirror:: +* CI testing on Travis-CI:: +@end menu + +@node Transfer from Subversion to Github +@section Transfer from Subversion to Github git-svn (@url{https://git-scm.com/docs/git-svn}) is used to check out the subtree @code{Build/source} of the Subversion repository. The @@ -2549,7 +2552,8 @@ come from the local @code{master} (not the one on Github) to Subversion, back to @code{master} on @code{texlive.info}, and from there to Github. -@subheading Automatic update of the Git mirror +@node Automatic update of the Git mirror +@section Automatic update of the Git mirror @emph{admin} has installed a cron job on @code{texlive.info} running every 30 minute which essentially runs @code{git svn rebase} and @@ -2558,7 +2562,8 @@ command fetches the changes from the Subversion repository and updates the @code{master} branch with them, the second one pushes changes (if available) to Github. -@subheading CI testing on Travis-CI +@node CI testing on Travis-CI +@section CI testing on Travis-CI @pindex .travis.yml The @code{source} tree of @TL{} contains a top-level file |