rename and update README* files, now generated from tlbuild.texi

git-svn-id: svn://tug.org/texlive/trunk@33605 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 73 insertions, 0 deletions

diff --git a/Build/source/README.2building b/Build/source/README.2building
new file mode 100644
index 00000000000..6111516eead
--- /dev/null
+++ b/Build/source/README.2building
@@ -0,0 +1,73 @@
+(This file was generated by makeinfo and splitinfo.gawk.)
+(Released under the old-style GNU documentation license;
+ see sources or other output files for full text.)
+
+4 Building
+**********
+
+The top-level 'Build' script is intended to simplify building the
+binaries distributed with TeX Live itself--we call this the "native" TL
+build.  It configures and makes everything in a subdirectory of the main
+build tree (default 'Work/'), installs everything in an other
+subdirectory (default 'inst/'), and finally runs 'make check'.  The
+exact directory and command names can be specified via environment
+variables and a few leading options.  All remaining arguments
+(assignments or options) are passed to the 'configure' script.  Please
+take a look at the script itself for more information; it is not
+complicated.
+
+   An alternative, and the one we will mainly discuss here, is to run
+'configure' and 'make' oneself in a suitable empty subdirectory.
+Building in the source directory itself is not supported (sorry).
+
+   Running the top-level 'configure' script configures the top level and
+the subdirectories 'libs', 'utils', and 'texk'.  Running 'make' at the
+top-level first iterates over all TeX-specific libraries, and then runs
+'make' in 'libs', 'utils', and 'texk' to iterate over all generic
+libraries, utility programs, and TeX-specific programs.  These
+iterations consist of two steps:
+
+  1. For each library or program module not yet configured, run
+     'configure', adding the configure option '--disable-build' if the
+     module need not be built, otherwise running 'make all'.
+
+  2. For each library or program module that must be built, run 'make'
+     for the selected target(s): 'default' or 'all' to (re-)build,
+     'check' to run tests, 'install', etc.
+
+   Running the top-level 'make' a second time iterates again over all
+the library and program modules, but finds (should find) nothing to be
+done unless some source files have been modified.
+
+   If configuring or building a module fails, you could either (a) find
+and fix the problem, or (b) remove the subdirectory for that module from
+the build tree, and rerun the top-level 'make' (or 'Build' with
+'--no-clean' as its first argument).
+
+   With the configure option '--disable-all-pkgs', all program and
+library modules are configured but none of them is built.  The
+'Makefile' for each such module contains all build rules and
+dependencies and can be invoked to build an individual program or
+library and causes to first build any required libraries.  This
+"build-on-demand" procedure is used, e.g., in the 'luatex' repository to
+build LuaTeX, essentially from a subset of the complete TeX Live tree.
+Similarly, when, e.g., building the original e-TeX has been disabled (as
+it is by default), one can run 'make etex' (or 'make etex.exe') in
+'texk/web2c/' to build e-TeX (although there is no comparably simple way
+to install e-TeX).
+
+   The TL build system carefully formulates dependencies as well as
+'make' rules when a tool (such as 'tangle', 'ctangle', or 'convert')
+creates several output files.  This allows for parallel builds ('make -j
+N' with N>1 or even 'make -j') that can considerably speed up the TL
+build.  Independently, speed-up can also be achieved by using a
+configure cache file, i.e., with the option '-C' (recommended).
+
+   Running 'make dist' at the top-level creates a tarball
+'tex-live-YYYY-MM-DD.tar.xz' from the TL source tree.  Running 'make
+dist-check' also verifies that this tarball suffices to build and
+install all of TL. (This is useful for checking consistency of the
+source tree and Makefiles, but the result is not a complete or even
+usable TeX system, since all the support files are lacking; see the next
+section.)
+