Debian Codegraph @

texmf-dist/source/latex/l3build/l3build.dtx

raw
1 % \iffalse
2 %
3 % File l3build.dtx Copyright (C) 2014-2026 The LaTeX Project
4 %
5 % It may be distributed and/or modified under the conditions of the
6 % LaTeX Project Public License (LPPL), either version 1.3c of this
7 % license or (at your option) any later version. The latest version
8 % of this license is in the file
9 %
10 % https://www.latex-project.org/lppl.txt
11 %
12 % This file is part of the "l3build bundle" (The Work in LPPL)
13 % and all files in that bundle must be distributed together.
14 %
15 % -----------------------------------------------------------------------
16 %
17 % The development version of the bundle can be found at
18 %
19 % https://github.com/latex3/l3build
20 %
21 % for those people who are interested.
22 %
23 %<*driver>
24 \RequirePackage{expl3}
25 \documentclass[full]{l3doc}
26 \renewcommand\partname{Part}
27 \usepackage{multicol,needspace}
28 \makeatletter
29 \addtolength\columnsep{1em}
30 \renewcommand\columnseprule{0.4pt}
31 \def\@starttoc#1{%
32 \begin{multicols}{2}
33 \small
34 \makeatletter
35 \@input{\jobname.#1}%
36 \expandafter\newwrite\csname tf@#1\endcsname
37 \immediate\openout \csname tf@#1\endcsname \jobname.#1\relax
38 \@nobreakfalse
39 \end{multicols}}
40 \makeatother
41 \newenvironment{buildcmd}[1]{%
42 \bigskip\par\noindent\hspace{-\parindent}%
43 \fbox{\ttfamily \textcolor[gray]{0.5}{\$} l3build #1}%
44 \nopagebreak\smallskip\nopagebreak\par\nopagebreak\noindent\ignorespaces
45 }
46 {}
47 \makeatletter
48 \newcommand\luavar[1]{\@ifundefined{lua_#1}{\ERROR}{\texttt{\@nameuse{lua_#1}}}}
49 \newcommand\luavarset[3]{\@namedef{lua_#1}{#2}}
50 \newcommand\luavarseparator{}
51 \makeatother
52 \def\allluavars{
53 \luavarset{module}{""}{The name of the module}
54 \luavarset{bundle}{""}{The name of the bundle in which the module belongs (where relevant)}
55 \luavarset{ctanpkg}{bundle == "" and module or bundle}{Name of the CTAN package matching this module}
56 \luavarseparator
57 \luavarset{modules}{\{ \}}{The list of all modules in a bundle (when not auto-detecting)}
58 \luavarset{exclmodules}{\{ \}}{Directories to be excluded from automatic module detection}
59 \luavarseparator
60 \luavarset{maindir} {"."} {Top level directory for the module/bundle}
61 \luavarset{docfiledir} {"."} {Directory containing documentation files}
62 \luavarset{sourcefiledir}{"."} {Directory containing source files}
63 \luavarset{supportdir} {maindir .. "/support"} {Directory containing general support files}
64 \luavarset{testfiledir}{"./testfiles"} {Directory containing test files}
65 \luavarset{testsuppdir}{testfiledir .. "/support"}{Directory containing test-specific support files}
66 \luavarset{texmfdir}{maindir .. "/texmf"}{Directory containing support files in tree form}
67 \luavarset{textfiledir}{"."} {Directory containing plain text files}
68 \luavarseparator
69 \luavarset{builddir} {maindir .. "/build"} {Directory for building and testing}
70 \luavarset{distribdir}{builddir .. "/distrib"}{Directory for generating distribution structure}
71 \luavarset{localdir} {builddir .. "/local"} {Directory for extracted files in \enquote{sandboxed} \TeX{} runs}
72 \luavarset{resultdir} {builddir .. "/result"} {Directory for PDF files when using PDF-based tests}
73 \luavarset{testdir} {builddir .. "/test"} {Directory for running tests}
74 \luavarset{typesetdir}{builddir .. "/doc"} {Directory for building documentation}
75 \luavarset{unpackdir} {builddir .. "/unpacked"}{Directory for unpacking sources}
76 \luavarseparator
77 \luavarset{ctandir}{distribdir .. "/ctan"}{Directory for organizing files for CTAN}
78 \luavarset{tdsdir} {distribdir .. "/tds"} {Directory for organized files into TDS structure}
79 \luavarset{tdsroot}{"latex"}{Root directory of the TDS structure for the bundle/module to be installed into}
80 \luavarseparator
81 \luavarset{auxfiles} {\{"*.aux", "*.lof", "*.lot", "*.toc"\}}{Secondary files to be saved as part of running tests}
82 \luavarset{bibfiles} {\{"*.bib"\}}{\BibTeX{} database files}
83 \luavarset{binaryfiles} {\{"*.pdf", "*.zip"\}}{Files to be added in binary mode to zip files}
84 \luavarset{bstfiles} {\{"*.bst"\}}{\BibTeX{} style files}
85 \luavarset{checkfiles} {\{~\}}{Extra files unpacked purely for tests}
86 \luavarset{checksuppfiles} {\{ \}}{Files needed for performing regression tests}
87 \luavarset{cleanfiles} {\{"*.log", "*.pdf", "*.zip"\}}{Files to delete when cleaning}
88 \luavarset{demofiles} {\{ \}}{Files which show how to use a module}
89 \luavarset{docfiles} {\{ \}}{Files which are part of the documentation but should not be typeset}
90 \luavarset{dynamicfiles} {\{ \}}{Secondary files to cleared before each test is run}
91 \luavarset{excludefiles} {\{"*\string~","build.lua","config-*.lua"\}}{Files to ignore entirely (default for Emacs backup files)}
92 \luavarset{installfiles} {\{"*.sty","*.cls"\}}{Files to install to the \texttt{tex} area of the \texttt{texmf} tree}
93 \luavarset{makeindexfiles} {\{"*.ist"\}}{MakeIndex files to be included in a TDS-style zip}
94 \luavarset{scriptfiles} {\{ \}}{Files to install to the \texttt{scripts} area of the \texttt{texmf} tree}
95 \luavarset{scriptmanfiles} {\{ \}}{Files to install to the \texttt{doc/man} area of the \texttt{texmf} tree}
96 \luavarset{sourcefiles} {\{"*.dtx", "*.ins", "*-????-??-??.sty"\}}{Files to copy for unpacking}
97 \luavarset{tagfiles} {\{"*.dtx"\}}{Files for automatic tagging}
98 \luavarset{textfiles} {\{"*.md", "*.txt"\}}{Plain text files to send to CTAN as-is}
99 \luavarset{typesetdemofiles} {\{ \}}{Files to typeset before the documentation for inclusion in main documentation files}
100 \luavarset{typesetfiles} {\{"*.dtx"\}}{Files to typeset for documentation}
101 \luavarset{typesetsuppfiles} {\{ \}}{Files needed to support typesetting when \enquote{sandboxed}}
102 \luavarset{typesetsourcefiles}{\{ \}}{Files to copy to unpacking when typesetting}
103 \luavarset{unpackfiles} {\{"*.ins"\}}{Files to run to perform unpacking}
104 \luavarset{unpacksuppfiles} {\{ \}}{Files needed to support unpacking when \enquote{sandboxed}}
105 \luavarseparator
106 \luavarset{includetests}{\{"*"\}}{Test names to include when checking}
107 \luavarset{excludetests}{\{ \}} {Test names to exclude when checking}
108 \luavarseparator
109 \luavarset{checkdeps} {\{ \}}{List of dependencies for running checks}
110 \luavarset{typesetdeps}{\{ \}}{List of dependencies for typesetting docs}
111 \luavarset{unpackdeps} {\{ \}}{List of dependencies for unpacking}
112 \luavarseparator
113 \luavarset{checkengines}{\{"pdftex", "xetex", "luatex"\}}{Engines to check with \texttt{check} by default}
114 \luavarset{stdengine} {checkengines[1] or "pdftex"}{Engine to generate \texttt{.tlg} file from}
115 \luavarset{checkformat} {"latex"} {Format to use for tests}
116 \luavarset{specialformats}{\meta{table}} {Non-standard engine/format combinations}
117 \luavarset{\detokenize{test_types}} {\meta{table}} {Custom test variants}
118 \luavarset{\detokenize{test_order}} {\{"log", "pdf"\}} {Which kinds of tests to evaluate}
119 \luavarseparator
120 \luavarset{checkconfigs}{\{ \}}{Configurations to use for tests}
121 \luavarseparator
122 \luavarset{typesetexe} {"pdflatex"} {Executable for compiling \texttt{doc(s)}}
123 \luavarset{unpackexe} {"pdftex"} {Executable for running \texttt{unpack}}
124 \luavarset{biberexe} {"biber"} {Biber executable}
125 \luavarset{bibtexexe} {"bibtex8"} {\BibTeX{} executable}
126 \luavarset{makeindexexe} {"makeindex"}{MakeIndex executable}
127 \luavarset{curlexe} {"curl"} {Curl executable for \texttt{upload}}
128 \luavarseparator
129 \luavarset{checkopts} {"-interaction=nonstopmode"}{Options passed to engine when running checks}
130 \luavarset{typesetopts}{"-interaction=nonstopmode"}{Options passed to engine when typesetting}
131 \luavarset{unpackopts} {""} {Options passed to engine when unpacking}
132 \luavarset{biberopts} {""} {Biber options}
133 \luavarset{bibtexopts} {"-W"} {\BibTeX{} options}
134 \luavarset{makeindexopts}{""} {MakeIndex options}
135 \luavarseparator
136 \luavarset{checksearch} {true}{Switch to search the system \texttt{texmf} for during checking}
137 \luavarset{typesetsearch}{true}{Switch to search the system \texttt{texmf} for during typesetting}
138 \luavarset{unpacksearch} {true}{Switch to search the system \texttt{texmf} for during unpacking}
139 \luavarseparator
140 \luavarset{glossarystyle}{"gglo.ist"}{MakeIndex style file for glossary/changes creation}
141 \luavarset{indexstyle} {"gind.ist"}{MakeIndex style for index creation}
142 \luavarset{specialtypesetting}{\meta{table}} {Non-standard typesetting combinations}
143 \luavarseparator
144 \luavarset{forcecheckepoch}{true} {Force epoch when running tests}
145 \luavarset{forcedocepoch} {false} {Force epoch when typesetting}
146 \luavarseparator
147 \luavarset{asciiengines}{\{"pdftex"\}}{Engines which should log as pure ASCII}
148 \luavarset{checkruns} {1} {Number of runs to complete for a test before comparing the log}
149 \luavarset{forcecheckruns}{false} {Always run \texttt{checkruns} runs and never stop early}
150 \luavarset{ctanreadme}{"README.md"} {Name of the file to send to CTAN as \texttt{README.\meta{ext}}}
151 \luavarset{ctanzip}{ctanpkg ... "-ctan"}{Name of the zip file (without extension) created for upload to CTAN}
152 \luavarset{epoch} {1463734800} {Epoch (Unix date) to set for test runs}
153 \luavarset{flatten} {true} {Switch to flatten any source structure when sending to CTAN}
154 \luavarset{flattentds} {true} {Switch to flatten any source structure when creating a TDS structure}
155 \luavarset{maxprintline}{9999} {Length of line to use in log files}
156 \luavarset{errorline}{79} {Length of line to use for error line}
157 \luavarset{halferrorline}{50} {Links to the above: see standard \TeX{} documentation}
158 \luavarset{packtdszip} {false} {Switch to build a TDS-style zip file for CTAN}
159 \luavarset{ps2pdfopts} {""} {Options for \texttt{ps2pdf}}
160 \luavarset{typesetcmds} {""} {Instructions to be passed to \TeX{} when doing typesetting}
161 \luavarset{typesetruns}{3} {Number of cycles of typesetting to carry out}
162 \luavarset{recordstatus}{false} {Switch to include error level from test runs in \texttt{.tlg} files}
163 \luavarset{xetexnopdf}{true} {Disable generation of PDF using \texttt{xetex} engine, for log-based tests}
164 \luavarset{manifestfile} {"MANIFEST.md"} {Filename to use for the manifest file}
165 \luavarseparator
166 \luavarset{tdslocations}{\{ \}}{List of non-standard file installations}
167 \luavarset{tdsdirs}{\{ \}}{Map for ready-to-use source locations}
168 \luavarseparator
169 \luavarset{uploadconfig} {\meta{table}} {Metadata to describe the package for CTAN (see Table~\vref{tab:upload-setup})}
170 \luavarset{uploadconfig.pkg}{ctanpkg}{Name of the CTAN package}
171 \luavarseparator
172 \luavarset{bakext}{".bak"}{Extension of backup files}
173 \luavarset{dviext}{".dvi"}{Extension of DVI files}
174 \luavarset{lvtext}{".lvt"}{Extension of log-based test files}
175 \luavarset{tlgext}{".tlg"}{Extension of log-based test output}
176 \luavarset{tpfext}{".tpf"}{Extension of PDF-based test output}
177 \luavarset{lveext}{".lve"}{Extension of auto-generating test file output}
178 \luavarset{logext}{".log"}{Extension of checking output, before processing it into a \texttt{.tlg}}
179 \luavarset{pvtext}{".pvt"}{Extension of PDF-based test files}
180 \luavarset{pdfext}{".pdf"}{Extension of PDF file for checking and saving}
181 \luavarset{psext} {".ps"} {Extension of PostScript files}
182 }
183 \allluavars
184
185
186 \newcommand\luavartypeset{%
187 \begingroup
188 \frenchspacing
189 \renewcommand\luavarset[3]{
190 \texttt{##1} & \texttt{##2} & ##3 \\
191 }
192 \renewcommand\luavarseparator{\midrule}
193 \setlength\LTleft{-0.21\linewidth}
194 \begin{longtable}{@{}%
195 >{\small}
196 p{0.20\linewidth}
197 @{\hspace{0.03\linewidth}}
198 >{\footnotesize\hangindent=1em}
199 p{0.34\linewidth}
200 @{\hspace{0.03\linewidth}}
201 >{\small\raggedright\arraybackslash}
202 p{0.63\linewidth}
203 @{}}
204 \toprule
205 Variable & Default & Description \\
206 \midrule\endhead
207 \allluavars
208 \bottomrule
209 \end{longtable}
210 \endgroup
211 }
212 \newcommand\var{\texttt}
213 \usepackage[procnames]{listings}
214 \lstset{
215 basicstyle=\ttfamily\small,
216 numbers=left,
217 numberstyle={\tiny\color[gray]{0.4}},
218 language={[5.2]Lua},
219 gobble=4,
220 }
221 \lstnewenvironment{floating-listing}[1][]
222 {%
223 \lstset{
224 frame=single,
225 float,
226 captionpos=b,
227 abovecaptionskip=\bigskipamount,
228 floatplacement=htb,
229 #1
230 }%
231 }
232 {}
233 \usepackage{shortvrb}
234 \usepackage{enumitem}
235 \usepackage[nospace]{varioref}
236 \usepackage{longtable}
237 \MakeShortVerb\|
238 \begin{document}
239 \DocInput{\jobname.dtx}
240 \end{document}
241 %</driver>
242 % \fi
243 %
244 % \title{^^A
245 % The \pkg{l3build} package\\ Checking and building packages^^A
246 % }
247 %
248 % \author{^^A
249 % The \LaTeX{} Project\thanks
250 % {^^A
251 % E-mail:
252 % \href{mailto:[email protected]}
253 % {[email protected]}^^A
254 % }^^A
255 % }
256 %
257 % \date{Released 2026-03-26}
258 %
259 % \maketitle
260 % \tableofcontents
261 %
262 % \begin{documentation}
263 %
264 % \section{The \pkg{l3build} system}
265 %
266 % \subsection{Introduction}
267 %
268 % The \pkg{l3build} system is a Lua script for building \TeX{} packages, with particular emphasis on regression testing.
269 % It is written in cross-platform Lua code, so can be used by any modern \TeX{} distribution with the |texlua| interpreter.
270 % Wrapper functions/binaries are distributed in the standard \TeX{} distributions so that the script can be called using
271 % \texttt{l3build} on the command line; run without arguments it prints a brief synopsis of its usage.
272 %
273 % The \pkg{l3build} system is designed for packages written in any \TeX\ dialect; its defaults are set up for \LaTeX\ packages written in the DocStrip style. (Caveat: minimal testing has yet been performed for non-\LaTeX{} packages.)
274 %
275 % Test files are written as standalone \TeX{} documents using the |regression-test.tex| setup file; documentation on writing these tests is discussed in Section~\vref{sec:writing-tests}.
276 %
277 % Each package will define its own |build.lua| configuration file which both sets variables (such as the name of the package) and may also provide custom functions.
278 %
279 % \pagebreak[2]
280 % A standard package layout might look something like the following:
281 % \begin{Verbatim}[fontsize=\small]
282 % abc/
283 % abc.dtx
284 % abc.ins
285 % build.lua
286 % README.md
287 % support/
288 % testfiles/
289 % \end{Verbatim}
290 % Most of this should look fairly self-explanatory.
291 % The top level |support/| directory (optional) would contain any necessary files for compiling documentation, running regression tests, and so on.
292 %
293 % The \pkg{l3build} system is also capable of building and checking \emph{bundles} of packages.
294 % To avoid confusion, we refer to either a standalone package or a package within a bundle as a \emph{module}.
295 %
296 % For example, within the \LaTeX{} project we have the \textsf{l3packages} bundle which contains the \textsf{xparse}, \textsf{xtemplate}, etc., modules.
297 % These are all built and distributed as one bundle for installation, distribution \emph{via} CTAN and so forth.
298 %
299 % Each module in a bundle will have its own build script, and a bundle build script brings them all together.
300 % A standard bundle layout would contain the following structure.
301 % \begin{Verbatim}
302 % mybundle/
303 % build.lua
304 % support/
305 % yyy/ zoo/
306 % build.lua build.lua
307 % README.md README.md
308 % testfiles/ testfiles/
309 % yyy.dtx zoo.dtx
310 % yyy.ins zoo.ins
311 % \end{Verbatim}
312 % All modules within a bundle must use the same build script name.
313 %
314 % In a small number of cases, the name used by CTAN for a module or bundle is
315 % different from that used in the installation tree. For example, the \LaTeXe{}
316 % kernel is called \pkg{latex-base} by CTAN but is located inside
317 % \texttt{\meta{texmf}/tex/latex/base}. This can be handled by using
318 % \var{ctanpkg} for the name required by CTAN to override the standard
319 % value.
320 %
321 % The |testfiles/| folder is local to each module, and its layout consists of a series of regression tests with their outputs.
322 % \begin{Verbatim}
323 % testfiles/
324 % test1.lvt
325 % test1.tlg
326 % ...
327 % support/
328 % my-test.cls
329 % \end{Verbatim}
330 % Again, the |support/| directory contains any files necessary to run some or all of these tests.
331 %
332 % When the build system runs, it creates a directory |build/| for various unpacking, compilation, and testing purposes.
333 % For a module, this build folder can be in the main directory of the package itself, but for a bundle it should be common for the bundle itself and for all modules within that bundle.
334 % A |build/| folder can be safely deleted; all material within is re-generated for each command of the \pkg{l3build} system.
335 %
336 % \subsection{The \texttt{build.lua} file}
337 %
338 % The \texttt{build.lua} file used to control \pkg{l3build} is a simple Lua file
339 % which is read during execution. In the current release of \pkg{l3build},
340 % \texttt{build.lua} is read automatically and can access all of the global
341 % functions provided by the script. Thus it may contain a simple list of
342 % variable settings \emph{or} additional code to customize the build
343 % process.
344 %
345 %The example scripts given in Section~\vref{sec:examples} largely cover the required knowledge in Lua programing.
346 % For a more advanced usage, one may consult general Lua documentations including \url{https://www.lua.org/manual/5.3/manual.html} and for the few |texlua| specific additions see section 4.2 of the \LuaTeX{} manual available locally with |texdoc luatex| command line or at \url{https://www.pragma-ade.com/general/manuals/luatex.pdf}.
347 %
348 % \subsection{Main build targets}
349 %
350 % In the working directory of a bundle or module, \pkg{l3build} is run by executing
351 % \begin{center}
352 % \texttt{l3build \meta{target} [\meta{option(s)}]}
353 % \end{center}
354 % where \texttt{\meta{target}} can be one of the following:
355 % \begin{itemize}[noitemsep]\ttfamily
356 % \item check
357 % \item check \meta{name(s)}
358 % \item clean
359 % \item ctan
360 % \item doc
361 % \item doc \meta{name(s)}
362 % \item install
363 % \item manifest
364 % \item save \meta{name(s)}
365 % \item tag [\meta{tag name}]
366 % \item uninstall
367 % \item unpack
368 % \item upload [\meta{version}]
369 % \end{itemize}
370 % These targets are described below.
371 %
372 % As well as these targets, the system recognizes the options
373 % \begin{itemize}
374 % \item |--config| (|-c|) Configuration(s) to use for testing
375 % \item |--date| (|-d|) Date to use when tagging data
376 % \item |--debug| Runs the target in debug mode (not supported by all targets)
377 % \item |--dev| Runs \LaTeX{} checks using the development format
378 % \item |--dirty| Skips cleaning up of the test area
379 % \item |--dry-run| Runs the \texttt{install} target but does not copy
380 % any files: simply lists those that would be installed
381 % \item |--email| Sets the email address for CTAN upload
382 % \item |--engine| (|-e|) Sets the engine(s) to use for testing
383 % \item |--epoch| Sets the epoch for typesetting and testing
384 % \item |--file| (|-F|) Takes the upload announcement from the given file
385 % \item |--first| Name of the first test to run
386 % \item |--full| Instructs the \texttt{install} target to include the
387 % \texttt{doc} and \texttt{source} trees
388 % \item |--halt-on-error| (|-H|) Specifies that checks
389 % should stop as soon as possible, rather than running all requested
390 % tests; the difference file is printed in the terminal directly in the case of failure
391 % \item |--last| Name of the last test to run
392 % \item |--message| (|-m|) Text for upload announcement
393 % \item |--quiet| (|-q|) Suppresses output from unpacking
394 % \item |--rerun| Runs tests without unpacking/set up
395 % \item |--show-log-on-error| To be used in addition to |--halt-on-error| and results
396 % in the full \texttt{.log} file of a failed test to be shown on the console
397 % \item |--show-saves| (|-S|) When tests fail, prints the \texttt{l3build save} commands needed
398 % to regenerate the tests assuming that the failures were false negatives.
399 % \item |--shuffle| Shuffles the order in which tests run
400 % \item |--stdengine| (|-s|) Run tests only with the standard engine (which can vary between
401 % configurations)
402 % \item |--texmfhome| Sets the location of the user tree for installing
403 % \end{itemize}
404 %
405 % \begin{buildcmd}{check}
406 % The |check| command runs the entire test suite.
407 % This involves iterating through each \texttt{.lvt} file in the test directory (specified by the \var{testfiledir} variable), compiling each test in a \enquote{sandbox} (a directory specified by \var{testdir}), and comparing the output against each matching predefined \texttt{.tlg} file.
408 %
409 % If changes to the package or the typesetting environment have affected the results, the check for that file fails.
410 % A |diff| of the expected to actual output should then be inspected to determine the cause of the error; it is located in the \var{testdir} directory (default \luavar{testdir}).
411 %
412 % On Windows, the |diff| program is not available and so |fc| is used instead
413 % (generating an |.fc| file). Setting the environmental variables |diffexe|
414 % and |diffext| can be used to adjust the choice of comparison made: the standard
415 % values are
416 % \begin{itemize}
417 % \item[Windows] |diffext = .fc|, |diffexe = fc /n|
418 % \item[*nix] |diffext = .diff|, |diffexe = diff -c --strip-trailing-cr|
419 % \end{itemize}
420 %
421 % The following files are moved into the \enquote{sandbox} for the |check| process:
422 % \begin{itemize}
423 % \item all \var{installfiles} after unpacking;
424 % \item all \var{checkfiles} after unpacking;
425 % \item any files in the directory \var{testsuppdir};
426 % \item any files that match \var{checksuppfiles} in the \var{supportdir}.
427 % \end{itemize}
428 % The \var{texmfdir} is also made available to the tests (if defined and
429 % non-empty).
430 % This range of possibilities allow sensible defaults but significant flexibility for defining your own test setups.
431 %
432 % Checking can be performed with any or all of the `engines' \texttt{pdftex}, \texttt{xetex}, and \texttt{luatex}.
433 % By default, each test is executed with all three, being compared against the \texttt{.tlg} file produced from the \var{pdftex} engine (these defaults are controlled by the |checkengines| and |stdengine| variable, respectively).
434 % The standard engine to use is typically chosen automatically as the first entry in
435 % \var{checkengines}, but may be set manually using \var{stdengine}. Where multiple
436 % configurations are used and need adjustment to the standard engine, this does
437 % need to be given explicitly using \var{stdengine}.
438 % The format used for tests can be altered by setting \var{checkformat}: the default setting \texttt{latex} means that tests are run using \emph{e.g.}~\texttt{pdflatex}, whereas setting to \texttt{tex} will run tests using \emph{e.g.}~\texttt{pdftex}.
439 % (Currently, this should be one of \texttt{latex}, \texttt{latex-dev}, \texttt{tex}, or
440 % \texttt{context}.)
441 % To perform the check, the engine typesets each test up to \var{checkruns} times.
442 % More detail on this in the documentation on |save|.
443 % Options passed to the binary are those defined in the variable
444 % \var{checkopts}, followed by the engine-specific ones for the current
445 % \var{checkformat} (stored in table \var{specialformats}), if exist.
446 %
447 % By default, |texmf| trees are searched for input files when checking. This can be disabled by setting \var{checksearch} to |false|: isolation provides confidence that the tests cannot accidentally be running with incorrect files installed in the main distribution or |hometexmf|.
448 %
449 % The \var{texmfdir} variable sets a directory which is made available for
450 % recursive searching \emph{in addition} to any files copied from
451 % \var{supportdir}. No subdivison of \var{texmfdir} is attempted, thus it
452 % should not contain multiple files with the same name. The \var{texmfdir}
453 % is made available both to checking and typesetting.
454 % \end{buildcmd}
455 %
456 %
457 % \begin{buildcmd}{check \meta{name(s)}}
458 % Checks only the test \texttt{\meta{name(s)}.lvt}.
459 % All engines specified by \var{checkengines} are tested unless the command
460 % line option |--engine| (or |-e|) has been given a comma-separated list to
461 % limit testing to selected |checkengines|.
462 % Normally testing is preceded by unpacking
463 % source files and copying the result plus any additional support to the
464 % test directory: this may be skipped using the |--rerun| (|-r|) option.
465 % \end{buildcmd}
466 %
467 % \begin{buildcmd}{clean}
468 % This target is meant as preparation for other targets, for example |ctan|.
469 % It removes the contents of \var{distribdir} and all temporary files used for package bundling and regression testing.
470 % These are all files within the directories \var{unpackdir}, \var{testdir}, \var{typesetdir} and \var{localdir}.
471 % In addition, all the files in \var{maindir} (the directory of |build.lua| in the standard layout),
472 % \var{sourcefiledir} and \var{docfiledir} are removed when matched by \var{cleanfiles}
473 % but not by \var{sourcefiles}.
474 % In a standard way are removed |.log| and |.pdf| files from the |doc| target and
475 % |.zip| files from the |ctan| target.
476 %
477 % When applied to a bundle, the |clean| target is first applied to each
478 % embedded modules (listed in |modules|).
479 % In addition, all the files in the directory of |build.lua| are removed
480 % when matched by \var{cleanfiles}, while ignoring \var{sourcefiles}. Finally |ctandir| and |tdsdir| are removed.
481 % \end{buildcmd}
482 %
483 %
484 % \begin{buildcmd}{ctan}
485 % Creates an archive of the package and its documentation, suitable for uploading to CTAN.
486 % The archive is compiled in \var{distribdir}, and if the results are successful the resultant |.zip| file is moved into the same directory as the build script.
487 % If \var{packtdszip} is set true then the building process includes a |.tds.zip| file containing the `\TeX\ Directory Structure' layout of the package or bundle.
488 % The archive therefore may contain two `views' of the package:
489 % \begin{Verbatim}
490 % abc.zip/
491 % abc/
492 % abc.dtx
493 % abc.ins
494 % abc.pdf
495 % README.md
496 % abc.tds.zip/
497 % doc/latex/abc/
498 % abc.pdf
499 % README.md
500 % source/latex/abc/
501 % abc.dtx
502 % abc.ins
503 % tex/latex/abc/
504 % abc.sty
505 % \end{Verbatim}
506 % The files copied into the archive are controlled by a number of variables.
507 % The `root' of the TDS structure is defined by \var{tdsroot}, which is \luavar{tdsroot} by default. Plain users would redefine this to |"plain"| (or perhaps |"generic"|), for example.
508 % The build process for a |.tds.zip| file currently assumes a `standard'
509 % structure in which all extracted files should be placed inside the |tex|
510 % tree in a single directory, as shown above. If the module includes any
511 % \BibTeX{} or MakeIndex styles these will be placed in the appropriate
512 % subtrees.
513 %
514 % \pagebreak[2]
515 % The |doc| tree is constructed from:
516 % \begin{itemize}
517 % \item all files matched by \var{demofiles},
518 % \item all files matched by \var{docfiles},
519 % \item all files matched by \var{typesetfiles} with their extension replaced with |.pdf|,
520 % \item all files matched by \var{textfiles},
521 % \item all files matched by \var{bibfiles}.
522 % \end{itemize}
523 % The |source| tree is constructed from all files matched by \var{typesetfiles} and \var{sourcefiles}.
524 % The |tex| tree from all files matched by \var{installfiles}.
525 %
526 % The special case \var{ctanreadme} is used to allow renaming of a local
527 % |foo.xyz| file to |README.xyz|. The local |foo.xyz| should be listed in
528 % \var{textfiles}, and will be renamed as part of constructing the CTAN
529 % structure. The file extension will be unchanged by this process.
530 %
531 % Files that should always be excluded from the archive are matched against the \var{excludefiles} variable; by default this is \luavar{excludefiles}, which match Emacs' autosave files.
532 %
533 % Binary files should be specified with the \var{binaryfiles} variable (default \luavar{binaryfiles}); these are added to the zip archive without normalizing line endings (text files are automatically converted to Unix-style line endings).
534 %
535 % The intermediate build directories \var{ctandir} and \var{tdsdir} are used to construct the archive.
536 % \end{buildcmd}
537 %
538 %
539 % \begin{buildcmd}{doc}
540 % Compiles documentation files in the \var{docfiledir}, using \var{typesetdir}
541 % as the working directory.
542 % In the absence of one or more file names, all documentation is typeset;
543 % a file list may be specified in \var{typesetfiles} or given at the command line for selective typesetting.
544 % If the compilation is successful the |.pdf| is moved back into the main directory.
545 %
546 % The documentation compilation is performed with the \var{typesetexe} binary (default \texttt{pdflatex}), with options \var{typesetopts}.
547 % Additional \TeX{} material defined in \var{typesetcmds} is passed to the document (e.g., for writing |\PassOptionsToClass{l3doc}{letterpaper}|, and so on---note that backslashes need to be escaped in Lua strings).
548 %
549 % Files that match |typesetsuppfiles| in the |support| directory (|supportdir|) are copied into the |build/doc| directory (|typesetdir|) for the typesetting compilation process.
550 % Additional dependencies listed in the \var{typesetdeps} variable (empty by default) will also be installed.
551 %
552 % Source files specified in \var{sourcefiles} and \var{typesetsourcefiles}
553 % are unpacked before the typesetting takes place. (In most cases
554 % \var{typesetsourcefiles} will be empty, but may be used where there are
555 % files to unpack \emph{only} for typesetting.)
556 %
557 % If \var{typesetsearch} is \code{true} (default), standard \texttt{texmf} search trees are used in the typesetting compilation. If set to false, \emph{all} necessary files for compilation must be included in the |build/local| sandbox.
558 %
559 % \end{buildcmd}
560 %
561 % \begin{buildcmd}{doc \meta{name(s)}}
562 % Typesets only the files with the \meta{name(s)} given, which should be the
563 % basename without any extension.
564 % \end{buildcmd}
565 %
566 % \begin{buildcmd}{install}
567 % Copies all package files (defined by \var{installfiles}) into the user's home \texttt{texmf} tree in the form of the \TeX\ Directory Structure.
568 % The location of the user tree can be adjusted using the |--texmfhome| switch:
569 % the standard setting is the location set as |TEXMFHOME|.
570 % \end{buildcmd}
571 %
572 % \begin{buildcmd}{save \meta{name(s)}}
573 % This command runs through the same execution as |check| for a specific test(s) \texttt{\meta{name(s)}.lvt}.
574 % This command saves the output of the test to a |.tlg| file.
575 % This file is then used in all subsequent checks against the \texttt{\meta{name}.lvt} test.
576 %
577 % If the |--engine| (or |-e|) is specified (one or more comma-separated engines
578 % in |checkengines|), the saved output is stored in
579 % \texttt{\meta{name}.\meta{engine}.tlg} for non-standard engines.
580 % This is necessary if running the test through a different engine produces
581 % a different output. A normalization process is performed when checking to
582 % avoid common differences such as register allocation; full details are listed
583 % in Section~\vref{sec:norm}.
584 %
585 % If the \var{recordstatus} variable is set \var{true}, additional information
586 % will be added to the \texttt{.tlg} to record the \enquote{exit status} of the
587 % typesetting compilation of the \texttt{.lvt} file. If the typesetting compilation
588 % completed without throwing an error (due to \TeX\ programming errors, for example),
589 % the \enquote{exit status} is zero, else non-zero.
590 % \end{buildcmd}
591 %
592 % \begin{buildcmd}{manifest}
593 % Generates a `manifest' file which lists the files of the package as known to \pkg{l3build}.
594 % The filename of this file (by default \luavar{manifestfile}) can be set with the variable \var{manifestfile}.
595 %
596 % The intended purpose of this manifest file is to include it within a package as metadata.
597 % This would allow, say, for the copyright statement for the package to refer to the
598 % manifest file rather than requiring the author to manually keep a file list up-to-date
599 % in multiple locations. The manifest file can be structured and documented with a degree
600 % of flexibility. Additional information is described in Section~\vref{sec:manifest}.
601 %
602 % In order for \texttt{manifest} to detect derived and typeset files, it should be run
603 % \emph{after} running \texttt{unpack} and \texttt{doc}. If \texttt{manifest}
604 % is run after also running \texttt{ctan} it will include the files included
605 % in the CTAN and TDS directories as well.
606 %
607 % Presently, this means that if you wish to include an up-to-date manifest file
608 % as part of a \texttt{ctan} release, you must run
609 % \texttt{ctan} / \texttt{manifest} / \texttt{ctan}.
610 % Improvements to this process are planned for the future.
611 % \end{buildcmd}
612 %
613 % \begin{buildcmd}{tag [\meta{tag name}]}
614 % Applies the Lua |update_tag()| function to modify the contents of all the files
615 % specified by |tagfiles|; this function updates the `release tag' (or package version)
616 % and date.
617 % The tag is given as the optional command line argument \meta{tag name} and the date using
618 % |--date| (or |-d|). If not given, the date will default to the current date in
619 % ISO format (YYYY-MM-DD). If no \meta{tag name} is given, the tag will default to |nil|.
620 % Both are passed as arguments to the |update_tag()| function.
621 %
622 % The standard setup does nothing unless tag update is set up by defining a custom |update_tag()| function. See Section~\vref{sec:tagging} for full details on this feature.
623 % \end{buildcmd}
624 %
625 % \begin{buildcmd}{unpack}
626 % This is an internal target that is normally not needed on user level.
627 % It unpacks all files into the directory defined by \var{unpackdir}. This occurs before other build commands such as |doc|, |check|, etc.
628 %
629 % The unpacking process is performed by executing the \var{unpackexe} (default \texttt{pdftex}) with options \var{unpackopts} on all files defined by the \var{unpackfiles} variable; by default, all files that match \luavar{unpackfiles}.
630 %
631 % If additional support files are required for the unpacking process, these can be enumerated in the \var{unpacksuppfiles} variable.
632 % Dependencies for unpacking are defined with \var{unpackdeps}.
633 %
634 % By default this process allows files to be accessed in all standard |texmf| trees; this can be disabled by setting \var{unpacksearch} to |false|.
635 % \end{buildcmd}
636 %
637 % \begin{buildcmd}{upload [\meta{version}]}
638 % This target uses \texttt{curl} to upload the package zip file (created using \texttt{ctan}) to CTAN.
639 % To control the metadata used to upload the package, the \texttt{uploadconfig} table should be populated with a number of fields.
640 % These are documented in Table~\vref{tab:upload-setup}.
641 % Missing required fields will result in an interactive prompt for manual entry. When given, \meta{version} overrides \texttt{uploadconfig.version}.
642 %
643 % See Section~\vref{sec:upload} for full details on this feature.
644 % \end{buildcmd}
645 %
646 % \subsection{Example build scripts}
647 % \label{sec:examples}
648 %
649 % An example of a standalone build script for a package that uses self-contained |.dtx| files is shown in Listing~\vref{lst:breqn}.
650 % Here, the |module| only is defined, and since it doesn't use |.ins| files so the variable \var{unpackfiles} is redefined to run |tex| on the |.dtx| files instead to generate the necessary |.sty| files.
651 % There are some PDFs in the repository that shouldn't be part of a CTAN submission, so they're explicitly excluded, and here unpacking is done `quietly' to minimize console output when building the package.
652 %
653 % \begin{floating-listing}[caption=The build configuration for the \pkg{breqn} package.,label=lst:breqn]
654 % -- Build configuration for breqn
655 %
656 % module = "breqn"
657 %
658 % unpackfiles = {"*.dtx"}
659 % excludefiles = {"*/breqn-abbr-test.pdf",
660 % "*/eqbreaks.pdf"}
661 % unpackopts = "-interaction=batchmode"
662 % \end{floating-listing}
663 %
664 % An example of a bundle build script for \pkg{l3packages} is shown in Listing~\vref{lst:bundle}.
665 % Note for \LaTeX{} we use a common file to set all build variables in one place, and the path to the |l3build.lua| script is hard-coded so we always use our own most recent version of the script.
666 % An example of an accompanying module build script is shown in Listing~\vref{lst:module}.
667 %
668 % \begin{floating-listing}[caption={The build script for the \pkg{l3packages} bundle.},label={lst:bundle}]
669 % -- Build script for LaTeX "l3packages" files
670 %
671 % -- Identify the bundle: there is no module as this is the "driver"
672 % bundle = "l3packages"
673 %
674 % -- Location of main directory: use Unix-style path separators
675 % maindir = ".."
676 % \end{floating-listing}
677 %
678 % \begin{floating-listing}[caption={The build script for the \pkg{xparse} module.},label={lst:module}]
679 % -- Build script for LaTeX "xparse" files
680 %
681 % -- Identify the bundle and module:
682 % bundle = "l3packages"
683 % module = "xparse"
684 %
685 % -- Location of main directory: use Unix-style path separators
686 % -- Should match that defined by the bundle.
687 % maindir = "../.."
688 % \end{floating-listing}
689 %
690 % A collection of full examples (source files in various layouts) are available
691 % at \url{https://github.com/latex3/l3build/tree/main/examples}.
692 %
693 % \subsection{Variables}
694 %
695 % This section lists all variables defined in the |l3build.lua| script that are available for customization.
696 %
697 % \luavartypeset
698 %
699 % \subsection{Interaction between tests}
700 %
701 % Tests are run in a single directory, so whilst they are may be isolated from
702 % the system \TeX{} tree they do share files. This may be significant if
703 % installation-type files are generated during a test, for example by a
704 % |filecontents| environment in \LaTeX{}. Typically, you should set up your
705 % tests such that they do not use the same names for such files: this may lead
706 % to variable outcomes depending on the order in which tests are run.
707 %
708 % Where files need to be removed between different engine tests, they should
709 % be listed in |dynamicfiles|. If the files are generated in a directory
710 % structure, e.g.~by \pkg{minted}, then a recursive glob will be needed,
711 % for example
712 % \begin{Verbatim}
713 % dynamicfiles = {"_minted-*/**"}
714 % \end{Verbatim}
715 %
716 % \subsection{Selective running of tests}
717 %
718 % The variables |includetests| and |excludetests| may be used to select which
719 % tests are run: these variables take raw test \emph{names} not full file names.
720 % The list of tests in |excludetests| overrides any matches in |includetests|,
721 % meaning that tests can be disabled selectively. It also makes it possible
722 % to disable test on for example a platform basis: the |texlua| specific variable
723 % |os.type| may be used to set |excludetests| only on some systems.
724 %
725 % \subsection{Multiple sets of tests}
726 %
727 % In most cases, a single set of tests will be appropriate for the module, with
728 % a common set of configuration settings applying. However, there are
729 % situations where you may need entirely independent sets of tests which have
730 % different setting values, for example using different formats or where the
731 % entire set will be engine-dependent. To support this, \pkg{l3build} offers
732 % the possibility of using multiple configurations for tests. This is supported
733 % using the \var{checkconfigs} table. This is used to list the names of each
734 % configuration (|.lua| file) which will be used to run tests.
735 %
736 % For example, for the core \LaTeXe{} tests the main test files are contained
737 % in a directory |testfiles|. To test font loading for \XeTeX{} and \LuaTeX{}
738 % there are a second set of tests in |testfiles-TU| which use a short
739 % |config-TU.lua| file similar to the one shown in Listing~\vref{lst:configs}.
740 % To run both sets of tests, the main |build.lua| file contains the setting
741 % |checkconfigs = {"build", "config-TU"}|. This will cause \pkg{l3build} to run
742 % first using no additional settings (\emph{i.e.}~reading the normal
743 % |build.lua| file alone), then running \emph{also} loading the settings from
744 % |config-TU.lua|.
745 % \begin{floating-listing}[caption={Example of using additional (or overriding) settings for configuring tests in a different subdirectory.},label={lst:configs}]
746 % -- Special config for these tests
747 % stdengine = "xetex"
748 % checkengines = {"xetex","luatex"}
749 % checksearch = true
750 % testfiledir = "testfiles-TU"
751 % \end{floating-listing}
752 %
753 % To allow selection of one or more configurations, and to allow saving of
754 % |.tlg| files in non-standard configurations, the |--config| (|-c|) option may
755 % be used. This works in the same way as |--engine|: it takes a comma-separated
756 % list of configurations to apply, overriding \var{checkconfigs}. For example,
757 % in the directory containing |config-TU.lua|, you can use
758 % |l3build check -cconfig-TU <name(s)>| and |l3build save -cconfig-TU <name(s)>|
759 % to check and save tests in |testfiles-TU| directory.
760 %
761 % \subsection{Dependencies}
762 %
763 % If you have multiple packages that are developed separately but still interact in some way, it's often desirable to integrate them when performing regression tests.
764 % For \LaTeX{}, for example, when we make changes to \pkg{l3kernel} it's important to check that the tests for \pkg{l3packages} still run correctly, so it's necessary to include the \pkg{l3kernel} files in the build process for \pkg{l3packages}.
765 %
766 % In other words, \pkg{l3packages} is \emph{dependent} on \pkg{l3kernel}, and this is specified in \pkg{l3build} by setting appropriately the variables \texttt{checkdeps}, \texttt{typesetdeps}, and \texttt{unpackdeps}.
767 % The relevant parts of the \LaTeX{} repository is structured as the following.
768 % \Needspace{3\baselineskip}
769 % \begin{Verbatim}
770 % l3/
771 % l3kernel/
772 % build.lua
773 % expl3.dtx
774 % expl3.ins
775 % ...
776 % testfiles/
777 % l3packages/
778 % build.lua
779 % xparse/
780 % build.lua
781 % testfiles/
782 % xparse.dtx
783 % xparse.ins
784 % support/
785 % \end{Verbatim}
786 % For \LaTeX{} build files, |maindir| is defined as top level folder |l3|, so all support files are located here, and the build directories will be created there.
787 % To set \pkg{l3kernel} as a dependency of \pkg{l3package}, within |l3packages/xparse/build.lua| the equivalent of the following is set:
788 % \begin{Verbatim}
789 % maindir = "../.."
790 % checkdeps = {maindir .. "/l3kernel"}
791 % \end{Verbatim}
792 % This ensures that the \pkg{l3kernel} code is included in all processes involved in unpacking and checking and so on.
793 % The name of the script file in the dependency is set with the |scriptname| variable; by default these are |"build.lua"|.
794 %
795 % \subsection{Non-standard source layouts}
796 %
797 % A variety of source layouts are supported. In general, a \enquote{flat}
798 % layout with all source files \enquote{here} is most convenient. However,
799 % \pkg{l3build} supports placement of both code and documentation source
800 % files in other locations using the \var{sourcefiledir}, \var{docfiledir}
801 % and \var{textfiledir}
802 % variables. For pre-built trees, the glob syntax \texttt{**/*.\meta{ext}} may
803 % be useful in these cases: this enables recursive searching in the appropriate
804 % tree locations. With the standard settings, this structure will be removed
805 % when creating a CTAN release: the variable \var{flatten} may be
806 % used to control this behavior. The \var{flattentds} setting controls
807 % the same concept for TDS creation.
808 %
809 % Notice that text files are treated separately from documentation files when
810 % splitting trees: this is to allow for the common case where files such
811 % as |README| and |LICENSE| are at the top level even when other documentation
812 % files are in a sub-directory.
813 %
814 % A series of example layouts and matching |build.lua| files are available from
815 % \url{https://github.com/latex3/l3build/tree/main/examples}.
816 %
817 % For more complex layouts in which sources are laid out in TDS format and
818 % should be used directly, the table \var{tdsdirs} is available. Each entry
819 % is a source directory and the matching installation target, for example
820 % \begin{Verbatim}
821 % tdsdirs = {sources = "tex"}
822 % \end{Verbatim}
823 % This would enable a directory \texttt{sources} in the development area to
824 % be used for testing and typesetting, and for it to be installed into the
825 % \texttt{tex} tree when building a release. When this method is used, the
826 % sources are \emph{not} copied into the local tree: like \var{texmfdir},
827 % they are added directly to the areas accessible during a testing or
828 % typesetting run. When using this approach, the files listed in
829 % \var{typesetfiles} \emph{must} still be included in \var{docfiles}:
830 % they have to be directly visible to \pkg{l3build}, not found by
831 % \texttt{kpsewhich} searching.
832 %
833 % \subsection{Non-standard formats/binaries}
834 %
835 % The standard approach used by \pkg{l3build} is to use a combination
836 % of \var{engine} and \var{checkformat} to generate the \emph{binary} and
837 % \emph{format} combination used for tests. For example, when |pdftex| is
838 % the \var{engine} and |latex| is the \var{checkformat}, the system call
839 % used is
840 % \begin{verbatim}
841 % pdftex --fmt=pdflatex
842 % \end{verbatim}
843 % \emph{i.e.}~the binary names is the same as the \var{engine}, and the format
844 % is a simple substitution of the \var{checkformat} into \var{engine}, replacing
845 % |tex|.
846 %
847 % For more complex set ups, \var{specialformats} should be used. This is a
848 % table with one entry per \var{checkformat}. Each entry is itself a table,
849 % and these contain a list of engines and settings for |binary|, |format|
850 % and |options|. For example, the set up for Con\TeX{}t in \pkg{l3build} 2023-07-17 is
851 % \begin{verbatim}
852 % specialformats.context = {
853 % luametatex = {binary = "context", format = ""},
854 % luatex = {binary = "context", format = "", options = "--luatex"},
855 % pdftex = {binary = "texexec", format = ""},
856 % xetex = {binary = "texexec", format = "", options = "--xetex"}
857 % }
858 % \end{verbatim}
859 % Additional tokens can also be injected before the loading of a test file using
860 % the |tokens| entry: this might for example be used to select a graphics driver
861 % with a DVI-based route.
862 %
863 % \subsection{Output normalization}
864 % \label{sec:norm}
865 %
866 % To allow test files to be used between different systems (\emph{e.g.}~when
867 % multiple developers are involved in a project), the log files are normalized
868 % before comparison during checking. This removes some system-dependent
869 % data but also some variations due to different engines. This normalization
870 % consists of two parts: removing (\enquote{ignoring}) some lines and modifying
871 % others to give consistent test. Currently, the following types of line are
872 % ignored:
873 % \begin{itemize}
874 % \item Lines before the \cs{START}, after the \cs{END} and within
875 % \cs{OMIT}/\cs{TIMO} blocks
876 % \item Entirely blank lines, including those consisting only of spaces.
877 % \item Lines related to loading |.fd| files (from \texttt{(\meta{name}.fd}
878 % to the matching \texttt{)}).
879 % \item Lines starting \cs{openin} or \cs{openout}.
880 % \end{itemize}
881 % Modifications made in lines are:
882 % \begin{itemize}
883 % \item Removal spaces at the start of lines.
884 % \item Removal of |./| at start of file names.
885 % \item Standardization of the list of units known to \TeX{} (\pdfTeX{}
886 % and \LuaTeX{} add a small number of additional units which are not
887 % known to \TeX90 or \XeTeX{}, (u)p\TeX{} adds some additional non-standard
888 % ones)
889 % \item Standardization of \verb*|\csname\endcsname | to |\csname\endcsname|
890 % (the former is formally correct, but the latter was produced for many
891 % years due to a \TeX{} bug).
892 % \item Conversion of \texttt{on line \meta{number}} to \texttt{on line ...}
893 % to allow flexibility in changes to test files.
894 % \item Conversion of \texttt{at lines \meta{number}}|--|\texttt{\meta{number}} to
895 % \texttt{at lines ...} for overfull and underfull boxes.
896 % \item Conversion of file dates to \texttt{....-..-..}, and any version
897 % numbers on the same lines to \texttt{v...}.
898 % \item Conversion of register numbers in assignment lines
899 % \texttt{\cs{\meta{register}}=\cs{\meta{type}}\meta{number}} to
900 % \texttt{\cs{\meta{type}}\meta{...}}
901 % \item Conversion of box numbers in |\show| lines
902 % \texttt{>~\cs{box}\meta{number}=} to \texttt{>~\cs{box}...=}
903 % \item Conversion of Lua data reference ids
904 % \texttt{<lua data reference \meta{number}>} to
905 % \texttt{<lua data reference ...>}
906 % \item Removal of some (u)p\TeX{} data where it is equivalent to
907 % \pdfTeX{} (|yoko direction|, |\displace 0.0|)
908 % \item Removal of various |\special| lines inserted due to the build
909 % process
910 % \end{itemize}
911 %
912 % \LuaTeX{} makes several additional changes to the log file. As normalizing
913 % these may not be desirable in all cases, they are handled separately.
914 % When creating \LuaTeX{}-specific test files (either with \LuaTeX{} as
915 % the standard engine or saving a \LuaTeX{}-specific |.tlg| file) no further
916 % normalization is undertaken. On the other hand, for cross-engine comparison
917 % the following normalization is applied:
918 % \begin{itemize}
919 % \item Removal of additional (unused) |\discretionary| points.
920 % \item normalization of some |\discretionary| data to a \TeX{}90 form.
921 % \item Removal of |U+...| notation for missing characters.
922 % \item Removal of |display| for display math boxes
923 % (included by \TeX90/\pdfTeX{}/\XeTeX).
924 % \item Removal of Omega-like |direction TLT| information.
925 % \item Removal of additional whatsit containing local paragraph information
926 % (|\localinterlinepenalty|, \emph{etc.}).
927 % \item Rounding of glue set to four decimal places (glue set may be
928 % slightly different in \LuaTeX{} compared to other engines).
929 % \item Conversion of low chars ($0$ to $31$) to |^^| notation.
930 % \end{itemize}
931 % This involves making an additional \texttt{.tlg} file in the \var{testdir}
932 % location, which is generated dynamically during the testing process.
933 %
934 % When making comparisons between 8-bit and Unicode engines it is useful to
935 % format the top half of the 8-bit range such that it appears in the log as
936 % |^^|\texttt{\meta{char}} (the exact nature of the 8-bit output is otherwise
937 % dependent on the active code page). This may be controlled using the
938 % |asciiengines| option. Any engines named here will use a |.tcx| file to
939 % produce only ASCII chars in the log output, whilst for other engines
940 % normalization is carried out from UTF-8 to ASCII. If the option is set to
941 % an empty table the latter process is skipped: suitable for cases where only
942 % Unicode engines are in use.
943 %
944 % \subsection{Breaking changes}
945 %
946 % Very occasionally, it is necessary to make changes to \pkg{l3build} that
947 % change the \texttt{.tlg} file results. This is typically when additional
948 % normalization is required. When this is the case, you should first verify
949 % that \texttt{.tlg} files pass with the older \pkg{l3build}, then update only
950 % \pkg{l3build}, re-check the files and save the results. Where possible,
951 % we provide a mechanism to run with older setting to allow this process to
952 % take place smoothly.
953 %
954 % \subsubsection{Release 2024-02-08}
955 %
956 % Wrapping of messages by \pkg{l3msg} is now suppressed, aligning with the
957 % approach to \var{maxprintline}.
958 %
959 % \subsubsection{Release 2023-03-22}
960 %
961 % This release changes the standard value of \var{maxprintline} from $79$ to
962 % $9999$, to suppress line wrapping in the log. This makes normalization of
963 % for example file paths more reliable. To check that \texttt{.tlg} files
964 % are correct, you can set \var{maxprintline} in your \texttt{build.lua} file
965 % explicitly to the old default, check that tests pass, then remove this
966 % line and re-check.
967 %
968 % \section{Writing test files}
969 % \label{sec:writing-tests}
970 %
971 % Test files are written in a \TeX{} dialect using the support file |regression-test.tex|, which should be |\input| at the very beginning of each test.
972 % Additional customizations to this driver can be included in a local |regression-test.cfg| file, which will be loaded automatically if found.
973 %
974 % The macros loaded by |regression-test.tex| set up the test system and provide a number of commands to aid the production of a structured test suite.
975 % The basis of the test suite is to output material into the |.log| file, from which a normalized test output (|.tlg|) file is produced by the build command |save|.
976 % A number of commands are provided for this; they are all written in uppercase to help avoid possible conflicts with other package commands.
977 %
978 % \subsection{Metadata and structural commands}
979 %
980 % Any commands that write content to the |.log| file that should be ignored can be surrounded by |\OMIT| \dots\ |\TIMO|.
981 % At the appropriate location in the document where the |.log| comparisons should start (say, after |\begin{document}|), the test suite must contain the |\START| macro.
982 %
983 % The |\END| command signals the end of the test (but read on).
984 % Some additional diagnostic information is printed at this time to debug if the test did not complete `properly' in terms of mismatched brace groups or \cs{if}\dots\cs{fi} groups.
985 %
986 % In a \LaTeX{} document, |\end{document}| will implicitly call |\END| at the very end of the compilation process.
987 % If |\END| is used directly (replacing |\end{document}| in the test), the compilation will halt almost immediately, and various tasks that |\end{document}| usually performs will not occur (such as potentially writing to the various |.toc| files, and so on). This can be an advantage if there is additional material printed to the log file in this stage that you wish to ignore, but it is a disadvantage if the test relies on various auxiliary data for a subsequent typesetting run.
988 % (See the \var{checkruns} variable for how these tests would be test up.)
989 %
990 % \subsection{Commands to help write tests}
991 %
992 % \cs{TYPE} is used to write material to the \texttt{.log} file, like \LaTeX's \cs{typeout}, but it allows `long' input.
993 % The following commands are defined to use \cs{TYPE} to output strings to the \texttt{.log} file.
994 % \begin{itemize}
995 % \item
996 % \cs{SEPARATOR} inserts a long line of \texttt{=} symbols to break up the log output.
997 % \item
998 % \cs{NEWLINE} inserts a linebreak into the log file.
999 % \item
1000 % \cs{TRUE}, \cs{FALSE}, \cs{YES}, \cs{NO} output those strings to the log file.
1001 % \item
1002 % \cs{ERROR} is \emph{not} defined but is commonly used to indicate a code path that should never be reached.
1003 % \item
1004 % The \cs{TEST}\marg{title}\marg{contents} command runs its \meta{contents}
1005 % in a group and surrounds the generated log lines with some \cs{SEPARATOR}s
1006 % and a \meta{title}.
1007 % \item
1008 % \cs{TESTEXP}\marg{title}\marg{contents} surrounds its \meta{contents} with
1009 % \cs{TYPE} and formatting to match \cs{TEST}; this can be used as a shorthand
1010 % to test expandable commands.
1011 % \item
1012 % \cs{BEGINTEST}\marg{title} \dots \cs{ENDTEST} is an environment form of
1013 % \cs{TEST}, allowing verbatim material, \emph{etc.} to appear.
1014 % \item
1015 % \cs{SHOWFILE}\marg{filename} (\eTeX{} only) shows the content of
1016 % \meta{filename}.
1017 % \item
1018 % \cs{ASSERT}\marg{arg_1}\marg{arg_2} and \cs{ASSERTSTR}\marg{arg_1}\marg{arg_2}
1019 % Test if the full expansion of \meta{arg_1} and \meta{arg_2} are the same:
1020 % on a token basis in \cs{ASSERT} and on a string basis in \cs{ASSERTSTR}.
1021 % Depending on the outcome, record either \texttt{PASSED} or \texttt{FAILED}
1022 % in the \texttt{.log}.
1023 % \item
1024 % \cs{SHOWPDFTAGS} generates a test block in the log file containing
1025 % the XML generated by applying \texttt{show-pdf-tags --xml} to PDF output
1026 % of the current test file. This allows any changes in the tagged PDF structure
1027 % to be detected. The \pkg{show-pdf-tags} package is required.
1028 % \end{itemize}
1029 % An example of some of these commands is shown following.
1030 % \begin{Verbatim}
1031 % \TEST{bool_set,~lazy~evaluation}
1032 % {
1033 % \bool_set:Nn \l_tmpa_bool
1034 % {
1035 % \int_compare_p:nNn 1=1
1036 % && \bool_lazy_any_p:n
1037 % {
1038 % { \int_compare_p:nNn 2=3 }
1039 % { \int_compare_p:nNn 4=4 }
1040 % { \int_compare_p:nNn 1=\ERROR } % is skipped
1041 % }
1042 % && \int_compare_p:nNn 2=2
1043 % }
1044 % \bool_if:NTF \l_tmpa_bool \TRUE \FALSE
1045 % }
1046 % \end{Verbatim}
1047 % This test will produce the following in the output.
1048 % \begin{Verbatim}
1049 % ==========================================
1050 % TEST 8: bool_set, lazy evaluation
1051 % ==========================================
1052 % TRUE
1053 % ==========================================
1054 % \end{Verbatim}
1055 % (Only if it's the eighth test in the file of course, and assuming \pkg{expl3}
1056 % coding conventions are active.)
1057 %
1058 % \subsection{Showing box content}
1059 %
1060 % The commands introduced above are only useful for checking algorithmic or logical correctness.
1061 % Many packages should be tested based on their typeset output instead; \TeX{} provides a mechanism for this by printing the contents of a box to the log file.
1062 % The |regression-test.tex| driver file sets up the relevant \TeX{} parameters to produce as much output as possible when showing box output.
1063 %
1064 % A plain \TeX{} example of showing box content follows.
1065 % \begin{Verbatim}[frame=single,fontsize=\small]
1066 % \input regression-test.tex\relax
1067 % \START
1068 % \setbox0=\hbox{\rm hello \it world $a=b+c$}
1069 % \showbox0
1070 % \END
1071 % \end{Verbatim}
1072 % This produces the output shown in Figure~\vref{fig:box-log} (left side).
1073 % It is clear that if the definitions used to typeset the material in the box changes, the log output will differ and the test will no longer pass.
1074 %
1075 % The equivalent test in \LaTeXe{} using \pkg{expl3} is similar.
1076 % \begin{Verbatim}[frame=single,fontsize=\small]
1077 % \input{regression-test.tex}
1078 % \documentclass{article}
1079 % \START
1080 % \ExplSyntaxOn
1081 % \box_new:N \l_tmp_box
1082 % \hbox_set:Nn \l_tmp_box {hello~ \emph{world}~ $a=b+c$}
1083 % \box_show:N \l_tmp_box
1084 % \ExplSyntaxOff
1085 % \END
1086 % \end{Verbatim}
1087 % The output from this test is shown in Figure~\vref{fig:box-log} (right side).
1088 % There is marginal difference (mostly related to font selection and different logging settings in \LaTeX) between the plain and \pkg{expl3} versions.
1089 %
1090 % When examples are not self-contained enough to be typeset into boxes, it is possible to ask \TeX{} to output the entire contents of a page.
1091 % Insert \cs{showoutput} for \LaTeX{} or set \cs{tracingoutput} positive for plain \TeX{}; ensure that the test ends with \cs{newpage} or equivalent because \TeX{} waits until the entire page is finished before outputting it.
1092 %
1093 % TODO: should we add something like \cs{TRACEPAGES} to be format-agnostic here? Should this perhaps even be active by default?
1094 %
1095 % \begin{figure}
1096 % \hspace*{-3cm}
1097 % \begin{BVerbatim}[fontsize=\small]
1098 % > \box0=
1099 % \hbox(6.94444+0.83333)x90.56589
1100 % .\tenrm h
1101 % .\tenrm e
1102 % .\tenrm l
1103 % .\tenrm l
1104 % .\tenrm o
1105 % .\glue 3.33333 plus 1.66666 minus 1.11111
1106 % .\tenit w
1107 % .\tenit o
1108 % .\tenit r
1109 % .\tenit l
1110 % .\tenit d
1111 %
1112 % .\glue 3.57774 plus 1.53333 minus 1.0222
1113 % .\mathon
1114 % .\teni a
1115 % .\glue(\thickmuskip) 2.77771 plus 2.77771
1116 % .\tenrm =
1117 % .\glue(\thickmuskip) 2.77771 plus 2.77771
1118 % .\teni b
1119 % .\glue(\medmuskip) 2.22217 plus 1.11108 minus 2.22217
1120 % .\tenrm +
1121 % .\glue(\medmuskip) 2.22217 plus 1.11108 minus 2.22217
1122 % .\teni c
1123 % .\mathoff
1124 %
1125 % ! OK.
1126 % l.9 \showbox0
1127 %
1128 %
1129 % \end{BVerbatim}
1130 % \qquad
1131 % \begin{BVerbatim}[fontsize=\small]
1132 % > \box71=
1133 % \hbox(6.94444+0.83333)x91.35481
1134 % .\OT1/cmr/m/n/10 h
1135 % .\OT1/cmr/m/n/10 e
1136 % .\OT1/cmr/m/n/10 l
1137 % .\OT1/cmr/m/n/10 l
1138 % .\OT1/cmr/m/n/10 o
1139 % .\glue 3.33333 plus 1.66666 minus 1.11111
1140 % .\OT1/cmr/m/it/10 w
1141 % .\OT1/cmr/m/it/10 o
1142 % .\OT1/cmr/m/it/10 r
1143 % .\OT1/cmr/m/it/10 l
1144 % .\OT1/cmr/m/it/10 d
1145 % .\kern 1.03334
1146 % .\glue 3.33333 plus 1.66666 minus 1.11111
1147 % .\mathon
1148 % .\OML/cmm/m/it/10 a
1149 % .\glue(\thickmuskip) 2.77771 plus 2.77771
1150 % .\OT1/cmr/m/n/10 =
1151 % .\glue(\thickmuskip) 2.77771 plus 2.77771
1152 % .\OML/cmm/m/it/10 b
1153 % .\glue(\medmuskip) 2.22217 plus 1.11108 minus 2.22217
1154 % .\OT1/cmr/m/n/10 +
1155 % .\glue(\medmuskip) 2.22217 plus 1.11108 minus 2.22217
1156 % .\OML/cmm/m/it/10 c
1157 % .\mathoff
1158 %
1159 % ! OK.
1160 % <argument> \l_tmp_box
1161 %
1162 % l.12 \box_show:N \l_tmp_box
1163 % \end{BVerbatim}
1164 % \caption{Output from displaying the contents of a simple box to the log file, using plain \TeX{} (left) and \pkg{expl3} (right). Some blank lines have been added to the plain \TeX{} version to help with the comparison.}
1165 % \label{fig:box-log}
1166 % \end{figure}
1167 %
1168 % \subsection{Testing entire pages}
1169 %
1170 % There may be occasions where creating entire test pages is necessary
1171 % to observe the test output required. That is best achieved by applying
1172 % \cs{showoutput} and forcing a complete page to be produced, for example
1173 % \begin{Verbatim}[frame=single,fontsize=\small]
1174 % \input{regression-test.tex}
1175 % \documentclass{article}
1176 % \START
1177 % \showoutput
1178 % % Test content here
1179 % \vfil\break
1180 % \END
1181 % \end{Verbatim}
1182 %
1183 % \subsection{Pre-check hook}
1184 %
1185 % To allow complex set up for tests, a hook |checkinit_hook()| is available
1186 % to be executed once all standard set up is complete but before any tests
1187 % are run. This should return an integer value: $0$ indicates no error.
1188 %
1189 % \subsection{Additional test tasks}
1190 %
1191 % A standard test will run the file \texttt{\meta{name}.lvt} using one
1192 % or more engines, but will not carry out any additional processing. For
1193 % some tests, for example bibliography generation, it may be desirable to
1194 % call one or more tools in addition to the engine. This can be arranged
1195 % by defining |runtest_tasks|, a function taking two arguments, the name
1196 % of the current test (this is equivalent to \TeX{}'s \cs{jobname},
1197 % \emph{i.e.}~it lacks an extension) and the current run number.
1198 % The function |runtest_tasks| is run after the main call to the
1199 % engine for a test cycle. It should return a string consists of task(s),
1200 % i.e., the CLI command(s) to execute.
1201 % If more than one task is required, these should be separated
1202 % by use of |os_concat|, a string variable defined by \pkg{l3build} as the
1203 % correct concatenation marker for the system. An example of |runtest_tasks|
1204 % suitable for calling Biber is shown in Listing~\vref{lst:test-tasks}.
1205 % \begin{floating-listing}[caption={Example \texttt{runtest_tasks} function.},label={lst:test-tasks}]
1206 % function runtest_tasks(name,run)
1207 % if run == 1 then
1208 % return "biber " .. name
1209 % else
1210 % return ""
1211 % end
1212 % end
1213 % \end{floating-listing}
1214 %
1215 % \subsection{Instructions for rebuilding test output}
1216 %
1217 % Sometimes changes to fundamental parts of the code can cause a lot of tests
1218 % to fail even though the actually tested systems are still working correctly.
1219 % This is especially common when the logging and error reporting systems
1220 % changes and therefore all log file based tests using the component fail with
1221 % these changes.
1222 %
1223 % In these cases, the option |--show-saves| can be passed to
1224 % |l3build check| in order to generate a list of |l3build save| commands which
1225 % can be executed to regenerate the expected output of all tests which fail.
1226 % Additionally it sometimes prints a list of |l3build check| commands for tests
1227 % which might still fail due to engine differences after running the |save|
1228 % commands. After running all these |l3build check| commands and all
1229 % |l3build save| commands listed by them, all tests will succeed.
1230 %
1231 % When bundles are used |l3build check --show-saves| has to be executed
1232 % separately for every module in the bundle.
1233 %
1234 % This option is potentially dangerous and therefore should only be used with
1235 % care. It can easily hide valid test failures between a bunch of spurious
1236 % changes. Therefore you should always take a close look at the difference
1237 % files generated by |l3build check| before running the generated
1238 % |l3build save| commands. Additionally it should only be used when you are
1239 % aware of the reason why a large number of tests failed and the change
1240 % causing the failures has been tested separately to have no unintended
1241 % side effects.
1242 %
1243 % \subsection{Epoch setting}
1244 %
1245 % To produce predictable output when using dates, the test system offers the
1246 % ability to set the epoch to a known value. The \var{epoch} variable may
1247 % be given as a raw value (a simple integer) or as a date in ISO format
1248 % (YYYY-MM-DD).
1249 % The two flags \var{forcecheckepoch} and \var{forcedocepoch} then
1250 % determine whether this is applied in testing and typesetting, respectively.
1251 %
1252 % The epoch may also be given as a command line option, |-E|, which again
1253 % takes either a date or raw epoch. When given, this will automatically
1254 % activate forcing of the epoch in both testing and typesetting.
1255 %
1256 % \subsection{Settings in \texttt{texmf.cnf}}
1257 %
1258 % To allow application of non-standard \TeX{} trees or similar non-standard
1259 % settings, \pkg{l3build} sets the environment variable \texttt{TEXMFCNF}
1260 % to allow reading of any \texttt{texmf.cnf} file present in the support folder.
1261 % This might for example be used with a file containing
1262 % \begin{verbatim}
1263 % TEXMFAUXTREES = ../../texmf,
1264 % \end{verbatim}
1265 % for adding a local tree within the development repository (assuming the
1266 % typical \pkg{l3build} layout).
1267 %
1268 % \section{Alternative test formats}
1269 %
1270 % \subsection{Generating test files with \pkg{DocStrip}}
1271 %
1272 % It is possible to pack tests inside source files. Tests generated during the
1273 % unpacking process will be available to the \texttt{check} and \texttt{save}
1274 % commands as if they were stored in the \texttt{testfiledir}. Any explicit
1275 % test files inside \texttt{testfiledir} take priority over generated ones
1276 % with the same names.
1277 %
1278 % \subsection{Specifying expectations}
1279 %
1280 % Regression tests check whether changes introduced in the code modify the test
1281 % output. Especially while developing a complex package there is not yet a
1282 % baseline to save a test goal with. It might then be easier to formulate the
1283 % expected effects and outputs of tests directly. To achieve this, you may
1284 % create an \texttt{.lve} instead of a \texttt{.tlg}
1285 % file.\footnote{Mnemonic: \texttt{lv\textbf{t}}: \textbf{t}est,
1286 % \texttt{lv\textbf{e}}: \textbf{e}xpectation} It is processed exactly like
1287 % the \texttt{.lvt} to generate the expected outcome. The test fails when both
1288 % differ.
1289 %
1290 % Combining both features enables contrasting the test with its expected
1291 % outcome in a compact format. Listing~\vref{lst:expect-dtx} exemplary tests
1292 % \TeX{}s counters. Listing~\vref{lst:expect-ins} shows the relevant part of an
1293 % \texttt{.ins} file to generate it.
1294 %
1295 % \begin{floating-listing}[language={TeX},caption={Test and expectation can be specified side-by-side in a single \texttt{.dtx} file.},label={lst:expect-dtx}]
1296 % \input regression-test.tex\relax
1297 % \START
1298 % \TEST{counter-math}{
1299 % %<*test>
1300 % \OMIT
1301 % \newcounter{numbers}
1302 % \setcounter{numbers}{2}
1303 % \addtocounter{numbers}{2}
1304 % \stepcounter{numbers}
1305 % \TIMO
1306 % \typeout{\arabic{numbers}}
1307 % %</test>
1308 % %<expect> \typeout{5}
1309 % }
1310 % \END
1311 % \end{floating-listing}
1312 %
1313 % \begin{floating-listing}[language={TeX},caption={Test and expectation are generated from a \texttt{.dtx} file of the same name.},label={lst:expect-ins}]
1314 % \generate{\file{\jobname.lvt}{\from{\jobname.dtx}{test}}
1315 % \file{\jobname.lve}{\from{\jobname.dtx}{expect}}}
1316 % \end{floating-listing}
1317 %
1318 % \subsection{PDF-based tests}
1319 %
1320 % In most cases, testing is best handled by using the text-based methods
1321 % outlined above. However, there are cases where the detail of output structure
1322 % is important. This can only be fully tested by comparing PDF structure.
1323 % To support this, \pkg{l3build} can be instructed to build and compare
1324 % PDF files by setting up tests in \texttt{.pvt} files. The following
1325 % normalization takes place:
1326 % \begin{itemize}
1327 % \item Replacement of binary streams by the marker |[BINARY STREAM]|
1328 % \item Replacement of \texttt{/ID} values by |ID-STRING|
1329 % \item Removal of blank lines
1330 % \item Removal of comment (|%%|) lines
1331 % \end{itemize}
1332 %
1333 % After this normalization takes place, the file can not usually be rendered
1334 % properly. To check if the build system has produced a correct PDF, the
1335 % pre-normalization PDF can be found in the \texttt{build} folder.
1336 %
1337 % To allow platform-independence, PDF-based tests must use only Type~1 or
1338 % OpenType fonts: Type3 fonts are system-dependent. PDF files are
1339 % engine-specific, thus one |.tpf| file should be stored per engine to be
1340 % tested.
1341 %
1342 % \subsection{Custom tests}
1343 %
1344 % If neither the text-based methods nor PDF-based tests are sufficient,
1345 % there is the additional option of defining custom variants with individual
1346 % normalization rules.
1347 %
1348 % For this, the variant has to be registered in the \texttt{test_types} table
1349 % and then activated in \texttt{test_order}.
1350 %
1351 % Every element in \texttt{test_types} is a table with fields \texttt{test}
1352 % (the extension of the test file), \texttt{reference} (the extension of the
1353 % file the output is compared with), \texttt{generated} (extension of the
1354 % analyzed \LaTeX{} output file) and \texttt{rewrite} (A Lua function for
1355 % normalizing the output file, taking as parameters the name of the unnormalized
1356 % \LaTeX{} output file to be read, the name of the normalized file to be written,
1357 % the engine name and a potential errorcode).
1358 %
1359 % For example:
1360 % \begin{verbatim}
1361 % test_types = {
1362 % mytest = {
1363 % test = ".mylvt",
1364 % reference = ".mytlg",
1365 % generated = ".log",
1366 % rewrite = function(source, normalized, engine, errorcode)
1367 % -- In this example we just rename the logfile without any normalization
1368 % ren(testdir,source,normalized)
1369 % end,
1370 % },
1371 % }
1372 % test_order = {"mylvt", "log", "pdf"}
1373 % \end{verbatim}
1374 %
1375 % \section{Release-focussed features}
1376 %
1377 % \subsection{Installation structure}
1378 %
1379 % With the standard settings, \pkg{l3build} will install files within
1380 % the \TeX{} directory structure (TDS) as follows
1381 % \begin{itemize}
1382 % \item \var{installfiles} within a \texttt{\meta{bundle}/\meta{module}}
1383 % (or \texttt{\meta{module}}) directory inside \texttt{tex/\meta{format}}
1384 % \item \var{sourcefiles} within a \texttt{\meta{bundle}/\meta{module}}
1385 % (or \texttt{\meta{module}}) directory inside \texttt{source/\meta{format}}
1386 % \item Typeset PDFs within a \texttt{\meta{bundle}/\meta{module}}
1387 % (or \texttt{\meta{module}}) directory inside \texttt{doc/\meta{format}}
1388 % \item \var{bstfiles} within a \texttt{\meta{bundle}/\meta{module}}
1389 % (or \texttt{\meta{module}}) directory inside \texttt{bibtex/bst}
1390 % \item \var{bibfiles} within a \texttt{\meta{bundle}/\meta{module}}
1391 % (or \texttt{\meta{module}}) directory inside \texttt{bibtex/bib}
1392 % \item \var{makeindexfiles} within a \texttt{\meta{bundle}/\meta{module}}
1393 % (or \texttt{\meta{module}}) directory inside \texttt{makeindex}
1394 % \end{itemize}
1395 %
1396 % For more complex set ups, this can be customized using the
1397 % \var{tdslocations} table. Each entry there should be a glob specifying the
1398 % TDS position of a file or files. Any files not specified in the table
1399 % will use the standard locations above. For example, to place some files
1400 % in the generic tree, some in the plain \TeX{} tree and some in the \LaTeX{}
1401 % tree, one might use the set up shown in Listing~\vref{lst:tds}.
1402 % \begin{floating-listing}[caption={Example \texttt{tdslocations} table.},label={lst:tds}]
1403 % tdslocations =
1404 % {
1405 % "tex/generic/mypkg/*.generic.tex" ,
1406 % "tex/plain/mypkg/*.plain.tex" ,
1407 % "tex/latex/mypkg/*.latex.tex"
1408 % }
1409 % \end{floating-listing}
1410 %
1411 % The table is read in order, and thus specific file names should come before
1412 % potential wild-card matches.
1413 %
1414 % \subsection{Automatic tagging}
1415 % \label{sec:tagging}
1416 %
1417 % The |tag| target can automatically edit
1418 % source files to modify date and release tag name. As standard, no automatic
1419 % replacement takes place, but setting up a |update_tag()| function
1420 % will allow this to happen. This function takes four input arguments:
1421 % \begin{enumerate}[nosep]
1422 % \item file name
1423 % \item full content of the file
1424 % \item tag name
1425 % \item tag date
1426 % \end{enumerate}
1427 % The |update_tag()| function should return the (modified) contents
1428 % for writing to disk.
1429 % For example, the function used by |l3build| itself is
1430 % shown in Listing~\vref{lst:update-tag}.
1431 %
1432 % \begin{floating-listing}[caption={Example \texttt{update_tag} function.},label={lst:update-tag}]
1433 % -- Detail how to set the version automatically
1434 % function update_tag(file,content,tagname,tagdate)
1435 % if string.match(file, "%.dtx$") then
1436 % return string.gsub(content,
1437 % "\n%% \\date{Released %d%d%d%d/%d%d/%d%d}\n",
1438 % "\n%% \\date{Released " .. tagname .. "}\n")
1439 % elseif string.match(file, "%.md$") then
1440 % return string.gsub(content,
1441 % "\nRelease %d%d%d%d/%d%d/%d%d\n",
1442 % "\nRelease " .. tagname .. "\n")
1443 % elseif string.match(file, "%.lua$") then
1444 % return string.gsub(content,
1445 % '\nrelease_date = "%d%d%d%d/%d%d/%d%d"\n',
1446 % '\nrelease_date = "' .. tagname .. '"\n')
1447 % end
1448 % return content
1449 % end
1450 % \end{floating-listing}
1451 %
1452 % To allow more complex tasks to take place, a hook |tag_hook()| is also
1453 % available. It will receive the tag name and date as arguments, and
1454 % may be used to carry out arbitrary tasks after all files have been updated.
1455 % For example, this can be used to set a version control tag for an entire repository.
1456 %
1457 %
1458 % \subsection{Typesetting documentation}
1459 %
1460 % As part of the overall build process, \pkg{l3build} will create PDF
1461 % documentation as described earlier. The standard build process for PDFs
1462 % will attempt to run Biber, \BibTeX{} and MakeIndex as appropriate
1463 % (the exact binaries used are defined by \var{biberexe}, \var{bibtexexe}
1464 % and \var{makeindexexe}). However, there is no attempt to create an entire
1465 % PDF creation system in the style of \texttt{latexmk} or similar.
1466 %
1467 % For package authors who have more complex requirements than those covered
1468 % by the standard set up, the Lua script offers the possibility for
1469 % customization. The Lua function \texttt{typeset} may be defined before
1470 % reading \texttt{l3build.lua} and should take one argument, the name of
1471 % the file to be typeset. Within this function, the auxiliary Lua
1472 % functions \texttt{biber}, \texttt{bibtex}, \texttt{makeindex} and
1473 % \texttt{tex} can be used, along with custom code, to define a PDF
1474 % typesetting pathway. The functions \texttt{biber} and \texttt{bibtex}
1475 % take a single argument: the name of the file to work with \emph{minus}
1476 % any extension. The \texttt{tex} takes as an argument the full name
1477 % of the file. The most complex function \texttt{makeindex} requires the
1478 % name, input extension, output extension, log extension and style name.
1479 % For example, Listing~\vref{lst:PDF} shows a simple script which might
1480 % apply to a case where multiple \BibTeX{} runs are needed (perhaps where
1481 % citations can appear within other references).
1482 %
1483 % Where there are complex requirements for pre-compiled demonstration
1484 % files, the hook |typeset_demo_tasks()| is available: it runs after
1485 % copying files to the typesetting location but before the main typesetting
1486 % run. This may be used for example to script a very large number of
1487 % demonstrations using a single source (see the \pkg{beamer} package
1488 % for an example of this). Note that this hook is intended for use files
1489 % \emph{not} listed in \var{typesetfiles} or \var{typesetdemofiles}.
1490 %
1491 % \begin{floating-listing}[caption={A customized PDF creation script.},label={lst:PDF}]
1492 % #!/usr/bin/env texlua
1493 %
1494 % -- Build script with custom PDF route
1495 %
1496 % module = "mymodule"
1497 %
1498 % function typeset(file)
1499 % local name = jobname(file)
1500 % local errorlevel = tex (file)
1501 % if errorlevel == 0 then
1502 % -- Return a non-zero errorlevel if anything goes wrong
1503 % errorlevel =(
1504 % bibtex(name) +
1505 % tex(file) +
1506 % bibtex(name) +
1507 % tex(file) +
1508 % tex(file)
1509 % )
1510 % end
1511 % return errorlevel
1512 % end
1513 % \end{floating-listing}
1514 %
1515 % \subsection{Pre-typesetting hook}
1516 %
1517 % To allow complex set up for typesetting, a hook |docinit_hook()| is available
1518 % to be executed once all standard set up is complete but before any typesetting
1519 % is run.
1520 %
1521 % \subsection{Non-standard typesetting}
1522 %
1523 % To allow non-standard typesetting combinations, for example per-file
1524 % choice of engines, the table \var{specialtypesetting} may be used.
1525 % This is a table with one entry per file. Each entry is itself a table,
1526 % and these contain a list of engines and settings for |cmd| and |func|.
1527 % For example, to choose to use \LuaTeX{} for one file when \var{typesetexe}
1528 % is |pdftex|
1529 % \begin{verbatim}
1530 % specialtypesetting = specialtypesetting or {}
1531 % specialtypesetting["foo.tex"] = {cmd = "luatex -interaction=nonstopmode"}
1532 % \end{verbatim}
1533 % or to select an entirely different typesetting function
1534 % \begin{verbatim}
1535 % specialtypesetting = specialtypesetting or {}
1536 % specialtypesetting["foo.tex"] = {func = typeset_foo}
1537 % \end{verbatim}
1538 %
1539 % \subsection{Automated upload to CTAN}
1540 % \label{sec:upload}
1541 %
1542 % The CTAN upload process is backed by an API, which \pkg{l3build} can use
1543 % to send zip files for release. Along with the file, a variety of metadata
1544 % must be specified about the package, including the version, license, and so on, explained at \url{https://www.ctan.org/upload}.
1545 % A description of this metadata is outlined in Table~\vref{tab:upload-setup},
1546 % and a simple example of an extract from a \texttt{build.lua} file using this is shown
1547 % in Listing~\vref{lst:uploadconfig}.
1548 %
1549 % Note that the \texttt{upload} target will \emph{not} execute the
1550 % \texttt{ctan} target first.
1551 %
1552 % This upload facility assumes availability of |curl| on your
1553 % system. In the case of Windows, the system curl will not be
1554 % available if you are using a 32 bit \TeX\ implementation. Curl
1555 % executables are available for a variety of operating systems from
1556 % \url{https://curl.haxx.se/download.html}.
1557 %
1558 % \paragraph{Announcement text}
1559 % It can be convenient not to include the announcement text within the |build.lua| file
1560 % directly. The command line argument |--message| (|-m|) allows the announcement to be
1561 % included as part of the |l3build| arguments, and |--file| (|-F|) reads the announcement
1562 % from a specified file. The \texttt{build.lua} file may also specify that this text is to
1563 % be taken from the file specified by
1564 % |uploadconfig.announcement_file|, this allows the release-specific announcement to be
1565 % specified outside the main |build.lua| file. If
1566 % |uploadconfig.announcement_file| is |nil| or specifies a file that
1567 % can not be read, and no announcement is provided by the
1568 % |announcement| field or commandline arguments, |l3build| will
1569 % interactively prompt for text (which may be empty).
1570 %
1571 % Note that if the announcement text is empty a `silent update'
1572 % is performed; this should usually be performed for minor bug or documentation fixes only.
1573 %
1574 % \paragraph{Note text}
1575 % This optional field is for passing notes to the CTAN maintainers. As
1576 % for announcements, the text may be set in |uploadconfig.note| or
1577 % perhaps more usefully, if |uploadconfig.note_file| is the filename of a
1578 % readable file the file text is used as the note.
1579 %
1580 % \paragraph{Uploader details}
1581 % The CTAN team use the uploader email address as a form of low-security sanity
1582 % check that the upload is coming from a reputable source. Therefore, it is advisable not
1583 % to store this information within a public |build.lua| file. It can be set on the command
1584 % line with the |--email| option to \texttt{l3build}; alternatively, a private
1585 % configuration file could be used to add this information at upload time.
1586 %
1587 % \paragraph{The \texttt{update} field}
1588 % In most scenarios the |update| field does not need to be explicitly set. By default
1589 % \pkg{l3build} assumes that the package being uploaded already exists on CTAN
1590 % (|update=true|). If it does not, this is caught in the validation process before
1591 % uploading and automatically corrected. If you set |update| explicitly this will be passed
1592 % directly to CTAN in all circumstances, leading to errors if you attempt to update a
1593 % non-existing package or if you attempt to upload a new package with the same name as a
1594 % pre-existing one.
1595 %
1596 % \paragraph{The \texttt{curl} options file}
1597 %
1598 % The \pkg{l3build} upload options are passed to |curl| by writing the
1599 % fields to a text file with a default name being
1600 % \meta{package}|-ctan.curlopt|. This is then passed to curl using its
1601 % |--config| commandline option. (Using an intermediate file helps
1602 % keep \pkg{l3build} portable between systems using different
1603 % commandline quoting conventions. Any backslashes are doubled when writing
1604 % to this file, so they do not need to be doubled in announcement and note texts.)
1605 %
1606 % By default the file is written into the current directory alongside
1607 % the zip file to be uploaded. You may wish to specify that this file
1608 % is ignored by any version control in that directory (using
1609 % |.gitignore| or similar). Or alternatively you can use the
1610 % |uploadconfig.curlopt_file| field in the |build.lua| file to specify an
1611 % alternative name or location for this file.
1612 %
1613 % \paragraph{Validating}
1614 % To validate your upload but not actually submit to CTAN, you may use
1615 % the |--dry-run| command-line option.
1616 %
1617 % \paragraph{Debugging}
1618 % If you have have difficulty with the upload process, add the option |--debug| to divert
1619 % the request from CTAN to a service that redirects the input back
1620 % again so it can be examined.
1621 % It can also be useful to check the contents of the |curlopts| file which has a
1622 % record of the options passed to curl.
1623 %
1624 % \begin{table}[p]
1625 % \def\YES{\textbullet}
1626 % \caption{Fields used in the \texttt{uploadconfig} setup table. The
1627 % first section of fields are \emph{required} and if they are
1628 % omitted the user will be interactively prompted for further
1629 % input. Most commands take string input, but those that are
1630 % indicated with `Multi' accept more than one entry using an array
1631 % of strings. Most of the fields correspond directly to the fields
1632 % in the CTAN upload API, the last group relate to file use by
1633 % \pkg{l3build}.}
1634 % \label{tab:upload-setup}
1635 % \medskip
1636 % \begin{minipage}{\linewidth}
1637 % \begin{tabular}{@{}lccp{8cm}@{}}
1638 % \toprule
1639 % Field & Req. & Multi & Description \\
1640 % \midrule
1641 % \texttt{announcement} & \YES & & Announcement text \\
1642 % \texttt{author } & \YES & & Author name (semicolon-separated for multiple) \\
1643 % \texttt{ctanPath } & \YES & & CTAN path \\
1644 % \texttt{email } & \YES & & Email address of uploader \\
1645 % \texttt{license } & \YES & \YES & Package license(s)\footnote{See \url{https://ctan.org/license}} \\
1646 % \texttt{pkg } & \YES & & Package name \\
1647 % \texttt{summary } & \YES & & One-line summary \\
1648 % \texttt{uploader } & \YES & & Name of uploader \\
1649 % \texttt{version } & \YES & & Package version \\
1650 % \midrule
1651 % \texttt{bugtracker } & & \YES & URL(s) of bug tracker \\
1652 % \texttt{description } & & & Short description/abstract \\
1653 % \texttt{development } & & \YES & URL(s) of development channels \\
1654 % \texttt{home } & & \YES & URL(s) of home page \\
1655 % \texttt{note } & & & Internal note to CTAN \\
1656 % \texttt{repository } & & & URL(s) of source repositories \\
1657 % \texttt{support } & & \YES & URL(s) of support channels \\
1658 % \texttt{topic } & & \YES & Topic(s)\footnote{See \url{https://ctan.org/topics/highscore}} \\
1659 % \texttt{update } & & & Boolean \texttt{true} for an update, \texttt{false} for a new package \\
1660 % \midrule
1661 % \texttt{announcement\_file} & & & Announcement text file \\
1662 % \texttt{note\_file} & & & Note text file \\
1663 % \texttt{curlopt\_file} & & & The filename containing the options passed to curl \\
1664 % \bottomrule
1665 % \end{tabular}
1666 % \end{minipage}
1667 % \end{table}
1668 %
1669 %
1670 % \begin{floating-listing}[caption={Example of \texttt{uploadconfig} from the \pkg{vertbars} package.},label={lst:uploadconfig}]
1671 % uploadconfig = {
1672 % pkg = "vertbars",
1673 % version = "v1.0c",
1674 % author = "Peter R Wilson; Will Robertson",
1675 % license = "lppl1.3c",
1676 % summary = "Mark vertical rules in margin of text",
1677 % ctanPath = "/macros/latex/contrib/vertbars",
1678 % repository = "https://github.com/wspr/herries-press/",
1679 % update = true,
1680 % }
1681 % \end{floating-listing}
1682 %
1683 % \section{Lua interfaces}
1684 %
1685 % Whilst for the majority of users the simple variable-based control methods
1686 % outlined above will suffice, for more advanced applications there will be
1687 % a need to adjust behavior by using interfaces within the Lua code. This
1688 % section details the global variables and functions provided.
1689 %
1690 % \subsection{Global variables}
1691 %
1692 % \begin{variable}{options}
1693 % The |options| table holds the values passed to \pkg{l3build} at the
1694 % command line. Each possible \meta{entry} given below corresponds to
1695 % |--|\meta{entry} given at the command line, except the |target| entry
1696 % which is self explanatory and the |names| entry which corresponds to \meta{name(s)}
1697 % for |check|, |doc|, |save| and |tag| targets.
1698 % \begin{center}
1699 % \begin{tabular}{ll}
1700 % \toprule
1701 % Entry & Lua type \\
1702 % \midrule
1703 % \var{config} & |table| \\
1704 % \var{date} & |string| \\
1705 % \var{dirty} & |boolean| \\
1706 % \var{dry-run} & |boolean| \\
1707 % \var{email} & |string| \\
1708 % \var{engine} & |table| \\
1709 % \var{epoch} & |string| \\
1710 % \var{file} & |string| \\
1711 % \var{first} & |boolean| \\
1712 % \var{full} & |boolean| \\
1713 % \var{halt-on-error} & |boolean| \\
1714 % \var{help} & |boolean| \\
1715 % \var{message} & |string| \\
1716 % \var{names} & |table| \\
1717 % \var{quiet} & |boolean| \\
1718 % \var{rerun} & |boolean| \\
1719 % \var{shuffle} & |boolean| \\
1720 % \var{stdengine} & |boolean| \\
1721 % \var{target} & |string| \\
1722 % \var{texmfhome} & |string| \\
1723 % \bottomrule
1724 % \end{tabular}
1725 % \end{center}
1726 % The Lua tables mentioned here are in fact arrays of strings.
1727 % From the |build.lua| file, one can modify the string and boolean values,
1728 % add or remove entries in arrays. But it is not recommended to affect a
1729 % whole new Lua table to |options| nor to its array entries.
1730 % \end{variable}
1731 %
1732 % \subsection{Utility functions}
1733 %
1734 % The utility functions are largely focussed on file operations, though a small
1735 % number of others are provided. File paths should be given in Unix style
1736 % (using |/| as a path separator). File operations take place relative to the
1737 % path from which \pkg{l3build} is called. File operation syntax is largely
1738 % modeled on Unix command line commands but reflect the need to work on
1739 % Windows in a flexible way.
1740 %
1741 % \begin{function}{abspath()}
1742 % \begin{syntax}
1743 % |abspath(|\meta{target}|)|
1744 % \end{syntax}
1745 % Returns a string which gives the absolute location of the
1746 % \meta{target} directory.
1747 % \end{function}
1748 %
1749 % \begin{function}{dirname()}
1750 % \begin{syntax}
1751 % |dirname(|\meta{file}|)|
1752 % \end{syntax}
1753 % Returns a string comprising the path to a \meta{file} with the name removed
1754 % (\emph{i.e.}~up to the last |/|). Where the \meta{file} has no path data,
1755 % |"."| is returned.
1756 % \end{function}
1757 %
1758 % \begin{function}{basename()}
1759 % \begin{syntax}
1760 % |basename(|\meta{file}|)|
1761 % \end{syntax}
1762 % Returns a string comprising the full name of the \meta{file} with the
1763 % path removed (\emph{i.e.}~from the last |/| onward).
1764 % \end{function}
1765 %
1766 % \begin{function}{cleandir()}
1767 % \begin{syntax}
1768 % |cleandir(|\meta{dir}|)|
1769 % \end{syntax}
1770 % Removes any content within the \meta{dir}; returns an error level.
1771 % \end{function}
1772 %
1773 % \begin{function}{cp()}
1774 % \begin{syntax}
1775 % |cp(|\meta{glob}, \meta{source}, \meta{destination}|)|
1776 % \end{syntax}
1777 % Copies files matching the \meta{glob} from the \meta{source} directory
1778 % to the \meta{destination}; returns an error level.
1779 % \end{function}
1780 %
1781 % \begin{function}{direxists()}
1782 % \begin{syntax}
1783 % |direxists(|\meta{dir}|)|
1784 % \end{syntax}
1785 % Tests if the \meta{dir} exists; returns a boolean value.
1786 % \end{function}
1787 %
1788 % \begin{function}{fileexists()}
1789 % \begin{syntax}
1790 % |fileexists(|\meta{file}|)|
1791 % \end{syntax}
1792 % Tests if the \meta{file} exists and is readable; returns a boolean value.
1793 % \end{function}
1794 %
1795 % \begin{function}{filelist()}
1796 % \begin{syntax}
1797 % |filelist(|\meta{path}, \oarg{glob}|)|
1798 % \end{syntax}
1799 % Returns a table containing all of the files with the \meta{path}
1800 % which match the \meta{glob}; if the latter is absent returns a list of
1801 % all files in the \meta{path}.
1802 % \end{function}
1803 %
1804 % \begin{function}{ordered_filelist()}
1805 % \begin{syntax}
1806 % |ordered_filelist(|\meta{path}, \oarg{glob}|)|
1807 % \end{syntax}
1808 % Like |filelist()| but returning a sorted table.
1809 % \end{function}
1810 %
1811 % \begin{function}{glob_to_pattern()}
1812 % \begin{syntax}
1813 % |glob_to_pattern(|\meta{glob}|)|
1814 % \end{syntax}
1815 % Returns the \meta{glob} converted to a Lua pattern.
1816 % \end{function}
1817 %
1818 % \begin{function}{jobname()}
1819 % \begin{syntax}
1820 % |jobname(|\meta{file}|)|
1821 % \end{syntax}
1822 % Returns a string comprising the jobname of the file with the
1823 % path and extension removed (\emph{i.e.}~from the last |/| up to the
1824 % last |.|).
1825 % \end{function}
1826 %
1827 % \begin{function}{mkdir()}
1828 % \begin{syntax}
1829 % |mkdir(|\meta{dir}|)|
1830 % \end{syntax}
1831 % Creates the \meta{dir}; returns an error level.
1832 % \end{function}
1833 %
1834 % \begin{function}{ren()}
1835 % \begin{syntax}
1836 % |ren(|\meta{dir}, \meta{source}, \meta{destination}|)|
1837 % \end{syntax}
1838 % Renames the \meta{source} file to the \meta{destination} name within
1839 % the \meta{dir}; returns an error level.
1840 % \end{function}
1841 %
1842 % \begin{function}{rm()}
1843 % \begin{syntax}
1844 % |rm(|\meta{dir}, \meta{glob}|)|
1845 % \end{syntax}
1846 % Removes files in the \meta{dir} matching the \meta{glob}; returns an
1847 % error level.
1848 % \end{function}
1849 %
1850 % \begin{function}{run()}
1851 % \begin{syntax}
1852 % |run(|\meta{dir}, \meta{cmd}|)|
1853 % \end{syntax}
1854 % Executes the \meta{cmd}, starting it in the \meta{dir}; returns an
1855 % error level.
1856 % \end{function}
1857 %
1858 % \begin{function}{splitpath()}
1859 % \begin{syntax}
1860 % |splitpath(|\meta{file}|)|
1861 % \end{syntax}
1862 % Returns two strings split at the last |/|: the \texttt{dirname()} and
1863 % the |basename()|.
1864 % \end{function}
1865 %
1866 % \begin{function}{normalize_path()}
1867 % \begin{syntax}
1868 % |normalize_path(|\meta{path}|)|
1869 % \end{syntax}
1870 % When called on Windows, returns a string comprising the \meta{path} with
1871 % |/| characters replaced by |\|. In other cases returns the path unchanged.
1872 % \end{function}
1873 %
1874 % \subsection{System-dependent strings}
1875 %
1876 % To support creation of additional functionality, the following low-level
1877 % strings are exposed by \pkg{l3build}: these all have system-dependent
1878 % definitions and avoid the need to test |os.type| during the construction
1879 % of system calls.
1880 %
1881 % \begin{variable}{os_concat}
1882 % The concatenation operation for using multiple commands in one
1883 % system call, \emph{e.g.}
1884 % \begin{verbatim}
1885 % os.execute("tex " .. file .. os_concat .. "tex " .. file)
1886 % \end{verbatim}
1887 % \end{variable}
1888 %
1889 % \begin{variable}{os_null}
1890 % The location to redirect commands which should produce no output
1891 % at the terminal: almost always used preceded by |>|, \emph{e.g.}
1892 % \begin{verbatim}
1893 % os.execute("tex " .. file .. " > " .. os_null)
1894 % \end{verbatim}
1895 % \end{variable}
1896 %
1897 % \begin{variable}{os_pathsep}
1898 % The separator used when setting an environment variable to multiple
1899 % paths, \emph{e.g.}
1900 % \begin{verbatim}
1901 % os.execute(os_setenv .. " PATH=../a" .. os_pathsep .. "../b")
1902 % \end{verbatim}
1903 % \end{variable}
1904 %
1905 % \begin{variable}{os_setenv}
1906 % The command to set an environmental variable, \emph{e.g.}
1907 % \begin{verbatim}
1908 % os.execute(os_setenv .. " PATH=../a")
1909 % \end{verbatim}
1910 % \end{variable}
1911 %
1912 % \begin{variable}{os_yes}
1913 % \textbf{DEPRECATED}
1914 % A command to generate a series of $300$ lines each containing the
1915 % character |y|: this is useful as the Unix |yes| command cannot be
1916 % used inside |os.execute| (it does not terminate).
1917 %
1918 % Rather than use this function, we recommend the replacement construct
1919 % \begin{verbatim}
1920 % io.popen(<cmd>,"w"):write(string.rep("y\n", 300)):close()
1921 % \end{verbatim}
1922 % \end{variable}
1923 %
1924 % \subsection{Components of \texttt{l3build}}
1925 %
1926 % \begin{function}{call()}
1927 % \begin{syntax}
1928 % |call(|\meta{dirs}, \meta{target}, \oarg{options}|)|
1929 % \end{syntax}
1930 % Runs the \texttt{l3build} \meta{target} (a string) for each directory in the
1931 % \meta{dirs} (a table). This will pass command line options for the parent
1932 % script to the child processes. The \meta{options} table should take the
1933 % same form as the global \meta{options}, described above. If it is
1934 % absent then the global list is used. Note that any entry for the
1935 % |target| in this table is ignored.
1936 % \end{function}
1937 %
1938 % \begin{function}{install_files()}
1939 % \begin{syntax}
1940 % |install_files(|\meta{target},\meta{full},\meta{dry-run}|)|
1941 % \end{syntax}
1942 % Installs the files from the module into the TDS root \meta{target}.
1943 % If \meta{full} is \texttt{true}, all files are copied: if it is
1944 % \texttt{false}, the \texttt{doc} and \texttt{source} trees are skipped.
1945 % If \meta{dry-run} is \texttt{true}, no files are copied, but instead the
1946 % files which would be copied are reported.
1947 % \end{function}
1948 %
1949 % \subsection{Typesetting functions}
1950 %
1951 % All typesetting functions return $0$ on a successful completion.
1952 %
1953 % \begin{function}{biber()}
1954 % \begin{syntax}
1955 % |biber(|\meta{name},\meta{dir}|)|
1956 % \end{syntax}
1957 % Runs Biber on the \meta{name} (\emph{i.e.}~a jobname lacking any
1958 % extension) inside the \meta{dir}. If there is no |.bcf| file then
1959 % no action is taken with a return value of $0$.
1960 % \end{function}
1961 %
1962 % \begin{function}{bibtex()}
1963 % \begin{syntax}
1964 % |bibtex(|\meta{name},\meta{dir}|)|
1965 % \end{syntax}
1966 % Runs Bib\TeX{} on the \meta{name} (\emph{i.e.}~a jobname lacking any
1967 % extension) inside the \meta{dir}. If there are no |\citation| lines in
1968 % the |.aux| file then no action is taken with a return value of $0$.
1969 % \end{function}
1970 %
1971 % \begin{function}{makeindex()}
1972 % \begin{syntax}
1973 % |makeindex(|\meta{name},\meta{dir},\meta{inext},\meta{outext},\meta{logext},\meta{style}|)|
1974 % \end{syntax}
1975 % Runs MakeIndex on the \meta{name} (\emph{i.e.}~a jobname lacking any
1976 % extension) inside the \meta{dir}. The various extensions and the \meta{style}
1977 % should normally be given as it standard for MakeIndex.
1978 % \end{function}
1979 %
1980 % \begin{function}{tex()}
1981 % \begin{syntax}
1982 % |tex(|\meta{file},\meta{dir},\meta{cmd}|)|
1983 % \end{syntax}
1984 % Runs \meta{cmd} (by default \luavar{typesetexe} \luavar{typesetopts}) on the
1985 % \meta{file} inside the \meta{dir}.
1986 % \end{function}
1987 %
1988 % \begin{function}{runcmd()}
1989 % \begin{syntax}
1990 % |runcmd(|\meta{cmd},\meta{dir},|{|\meta{envvars}|})|
1991 % \end{syntax}
1992 % A generic function which runs the \meta{cmd} in the \meta{dir}, first
1993 % setting up all of the environmental variables specified to
1994 % point to the |local| and |working| directories. This function is useful
1995 % when creating non-standard typesetting steps.
1996 % \end{function}
1997 %
1998 % \subsection{Customizing the target and option lists}
1999 %
2000 % The targets known to \pkg{l3build} are stored in the global table
2001 % |target_list|. Each entry should have at least a |func|, pointing to the
2002 % function used to implement the target. This function will receive the
2003 % list of names given at the command line as a table argument.
2004 % In most cases, targets will also have a |desc|, used to construct |help()|
2005 % automatically. In addition, the following may also be used:
2006 % \begin{itemize}
2007 % \item |bundle_func| A variant of |func| used when at the top level of
2008 % a bundle
2009 % \item |bundle_target| A boolean to specify that when passing the target
2010 % name in a bundle, it should have |bundle| prepended.
2011 % \item |pre| A function executed before the main function, and receiving
2012 % the |names| as an argument; this allows checking of the |name| data
2013 % without impact on the main |func|.
2014 % \end{itemize}
2015 % The functions |func|, |bundle_func| and |pre| must return 0 on success.
2016 %
2017 % The list of options (switches) is controlled by the |option_list| table.
2018 % The name of each entry in the table is the \enquote{long} version of the
2019 % option. Each entry requires a |type|, one of |boolean|, |string| or
2020 % |table|. As for targets, each entry should have a |desc| to construct
2021 % the |help()|. It is also possible to provide a |short| name for the option:
2022 % this should be a single letter.
2023 %
2024 % \subsection{Customizing the manifest file}
2025 % \label{sec:manifest}
2026 %
2027 % The default setup for the manifest file creating with the \texttt{manifest}
2028 % target attempt to reflect the defaults for \pkg{l3build} itself.
2029 % The groups (and hence the files) displayed can be completely
2030 % customized by defining a new setup function which creates a Lua table with
2031 % the appropriate settings (Section~\vref{sec:manifest-groups}).
2032 %
2033 % The formatting within the manifest file can be customized by redefining a number
2034 % of Lua functions. This includes
2035 % how the files are sorted within each group (Section~\vref{sec:manifest-sorting}),
2036 % the inclusion of one-line descriptions for each file (Section~\vref{sec:manifest-desc}),
2037 % and the details of the formatting of each entry (Section~\vref{sec:manifest-formatting}).
2038 %
2039 % To perform such customizations, either include the re-definitions directly within your
2040 % package's |build.lua| file, or make a copy of |l3build-manifest-setup.lua|, rename it,
2041 % and load it within your |build.lua| using |dofile()|.
2042 %
2043 %
2044 % \subsubsection{Custom manifest groups}
2045 % \label{sec:manifest-groups}
2046 %
2047 % The setup code for defining each group of files within the manifest looks something like
2048 % the following:
2049 % \begin{verbatim}
2050 % manifest_setup = function()
2051 % local groups = {
2052 % {
2053 % subheading = "Repository files",
2054 % description = [[
2055 % Files located in the package development repository.
2056 % ]],
2057 % },
2058 % {
2059 % name = "Source files",
2060 % description = [[
2061 % These are source files generating the package files.
2062 % ]],
2063 % files = {sourcefiles},
2064 % },
2065 % {
2066 % name = "Typeset documentation source files",
2067 % description = [[
2068 % These files are typeset using LaTeX to produce the PDF documentation for the package.
2069 % ]],
2070 % files = {typesetfiles,typesetsourcefiles,typesetdemofiles},
2071 % },
2072 % ...
2073 % }
2074 % return groups
2075 % end
2076 % \end{verbatim}
2077 %
2078 % The |groups| variable is an ordered array of tables which contain the metadata about each
2079 % `group' in the manifest listing.
2080 % The keys supported in these tables are outlined in
2081 % Tables~\vref{tab:manifest-setup} and~\vref{tab:manifest-subheadings}.
2082 % See the complete setup code in |l3build-manifest-setup.lua| for examples of these in use.
2083 %
2084 % \begin{table}
2085 % \caption{Table entries used in the manifest setup table for a group.}
2086 % \label{tab:manifest-setup}
2087 % \centering
2088 % \begin{tabular}{lp{8cm}}
2089 % \toprule
2090 % Entry & Description \\
2091 % \midrule
2092 % \var{name} & The heading of the group \\
2093 % \var{description} & The description printed below the heading \\
2094 % \var{files} & Files to include in this group \\
2095 % \var{exclude} & Files to exclude (default |{excludefiles}|) \\
2096 % \var{dir} & The directory to search (default |maindir|) \\
2097 % \var{rename} & An array with a |gsub| redefinition for the filename \\
2098 % \var{skipfiledescription} & Whether to extract file descriptions from these files (default |false|) \\
2099 % \bottomrule
2100 % \end{tabular}
2101 % \end{table}
2102 %
2103 % \begin{table}
2104 % \caption{Table entries used in the manifest setup table for a subheading.}
2105 % \label{tab:manifest-subheadings}
2106 % \centering
2107 % \begin{tabular}{lp{8cm}}
2108 % \toprule
2109 % Entry & Description \\
2110 % \midrule
2111 % \var{subheading} & The subheading \\
2112 % \var{description} & The description printed below the subheading \\
2113 % \bottomrule
2114 % \end{tabular}
2115 % \end{table}
2116 %
2117 %
2118 % \subsubsection{Sorting within each manifest group}
2119 % \label{sec:manifest-sorting}
2120 %
2121 % Within a single group in the manifest listing, files can be matched against multiple variables.
2122 % For example, for |sourcefiles={*.dtx,*.ins}| the following (unsorted) file listing might result:
2123 % \begin{itemize}[nosep]
2124 % \item foo.dtx
2125 % \item bar.dtx
2126 % \item foo.ins
2127 % \item bar.ins
2128 % \end{itemize}
2129 % This listing can be sorted using two separate functions by the default manifest code.
2130 % The first, default, is to sort alphabetically within a single variable match.
2131 % This keeps all files of a single extension contiguous in the listing.
2132 % To edit how this sort is performed, redefine the |manifest_sort_within_match| function.
2133 %
2134 % The second approach to sorting is to apply a sorting function to the entire set of matched files.
2135 % (This happens \emph{after} any sorting is applied for each match.)
2136 % By default this is a no-op but can be edited by redefining the |manifest_sort_within_group|
2137 % function. For example:
2138 % \begin{verbatim}
2139 % manifest_sort_within_group = function(files)
2140 % local f = files
2141 % table.sort(f)
2142 % return f
2143 % end
2144 % \end{verbatim}
2145 % This will produce an alphabetical listing of files:
2146 % \begin{itemize}
2147 % \item bar.dtx
2148 % \item bar.ins
2149 % \item foo.dtx
2150 % \item foo.ins
2151 % \end{itemize}
2152 %
2153 %
2154 % \subsubsection{File descriptions}
2155 % \label{sec:manifest-desc}
2156 %
2157 % By default the manifest contains lists of files, and with a small addition these
2158 % lists can be augmented with a one-line summary of each file.
2159 % If the Lua function |manifest_extract_filedesc| is defined, it will be used to search
2160 % the contents of each file to extract a description for that file.
2161 % For example, perhaps you are using multiple |.dtx| files for a project and the argument
2162 % to the first |\section| in each can be used as a file description:
2163 % \begin{verbatim}
2164 % manifest_extract_filedesc = function(filehandle,filename)
2165 %
2166 % local all_file = filehandle:read("a")
2167 % local matchstr = "\\section{(.-)}"
2168 %
2169 % filedesc = string.match(all_file,matchstr)
2170 %
2171 % return filedesc
2172 % end
2173 % \end{verbatim}
2174 % (Note the |matchstr| above is only an example and doesn't handle nested braces.)
2175 %
2176 %
2177 % \subsubsection{Custom formatting}
2178 % \label{sec:manifest-formatting}
2179 %
2180 % After the manifest code has built a complete listing of files to print, a series of
2181 % file writing operations are performed which create the manifest file.
2182 % The following functions can be re-defined to change the formatting of the manifest file:
2183 % \begin{itemize}
2184 % \item |manifest_write_opening|: Write the heading of the manifest file and its opening paragraph.
2185 % \item |manifest_write_subheading|: Write a subheading and description
2186 % \item |manifest_write_group_heading|: Write the section heading of the manifest group and the group description
2187 % \item |manifest_write_group_file|: Write the filename (when not writing file descriptions)
2188 % \item |manifest_write_group_file_descr|: Write the filename and the file description
2189 % \end{itemize}
2190 % Full descriptions of their usage and arguments can be found within the |l3build-manifest-setup.lua|
2191 % code itself.
2192 %
2193 % \section{Known limitations}
2194 %
2195 % \subsection{Non-\textsc{ascii} filenames}
2196 %
2197 % On Windows, support for non-\textsc{ascii} filenames is limited by the way
2198 % that Lua handles system calls. While calling \TeX{} engines should work with
2199 % any name, general file operations will only success if the filename falls
2200 % within the codepage currently in use by the operating system.
2201 %
2202 % \end{documentation}
2203 %
2204 % \begin{implementation}
2205 %
2206 % \clearpage
2207 % \section{\texttt{regression-test.tex}}
2208 %
2209 % This section describes the code for setting up the regression test system.
2210 % Each test file should start with |\input regression-test.tex\relax|.
2211 %
2212 % \begin{macrocode}
2213 %<*package>
2214 % \end{macrocode}
2215 %
2216 % \subsection{Preliminaries}
2217 %
2218 % We require \eTeX{} for some features.
2219 % \begin{macrocode}
2220 \begingroup\expandafter\expandafter\expandafter\endgroup
2221 \expandafter\ifx\csname eTeXversion\endcsname\relax
2222 \message{e-TeX is required by some regression-test.tex features}%
2223 \fi
2224 % \end{macrocode}
2225 %
2226 % \begin{macro}{\reset@catcodes}
2227 % Unlike in the \LaTeXe{} regression test suite, reset catcodes: each test
2228 % should set these as appropriate. There's also a quick test for Con\TeX{}t:
2229 % it defines |\unprotect| which should be a reasonable marker (and is
2230 % needed as some catcodes are otherwise wrong).
2231 % \begin{macrocode}
2232 \ifx\unprotect\undefined
2233 \expandafter\edef\csname reset\string @catcodes\endcsname{%
2234 \catcode`\noexpand\@=\the\catcode`\@\relax
2235 }%
2236 \catcode`\@=11 %
2237 \else
2238 \unprotect
2239 \def\reset@catcodes{\protect}%
2240 \fi
2241 % \end{macrocode}
2242 % \end{macro}
2243 %
2244 % Put \TeX{} into scroll mode, and stop it showing the
2245 % implementation details of macros in error messages.
2246 % \begin{macrocode}
2247 \begingroup\expandafter\expandafter\expandafter\endgroup
2248 \expandafter\ifx\csname interactionmode\endcsname\relax
2249 \else
2250 \ifnum\interactionmode>1 \scrollmode\fi
2251 \fi
2252 \errorcontextlines=-1 %
2253 % \end{macrocode}
2254 %
2255 % Show all box details: this avoids getting variable results if boxes
2256 % have different numbers of lines (\LuaTeX{} adds extra information).
2257 % \begin{macrocode}
2258 \showboxbreadth=\maxdimen
2259 \showboxdepth=\maxdimen
2260 % \end{macrocode}
2261 %
2262 % \begin{macro}{\logginoutput}
2263 % The |\showoutput| command of \LaTeX{} calls |\loggingoutput| which in turn
2264 % calls |\errorstopmode| but we want to continue running without any stops.
2265 % \begin{macrocode}
2266 \def\loggingoutput{%
2267 \tracingoutput=1 %
2268 \showboxbreadth=\maxdimen
2269 \showboxdepth=\maxdimen
2270 }
2271 % \end{macrocode}
2272 % \end{macro}
2273 %
2274 % Set the newline character: \LaTeXe{} does this but plain-based formats do
2275 % not.
2276 % \begin{macrocode}
2277 \newlinechar=`\^^J
2278 % \end{macrocode}
2279 %
2280 % \subsection{Commands in test files}
2281 %
2282 % \begin{macro}{\LONGTYPEOUT, \TYPE}
2283 % A long version of |\typeout|, because tests may contain |\par| tokens.
2284 % Besides, with that |\TYPE|, we can do
2285 % |\TYPE { ... \TRUE ... \NEWLINE ... }|.
2286 % \begin{macrocode}
2287 \long\def\LONGTYPEOUT#1{%
2288 \begingroup
2289 \long\def\TYPE##1{##1}%
2290 \immediate\write128{#1}%
2291 \endgroup
2292 }
2293 \let\TYPE\LONGTYPEOUT
2294 % \end{macrocode}
2295 % \end{macro}
2296 %
2297 % \begin{macro}{\STARTMESSAGE, \START}
2298 % Start the test, after the optional |\documentclass|
2299 % |\begin{document}| commands with |\START|. All lines in the |.log| file
2300 % before this will be ignored.
2301 % \begin{macrocode}
2302 \def\STARTMESSAGE{This is a generated file for the l3build validation system.}
2303 \def\START{%
2304 \LONGTYPEOUT{^^JSTART-TEST-LOG^^J}%
2305 \LONGTYPEOUT{^^J%
2306 \STARTMESSAGE%
2307 ^^J^^JDon't change this file in any respect.%
2308 ^^J^^J%
2309 }%
2310 }
2311 % \end{macrocode}
2312 % \end{macro}
2313 %
2314 % \begin{macro}{\@@@end, \END}
2315 % The test should end with |\END| or |\end{document}|
2316 % or |\bye| in plain \TeX{}.
2317 % \begin{macrocode}
2318 \ifx\@@end\@undefined
2319 \let\@@@end\end
2320 \else
2321 \let\@@@end\@@end
2322 \fi
2323 \def\END{%
2324 \ifnum\currentgrouplevel>0 %
2325 \LONGTYPEOUT{Bad grouping: \the\currentgrouplevel!}%
2326 \fi
2327 \ifnum\currentiflevel>1 %
2328 \LONGTYPEOUT{Bad conditionals: \the\numexpr\currentiflevel-1!}%
2329 \fi
2330 \LONGTYPEOUT{^^JEND-TEST-LOG^^J}%
2331 \@@@end
2332 }
2333 \begingroup\expandafter\expandafter\expandafter\endgroup
2334 \expandafter\ifx\csname currentgrouplevel\endcsname\relax
2335 \def\END{%
2336 \LONGTYPEOUT{^^JEND-TEST-LOG^^J}%
2337 \@@@end
2338 }
2339 \fi
2340 \ifx\@@end\@undefined
2341 \let\end\END
2342 \else
2343 \let\@@end\END
2344 \fi
2345 % \end{macrocode}
2346 % \end{macro}
2347 %
2348 % \begin{macro}{\OMIT, \TIMO}
2349 % Surround commands which produce irrelevant lines in the |.log| file by
2350 % |\OMIT|\dots|\TIMO|
2351 % \begin{macrocode}
2352 \def\OMIT{\LONGTYPEOUT{OMIT}}
2353 \def\TIMO{\LONGTYPEOUT{TIMO}}
2354 % \end{macrocode}
2355 % \end{macro}
2356 %
2357 % \begin{macro}{\SHOWFILE}
2358 % Load a file (e.g.,| \jobname.toc|) into the .log file with the usual special
2359 % characters rendered harmless. Use as |\SHOWFILE{\jobname.aux}|.
2360 % \begin{macrocode}
2361 \begingroup % within the scope of this groups each line needs to end in % !
2362 \catcode`\^^M\active %
2363 \gdef\SHOWFILE#1{%
2364 \typeout{-------- #1 (start) ---------}%
2365 \IfFileExists{#1}%
2366 {\begingroup %
2367 \catcode`\^^M\active %
2368 \edef^^M{[nl]^^J}%
2369 \everyeof{\noexpand}%
2370 \obeyspaces %
2371 \@sanitize %
2372 \message{\@@input #1 }%
2373 \endgroup }%
2374 {\message{Not found}}%
2375 \typeout{-------- #1 (end) -----------}%
2376 }%
2377 \endgroup
2378 \begingroup\expandafter\expandafter\expandafter\endgroup
2379 \expandafter\ifx\csname everyeof\endcsname\relax
2380 \def\SHOWFILE#1{\TYPE{FEATURE UNAVAILABLE}}
2381 \fi
2382 % \end{macrocode}
2383 % \end{macro}
2384 %
2385 % To allow testing of possible changes, we allow extra code to be read
2386 % in before the test starts. The necessary code should be placed in a
2387 % file |regression-test.cfg|.
2388 % \begin{macrocode}
2389 \ifx\InputIfFileExists\@undefined
2390 \newread\@inputcheck
2391 \long\def\InputIfFileExists#1#2#3{%
2392 \openin\@inputcheck#1\relax
2393 \ifeof\@inputcheck
2394 \def\reserved@a{#3}%
2395 \else
2396 \def\reserved@a{#2\input #1\relax}%
2397 \fi
2398 \closein\@inputcheck
2399 \reserved@a
2400 }%
2401 \fi
2402 \InputIfFileExists{regression-test.cfg}
2403 {\LONGTYPEOUT{^^J***^^Jregression-test.cfg in operation^^J***^^J}}{}
2404 % \end{macrocode}
2405 %
2406 % \subsection{Showing PDF Tag Tree}
2407 %
2408 % \begin{macro}{\SHOWPDFTAGS}
2409 % Insert a marker in the log. The normalized log will have
2410 % The output from \texttt{show-pdf-tags} inserted at that point.
2411 % \begin{macrocode}
2412 \gdef\SHOWPDFTAGS{%
2413 \BEGINTEST{Show PDF Tags}%
2414 \TYPE{^^J^^J%
2415 -------- \jobname.xml (start) ---------^^J%
2416 --INSERT-PDF-TAGS \jobname.pdf ^^J%
2417 -------- \jobname.xml (end) -----------^^J%
2418 ^^J}%
2419 \ENDTEST
2420 }
2421 % \end{macrocode}
2422 % \end{macro}
2423 % \subsection{Formatting the \texttt{.log} file}
2424 %
2425 % \begin{macro}{\gTESTint}
2426 % For tracking the total number of tests.
2427 % \begin{macrocode}
2428 \newcount\gTESTint
2429 % \end{macrocode}
2430 % \end{macro}
2431 %
2432 % \begin{macro}
2433 % {
2434 % \SEPARATOR,
2435 % \BEGINTEST,
2436 % \ENDTEST,
2437 % \TEST,
2438 % \TESTEXP,
2439 % \TRUE,
2440 % \FALSE,
2441 % \YES,
2442 % \NO,
2443 % \NEWLINE,
2444 % \ASSERT,
2445 % \ASSERTSTR
2446 % }
2447 % We are not starved for space in the log file output, so let's make it as
2448 % verbose as is useful when reading the |.diff|'s.
2449 % \begin{macrocode}
2450 \def\SEPARATOR{%
2451 \TYPE{%
2452 ============================================================%
2453 }%
2454 }
2455 \csname protected\endcsname\long\def\BEGINTEST#1{%
2456 \global\advance\gTESTint by 1 %
2457 \SEPARATOR
2458 \LONGTYPEOUT{TEST \the\gTESTint: \detokenize{#1}}%
2459 \SEPARATOR
2460 \begingroup
2461 \let\TYPE\LONGTYPEOUT
2462 }
2463 \begingroup\expandafter\expandafter\expandafter\endgroup
2464 \expandafter\ifx\csname detokenize\endcsname\relax
2465 \long\def\BEGINTEST#1{%
2466 \global\advance\gTESTint by 1 %
2467 \SEPARATOR
2468 \begingroup
2469 \toks0={#1}%
2470 \LONGTYPEOUT{TEST \the\gTESTint: \the\toks0 }%
2471 \endgroup
2472 \SEPARATOR
2473 \begingroup
2474 \let\TYPE\LONGTYPEOUT
2475 }
2476 \fi
2477 \csname protected\endcsname\long\def\ENDTEST{%
2478 \endgroup
2479 \SEPARATOR
2480 \LONGTYPEOUT{}%
2481 }
2482 \long\def\TEST#1#2{%
2483 \BEGINTEST{#1}%
2484 #2%
2485 \ENDTEST
2486 }
2487 \long\def\TESTEXP#1#2{%
2488 \BEGINTEST{#1}%
2489 \LONGTYPEOUT{#2}%
2490 \ENDTEST
2491 }
2492 \def \TRUE {\TYPE{TRUE}}
2493 \def \FALSE {\TYPE{FALSE}}
2494 \def \YES {\TYPE{YES}}
2495 \def \NO {\TYPE{NO}}
2496 \def \NEWLINE {\TYPE{^^J}}
2497 \csname protected\endcsname\long\def\ASSERT#1#2{%
2498 \begingroup
2499 \edef\@tempa{#1}%
2500 \edef\@tempb{#2}%
2501 \ifx\@tempa\@tempb
2502 \TYPE{PASSED}%
2503 \else
2504 \TYPE{FAILED}%
2505 \fi
2506 \endgroup
2507 }
2508 \csname protected\endcsname\long\def\ASSERTSTR#1#2{%
2509 \begingroup
2510 \edef\@tempa{#1}%
2511 \edef\@tempb{#2}%
2512 \edef\@tempa{\meaning\@tempa}%
2513 \edef\@tempb{\meaning\@tempb}%
2514 \ifx\@tempa\@tempb
2515 \TYPE{PASSED}%
2516 \else
2517 \TYPE{FAILED}%
2518 \fi
2519 \endgroup
2520 }
2521 \begingroup\expandafter\expandafter\expandafter\endgroup
2522 \expandafter\ifx\csname detokenize\endcsname\relax
2523 \long\def\ASSERTSTR#1#2{%
2524 \TYPE{FEATURE UNAVAILABLE}%
2525 }
2526 \fi
2527 % \end{macrocode}
2528 % \end{macro}
2529 %
2530 % \subsection{Suppressing variable data in output}
2531 %
2532 % Disable compression in PDF output.
2533 % \begin{macrocode}
2534 \ifnum 0%
2535 \ifx\pdfoutput\@undefined\else\ifnum\pdfoutput>0 1\fi\fi
2536 \ifx\outputmode\@undefined\else\ifnum\outputmode>0 1\fi\fi
2537 >0 %
2538 \ifx\pdfvariable\@undefined
2539 \pdfcompresslevel=0 %
2540 \pdfobjcompresslevel=0 %
2541 \else
2542 \pdfvariable compresslevel=0 %
2543 \pdfvariable objcompresslevel=0 %
2544 \fi
2545 \else
2546 \ifx\XeTeXversion\@undefined
2547 \special{%
2548 ps: /setdistillerparams
2549 where
2550 {pop << /CompressPages false /CompressStreams false >> setdistillerparams}
2551 if
2552 }%
2553 \else
2554 \special{dvipdfmx:config z 0}% Compress level
2555 \special{dvipdfmx:config C 0x40}% Object compression
2556 \fi
2557 \fi
2558 % \end{macrocode}
2559 %
2560 %
2561 % \begin{macrocode}
2562 \begingroup\expandafter\expandafter\expandafter\endgroup
2563 \expandafter\ifx\csname protected\endcsname\relax
2564 \reset@catcodes
2565 \let\protected\undefined
2566 \expandafter\endinput
2567 \fi
2568 % \end{macrocode}
2569 %
2570 % Load the map file early so it does not appear in the log.
2571 % \begin{macrocode}
2572 \ifx\pdfoutput\@undefined
2573 \ifx\outputmode\@undefined
2574 \else
2575 \ifnum\outputmode>0 %
2576 \pdfextension mapfile{pdftex.map}%
2577 \fi
2578 \fi
2579 \else
2580 \ifnum\pdfoutput>0 %
2581 \pdfmapfile{pdftex.map}%
2582 \fi
2583 \fi
2584 % \end{macrocode}
2585 %
2586 % To make any PDF file produced comparable we need to suppress various
2587 % pieces of data. This works in concert with setting the epoch from the
2588 % environment side (as not all output can be controlled here).
2589 % There is a limit to what can be done with the underlying PDF structure so
2590 % there is no point entirely suppressing \texttt{Producer}: simply avoid
2591 % any version numbers. If the pdfmanagement is loaded we use its function
2592 % if it exists.
2593 % \begin{macrocode}
2594 \ifcsname pdfmeta_set_regression_data:\endcsname
2595 \csname pdfmeta_set_regression_data:\endcsname
2596 \else
2597 \ifnum 0%
2598 \ifx\pdfoutput\@undefined\else\ifnum\pdfoutput>0 1\fi\fi
2599 \ifx\outputmode\@undefined\else\ifnum\outputmode>0 1\fi\fi
2600 >0 %
2601 \ifx\pdfvariable\@undefined
2602 \pdfinfo{/Producer (\ifx\directlua\@undefined pdf\else Lua\fi TeX)}
2603 \ifx\pdfinfoomitdate\@undefined\else
2604 \pdfinfoomitdate = 1 %
2605 \pdfsuppressptexinfo = \numexpr
2606 0
2607 + 1 % PTEX.Fullbanner
2608 + 2 % PTEX.FileName
2609 \relax
2610 \pdftrailerid{}
2611 \fi
2612 \else
2613 \pdfextension info{/Producer (LuaTeX)}
2614 \pdfvariable suppressoptionalinfo \numexpr
2615 0
2616 + 1 % PTEX.Fullbanner
2617 + 2 % PTEX.FileName
2618 + 32 % CreationDate
2619 + 64 % ModDate
2620 + 512 % ID
2621 \relax
2622 \fi
2623 \else
2624 \ifx\XeTeXversion\@undefined
2625 \special{! <</DocumentUUID (DocumentUUID)>> setpagedevice}
2626 \special{! <</InstanceUUID (InstanceUUID)>> setpagedevice}
2627 \else
2628 \special{%
2629 pdf: docinfo
2630 <<
2631 /Creator (TeX)
2632 /CreationDate ()
2633 /ModDate ()
2634 /Producer (xdvipdfmx)
2635 >>
2636 }
2637 \fi
2638 \fi
2639 \fi
2640 % \end{macrocode}
2641 % Suppress version data in \LaTeX{} runs.
2642 % \begin{macrocode}
2643 \ifdefined\AddToHook
2644 \AddToHook{enddocument/info}[kernel/testmode]{}
2645 \DeclareHookRule{enddocument/info}{kernel/testmode}{voids}{kernel/release}
2646 \fi
2647 % \end{macrocode}
2648 %
2649 % \begin{macrocode}
2650 \ifcsname\detokenize{l_iow_line_count_int}\endcsname
2651 \csname \detokenize{l_iow_line_count_int}\endcsname=9999 %
2652 \fi
2653 % \end{macrocode}
2654 %
2655 % Finish up.
2656 % \begin{macrocode}
2657 \reset@catcodes
2658 % \end{macrocode}
2659 %
2660 % \begin{macrocode}
2661 %</package>
2662 % \end{macrocode}
2663 %
2664 % \newpage
2665 % \section{\texttt{l3build.lua}}
2666 %
2667 % This section consists of the |l3build.lua| code.
2668 % This code is \emph{not} generated from |l3build.dtx| since it needs to already be extracted to build \pkg{l3build} itself!
2669 % As Frank says, we don't want to end up with a double M\"unchhausen.
2670 %
2671 % \lstinputlisting
2672 % [
2673 % basicstyle=\ttfamily\scriptsize,
2674 % numbers=left,
2675 % numberstyle={\tiny\color[gray]{0.4}},
2676 % language={[5.2]Lua},
2677 % procnamekeys=function,
2678 % procnamestyle=\color{red},
2679 % ]
2680 % {l3build.lua}
2681 %
2682 % \end{implementation}
2683 %
2684 % \PrintIndex