| 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 |