summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3build
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2017-12-12 22:36:25 +0000
committerKarl Berry <karl@freefriends.org>2017-12-12 22:36:25 +0000
commit961b81fc7fb95f7c1ffb545c43fdadf40a5c6672 (patch)
treebe6478b433364650306e3b31c672108c53857cdf /Master/texmf-dist/source/latex/l3build
parent0d506032e13fe359b86f88075101ad84924f22f6 (diff)
l3build (12dec17)
git-svn-id: svn://tug.org/texlive/trunk@46055 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/l3build')
-rw-r--r--Master/texmf-dist/source/latex/l3build/l3build.dtx100
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