l3build (12dec17)

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

1 files changed, 68 insertions, 32 deletions

diff --git a/Master/texmf-dist/source/latex/l3build/l3build.dtx b/Master/texmf-dist/source/latex/l3build/l3build.dtx
index d5adf1a913f..2c674d4d521 100644
--- a/Master/texmf-dist/source/latex/l3build/l3build.dtx
+++ b/Master/texmf-dist/source/latex/l3build/l3build.dtx
@@ -57,17 +57,19 @@
 \luavarset{modules}{\{\}}{The list of all modules in a bundle (when not auto-detecting)}
 \luavarset{exclmodules}{\{\}}{Directories to be excluded from automatic module detection}
 \luavarseparator
-\luavarset{maindir}    {"."}                      {Top level directory for the module/bundle}
-\luavarset{docfiledir} {maindir}                  {Directory containing documentation files}
+\luavarset{maindir}     {"."}                      {Top level directory for the module/bundle}
+\luavarset{docfiledir}  {"."}                 {Directory containing documentation files}
+\luavarset{sourcfiledir}{"."}                 {Directory containing source files}
 \luavarset{supportdir} {maindir .. "/support"}    {Directory containing general support files}
-\luavarset{testfiledir}{maindir .. "/testfiles"}  {Directory containing test files}
+\luavarset{testfiledir}{"./testfiles"}  {Directory containing test files}
 \luavarset{testsuppdir}{testfiledir .. "/support"}{Directory containing test-specific support files}
 \luavarseparator
-\luavarset{distribdir}{maindir .. "/build/distrib"}{Directory for generating distribution structure}
-\luavarset{localdir}  {maindir .. "/build/local"}  {Directory for extracted files in \enquote{sandboxed} \TeX{} runs}
-\luavarset{testdir}   {maindir .. "/build/test"}   {Directory for running tests}
-\luavarset{typesetdir}{maindir .. "/build/doc"}    {Directory for building documentation}
-\luavarset{unpackdir} {maindir .. "/build/unpack"} {Directory for unpacking sources}
+\luavarset{builddir}  {maindir .. "/build"}   {Directory for building and testing}
+\luavarset{distribdir}{builddir .. "/distrib"}{Directory for generating distribution structure}
+\luavarset{localdir}  {builddir .. "/local"}  {Directory for extracted files in \enquote{sandboxed} \TeX{} runs}
+\luavarset{testdir}   {builddir .. "/test"}   {Directory for running tests}
+\luavarset{typesetdir}{builddir .. "/doc"}    {Directory for building documentation}
+\luavarset{unpackdir} {builddir .. "/unpack"} {Directory for unpacking sources}
 \luavarseparator
 \luavarset{ctandir}{distribdir .. "/ctan"}{Directory for organising files for CTAN}
 \luavarset{tdsdir} {distribdir .. "/tds"} {Directory for organised files into TDS structure}
@@ -112,6 +114,9 @@
 \luavarset{stdengine}    {"pdftex"}{Engine to generate \texttt{.tlg} file from}
 \luavarset{checkformat}  {"latex"} {Format to use for tests}
 \luavarseparator
+\luavarset{checkconfigs}{\{\}}{Configurations to use for tests}
+\luavarset{stdconfig}   {\meta{Main script}}{Standard test configuration}
+\luavarseparator
 \luavarset{typesetexe}{"pdflatex"}{Executable for compiling \texttt{doc(s)}}
 \luavarset{unpackexe} {"tex"}     {Executable for running \texttt{unpack}}
 \luavarset{zipexe}    {"zip"}     {Executable for creating archive with \texttt{ctan}}
@@ -209,7 +214,7 @@
 %    }^^A
 % }
 %
-% \date{Released 2017/12/06}
+% \date{Released 2017/12/12}
 %
 % \maketitle
 % \tableofcontents
@@ -304,6 +309,7 @@
 %
 % As well as these commands, the system recognises the options
 % \begin{itemize}
+%   \item \texttt{--config} (\texttt{-c}) Configuration(s) to use for testing
 % \item \texttt{--date} (\texttt{-d}) Date to use when setting version
 %   data
 % \item \texttt{--engine} (\texttt{-e}) Sets the engine to use for
@@ -618,31 +624,42 @@
 % \subsection{Multiple sets of tests}
 %
 % In most cases, a single set of tests will be appropriate for the module, with
-% a common set of configuration settings applying. However, there are situations
-% where you may need entirely independent sets of tests which have different
-% setting values, for example using different formats or where the entire set
-% will be engine-dependent. To support this, \pkg{l3build} offers the |--testfiledir|
-% (|-t|) command line option. When this is given with a directory argument it
-% overrides the \var{testfiledir} variable. Moreover, before the tests are run,
-% \pkg{l3build} will read |config.lua| within the directory (if available). This
-% should comprise a list of settings which apply to the tests in place of those in
-% the main build script.
-%
-% For example, for the core \LaTeXe{} tests the main test files are contained
-% in a directory |testfiles| and have \var{checksearch} set \var{false}. To test
-% font loading for \XeTeX{} and \LuaTeX{} there are a second set of tests in
-% |testfiles-TU| which use the short |config.lua| file shown in
-% Figure~\ref{fig:testfiledir}. These additional tests are then run using
-% |texlua build.lua check --testfiledir=testfiles-TU|.
-% \begin{figure}
-%   \begin{lstlisting}[frame=single,language={[5.2]Lua},gobble = 6]
-%     -- Special config for these tests
+% a common set of configuration settings applying. However, there are
+% situations where you may need entirely independent sets of tests which have
+% different setting values, for example using different formats or where the
+% entire set will be engine-dependent. To support this, \pkg{l3build} offers
+% the possibility of using multiple configurations for tests. This is supported
+% using the \var{checkconfigs} table. This is used to list the names of each
+% configuration (|.lua| file) which will be used to run tests.
+%
+% For example, for the core \LaTeXe{} tests the main test files are contained 
+% in a directory |testfiles|. To test font loading for \XeTeX{} and \LuaTeX{}
+% there are a second set of tests in |testfiles-TU| which use the short
+% |build-TU.lua| file shown in Figure~\ref{fig:configs}. To run both sets of
+% tests, the main |build.lua| file contains the setting
+% |checkconfigs = {"build", "config-TU"}|. This will cause \pkg{l3build} to run
+% first using no additional settings (\emph{i.e.}~reading the normal
+% |build.lua| file alone), then running \emph{also} loading the settings from
+% |config-TU.lua|.
+% \begin{figure} 
+%   \begin{lstlisting}[frame=single,language={[5.2]Lua},gobble = 6] 
+%     -- Special config for these tests 
 %     checksearch  = true
 %     checkengines = {"xetex","luatex"}
-%   \end{lstlisting}
-% \caption{The build script for the \pkg{xparse} module.}
-% \label{fig:testfiledir}
-% \end{figure}
+%     testfiledir  = "testfiles-TU"
+%   \end{lstlisting} 
+% \caption{The build script for the \pkg{xparse} module.} 
+% \label{fig:configs} 
+% \end{figure} 
+%
+% To allow selection of a one or more configurations, and to allow saving of
+% |.tlg| files in non-standard configurations, the |--config| (|-c|) option may
+% be used. This works in the same way as |--engine|: it takes a comma list of
+% configurations to apply, overriding \var{checkconfigs}.
+%
+% Note that the setting \var{stdconfig} is used to determine the \emph{vanilla}
+% configuration: this will typically be the name of the main script (usually
+% |build| for a standard |build.lua| file).
 %
 % \subsection{Dependencies}
 %
@@ -678,6 +695,18 @@
 % This ensures that the \pkg{l3kernel} code is included in all processes involved in unpacking and checking and so on.
 % The name of the script file in the dependency is set with the |scriptname| variable; by default these are |"build.lua"|.
 %
+% \subsection{Non-standard source layouts}
+%
+% A variety of source layouts are supported. In general, a \enquote{flat}
+% layout with all source files \enquote{here} is most convenient. However,
+% \pkg{l3build} supports placement of both code and documentation source
+% files in other locations using the \var{sourcefiledir} and \var{docfiledir}
+% variables. For pre-built trees, the glob syntax \texttt{**/*.\meta{ext}} may
+% be useful in these cases: this enables recursive searching in the appropriate
+% tree locations.
+%
+% A series of example layouts and matching |build.lua| files are available from
+% \url{https://github.com/latex3/l3build/tree/master/examples}.
 %
 % \subsection{Output normalisation}
 % \label{sec:norm}
@@ -1136,6 +1165,13 @@
 % apply to a case where multiple \BibTeX{} runs are needed (perhaps where
 % citations can appear within other references).
 %
+% Where there are complex requirements for pre-compiled demonstration
+% files, the hook |typeset_demo_hook()| is available: it runs after
+% copying files to the typesetting location but before the main typesetting
+% run. This may be used for example to script a very large number of
+% demonstrations using a single source (see the \pkg{beamer} package
+% for an example of this).
+%
 % \begin{figure}[!b]
 %   \begin{lstlisting}[frame=single,language={[5.2]Lua},gobble = 6]
 %     #!/usr/bin/env texlua