summaryrefslogtreecommitdiff
path: root/Build/source/doc/tlbuild.texi
diff options
context:
space:
mode:
Diffstat (limited to 'Build/source/doc/tlbuild.texi')
-rw-r--r--Build/source/doc/tlbuild.texi317
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