Merge branch 'texlive-trunk' r62492

source/README

@@ -1,4 +1,4 @@
-$Id$
+Id: README 62297 2022-02-28 22:13:17Z karl $
 Public domain.  Originally written 2005 by Karl Berry.
 
 For a high-level overview of building TeX Live, see
@@ -34,23 +34,25 @@ aarch64-linux:
 
 armhf-linux:
   Raspbian/Raspberry Pi OS (Debian Buster)
-  gcc (Raspbian 8.3.0-6+rpi1) 8.3.0
+  gcc version 10.2.1 20210110 (Raspbian 10.2.1-6+rpi1)
   ./Build --enable-xindy CLISP=${BUILD_ROOT_DIR}/clisp/clisp-build/clisp}
+  armhf-linux binaries are created and tested on RPi;
+  they run on RPi, as well as ARMv7 CPUs, but are untested on non-RPi
+  ARMv6 machines.
 
 i386-cygwin, x86_64-cygwin: gcc-10.2.0, cygwin-3.1.7
   TL_CONFIGURE_ARGS="--enable-xindy --enable-shared CLISP=/path/to/clisp.exe
     LDFLAGS='-Wl,--no-insert-timestamp -Wl,--stack,0x800000'" \
   ./Build
 
-
 i386-freebsd, amd64-freebsd:
   Built on contextgarden, see below.
   FreeBSD 11.4
 
 i386-linux: see travis below.
 
 i386-netbsd, amd64-netbsd:
-  NetBSD/amd64 9.1
+  NetBSD/amd64 9.2
   gcc version 7.5.0 (nb4 20200810)
     TL_MAKE=gmake CC=gcc CXX=g++ \
     CFLAGS=-D_NETBSD_SOURCE \
@@ -80,7 +82,7 @@ x86_64-linux,
 x86_64-linuxmusl:
   CentOS 7 Docker image with musl libc 1.1.5, plus gcc10:
     yum -y install centos-release-scl-rh
-    yum -y install devtoolset-10-gcc-c++
+    yum -y install devtoolset-9-gcc-c++
     yum install -y fontconfig-devel libX11-devel libXmu-devel libXaw-devel
   Binaries are taken from the CI testing via github;
   see the source/.github/* files for details on how to build,

source/README.1prerequisites

@@ -6,32 +6,41 @@
 ***************
 
 Overall, building the TeX Live programs, when using all libraries from
-the TL source tree, requires C and C++11 compilers and GNU 'make'.  If
-'make' from your 'PATH' is not GNU make, you can set the 'MAKE'
-environment variable to whatever is necessary.
+the TL source tree, requires C and C++11 compilers, GNU 'make', and
+Python.
 
-   GNU 'make' is required only because of some third-party libraries,
-notably FreeType; all the TL-maintained directories (and
-Automake/Autoconf output in general) work with any reasonable 'make'.
+   * If 'make' from your 'PATH' is not GNU 'make', you can set the
+     'MAKE' environment variable to whatever is necessary.
 
-   A C++11 compiler is similarly required because of the third-party
-library ICU; the program 'dvisvgm' also requires C++11.  It is possible
-to build everything else with older compilers, but you have to remove
-the C++11-dependent sources.  *Note Build one package::.
+     GNU 'make' is required only because of third-party libraries,
+     notably FreeType.  Automake/Autoconf output in general, and the
+     TL-maintained directories, work with any reasonable 'make'.(1)
+
+   * A C++11 compiler is similarly required because of the third-party
+     libraries ICU and HarfBuzz (at least); the program 'dvisvgm' also
+     requires C++11.  It is possible to build what remains with older
+     compilers, but you have to remove the C++11-dependent sources.
+     *Note Build one package::.
+
+   * Python is required by ICU tests.  (If you know how to disable these
+     tests and thus eliminate the requirement, please write.)
 
    A few programs in the tree have additional requirements:
 
 'web2c'
-     requires 'perl' for some tests run by 'make check'.
+     requires 'perl' for some tests run by 'make check'.  Incidentally,
+     the TeX Live installer ('install-tl') and manager ('tlmgr') are
+     also written in Perl, but this does not matter for compiling the
+     sources.
 
 'xdvik'
 'xpdfopen'
-     require X11 headers and libraries, typically in "development"
+     require X11 headers and libraries, typically in devel(opment)
      packages that are not installed by default.
 
 'xetex'
      requires 'fontconfig' (again both headers and library), or, for
-     MacOSX only, the 'ApplicationServices' and 'Cocoa' frameworks.
+     MacOS only, the 'ApplicationServices' and 'Cocoa' frameworks.
 
 'xindy'
      requires GNU 'clisp', 'libsigsegv', and 'libiconv'; additionally,
@@ -60,6 +69,14 @@ expect:
    If you haven't modified any source files, and infrastructure tools
 such as 'autoconf' or 'makeinfo' are still being run, check your
 timestamps--notably, 'use-commit-times' must be set to 'yes' in your
-Subversion configuration (*note Build system tools::).  Barring buggy
-commits, no infrastructure tools are needed to do a normal build.
+Subversion configuration (*note Build system tools::).  No
+infrastructure tools are needed to do a normal build (barring bugs).
+
+   ---------- Footnotes ----------
+
+   (1) There is one exception in TL: the 'tangle-sh' and related rules
+use '$@' to mean the target name, a feature not present in all 'make's.
+This could be alleviated by laborious editing, but since there's no way
+to avoid GNU 'make' for builds of the entire tree, it does not seem
+worth the trouble.
 

source/README.2building

@@ -42,16 +42,7 @@ These iterations consist of two steps:
 the library and program modules, and finds (should find) nothing to be
 done.
 
-4.2 Build problems
-==================
-
-If configuring or building a module fails, you should first try to find
-and fix the problem.  Failing that, a possible workaround is to remove
-the subdirectory for that module from the build tree (so 'configure'
-won't try to run there, and finally rerun the top level 'make' (or
-'./Build' '--no-clean').
-
-4.3 Build in parallel
+4.2 Build in parallel
 =====================
 
 The TL build system carefully formulates dependencies as well as 'make'
@@ -63,7 +54,7 @@ N>1 or even 'make -j') that can considerably speed up the TL build.
 using a configure cache file, i.e., specifying the 'configure' option
 '-C' (recommended).
 
-4.4 Build distribution
+4.3 Build distribution
 ======================
 
 Running 'make dist' at the top level creates a tarball
@@ -76,7 +67,7 @@ Makefiles, but the result is not a complete or even usable TeX system,
 since all the support files are lacking; *note Installing::.  We do not
 actually distribute any such tarball, and have no plans to do so.
 
-4.5 Build one package
+4.4 Build one package
 =====================
 
 To build one package, the basic idea is to use the 'configure' option
@@ -87,8 +78,8 @@ invoked to build an individual program or library, first building any
 required libraries.
 
    Here is an example from start to finish for working on 'dvipdfm-x'.
-(Unfortunately, this does not suffice for building the TeX engines; see
-the next section.)
+Unfortunately, this does not suffice for building the TeX engines; see
+the next section.
 
      mkdir mydir && cd mydir  # new working directory
 
@@ -106,10 +97,17 @@ the next section.)
      # Do the make:
      make >&outm || echo fail
 
-     # Test:
+     # Run the tests:
      cd texk/dvipdfm-x
      make check
 
+     # Run the new binary in the buil tree, finding support files
+     # in a separate tree for a TeX Live release YYYY
+     # (Bourne shell syntax):
+     TEXMFROOT=/usr/local/texlive/YYYY \
+     TEXMFCNF=$TEXMFROOT/texmf-dist/web2c \
+     ./xdvipdfmx ...
+
    Then you can modify source files in 'mydir/texk/dvipdfm-x' and rerun
 'make' in 'mydir/Work/texk/dvipdfm-x' to rebuild; that build directory
 is where the binary ends up and where you can run a debugger, etc.
@@ -126,37 +124,60 @@ desired; check the output from 'configure --help'.  It is also a good
 idea to run 'make check' after making any changes, to ensure that
 whatever tests have been written still pass.
 
-   Finally, the above retrieves the entire TL source tree (several
-hundred megabytes).  It is natural to ask if this is really necessary.
-Strictly speaking, the answer is no, but it is vastly more convenient to
-do so.  If you cut down the source tree, you must also give additional
+Reducing source download size
+.............................
+
+The above retrieves the entire TL source tree (several hundred
+megabytes).  It is natural to ask if this is really necessary.  Strictly
+speaking, the answer is no, but it is vastly more convenient to do so.
+If you cut down the source tree, you must also give additional
 'configure' flags to individually disable using system versions of
 libraries, or the intricacies of the dependencies (such as 'teckit'
 requiring 'zlib') will have undesired side effects.  For an example of
 this approach, see the 'build-pdftex.sh' script in the 'pdftex'
 development source (details at <http://pdftex.org>), which is indeed
 such a cut-down TL source tree.
 
-   Some libraries and programs require C++11.  If you want to build with
-an older compiler lacking such support, you need to (re)move those
-source directories; specifying '--disable' for them does not suffice,
-unfortunately.  Specifically, before running 'configure':
+GCC used by default
+...................
+
+By default, the 'gcc' compilers will be used if present; otherwise,
+individual packages may use something different.  You can explicitly
+specify the compilers to be used with the environment variables 'CC',
+'CXX', and 'OBJCXX'.
+
+Removing C+11 dependency
+........................
 
-     rm -rf libs/icu libs/graphite2 texk/dvisvgm
+Some libraries and programs require C++11; one such is XeTeX. If you
+want to build with an older compiler lacking such support, you need to
+(re)move those source directories; unfortunately, specifying '--disable'
+for them does not suffice.  It's also necessary to specify
+'--disable-xetex' explicitly.  Specifically, before running 'configure
+--disable-xetex ...':
+
+     rm -rf libs/icu libs/graphite2 texk/dvisvgm texk/web2c/xetexdir
 
    Also, even with '--disable-all-pkgs', dependencies are (currently)
-checked.  For instance, if a (non-MacOSX) system does not have
+checked.  One notable case: if a (non-MacOS) system does not have
 'fontconfig', XeTeX cannot be built (*note Prerequisites::), and
 'configure' will terminate even with '--disable-xetex'.  To proceed
-without such dependencies, specify '--enable-missing' also.  (Patches to
-improve this would be most welcome.)
+without such dependencies, specify '--enable-missing' also.
 
-   By default, the 'gcc' compilers will be used if present; otherwise,
-individual packages may use something different.  You can explicitly
-specify the compilers to be used with the environment variables 'CC',
-'CXX', and 'OBJCXX'.
+   As of 2022, HarfBuzz also requires C++11.  Therefore even more would
+have to be disabled and removed, notably including 'luahbtex', the
+standard engine used for LuaLaTeX.  Removing that would not be
+acceptable for builds intended for distribution; but perhaps for testing
+the above information could still be useful.
+
+   In general, the TL 'configure' will run in all directories.
+Therefore a general workaround for build problems is to remove failing
+directories from the tree, and also specify the relevant '--disable-...'
+option(s).
+
+   Patches to improve all this would be most welcome.
 
-4.6 Build one engine
+4.5 Build one engine
 ====================
 
 Unfortunately, there is one common case where the steps in the preceding
@@ -170,16 +191,20 @@ original TeX:
 
      cd Work        # top build directory
      ../configure --without-x --disable-shared --disable-all-pkgs \
-                  --enable-tex --disable-synctex -C CFLAGS=-g CXXFLAGS=-g
+                  --enable-tex --disable-synctex --disable-xetex \
+                  --enable-missing -C CFLAGS=-g CXXFLAGS=-g
      make
      cd texk/web2c  # cd engine build directory
      make tex       # must specify target
 
    The first 'make' run will configure everything, and even build the
-libraries, even though the packages are disabled.  The source tree can
-be cut down to just what is needed for the given engine (the separate
-pdfTeX and LuaTeX source repositories do this, for example), but see
-caveats in previous section.
+libraries, even though the packages are disabled.
+
+   The source tree can be cut down to just what is needed for the given
+engine (the separate pdfTeX and LuaTeX source repositories do this, for
+example), but see caveats in previous section.  When the
+'--disable-xetex' and '--enable-missing' options are needed is also
+explained in the previous section.
 
    If you want to debug an X-related program or shared library setup, or
 other variants, change the 'configure' options accordingly.  Either
@@ -188,10 +213,31 @@ other variants, change the 'configure' options accordingly.  Either
    Then it is necessary to again specify the target engine ('tex', in
 the above) in the 'make'.
 
-   All this is somewhat unfortunate.  We hope to improve the situation
-in the future.  Patches are welcome.
+   All these complications are rather unfortunate.  Patches are welcome.
+
+Testing one engine
+..................
+
+To run only the tests for a given engine, say 'hitex':
+
+     make -C $ww check SUBDIRS=. TESTS='$(hitex_tests)'
+
+where '$ww' is the web2c build directory, that is,
+'ww=/wherever/Build/source/Work/texk/web2c'.
+
+   It's also possible to run individual tests the same way, using the
+test name exactly as specified in the '.am' file:
+
+     make -C $ww check SUBDIRS=. TESTS=hitexdir/tests/hello.test
+
+   If you get tired of looking at the 'Entering'/'Leaving directory'
+lines, you can add the (GNU) make option '--no-print-dir'.
+
+   You may find it useful to put lengthy incantations like this into a
+trivial shell script with a short name (say, 'hitst').  Then you just
+run 'hitst' and edit the file when necessary to change things around.
 
-4.7 Cross compilation
+4.6 Cross compilation
 =====================
 
 In a cross compilation a "build" system is used to create binaries to be
@@ -209,14 +255,14 @@ canonical host name, but note that this should _not_ be '--host=HOST'
 (*note (autoconf)Hosts and Cross-Compilation::).
 
    In order to build, e.g., 32-bit binaries with 'clang' on a 64-bit
-MacOSX system one could use:
+MacOS system one could use:
 
      TL_BUILD_ENV="CC='clang -arch i386' \
        CXX='clang++ -arch i386' \
        OBJCXX='clang++ -arch i386'" \
        ./Build --build=i386-apple-darwin
 
-4.7.1 Cross configuring
+4.6.1 Cross configuring
 -----------------------
 
 In a standard cross compilation, binaries for the host system cannot
@@ -262,7 +308,7 @@ C and C++ programs required for the build process as configure arguments
      BUILDCXXFLAGS=...
      BUILDLDFLAGS=...
 
-4.7.2 Cross problems
+4.6.2 Cross problems
 --------------------
 
 The fact that binaries for the host system cannot be executed on the