summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/l3build/l3build.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/l3build/l3build.dtx')
-rw-r--r--macros/latex/contrib/l3build/l3build.dtx39
1 files changed, 34 insertions, 5 deletions
diff --git a/macros/latex/contrib/l3build/l3build.dtx b/macros/latex/contrib/l3build/l3build.dtx
index 5171f10972..8d34055227 100644
--- a/macros/latex/contrib/l3build/l3build.dtx
+++ b/macros/latex/contrib/l3build/l3build.dtx
@@ -121,7 +121,6 @@
\luavarseparator
\luavarset{typesetexe} {"pdflatex"} {Executable for compiling \texttt{doc(s)}}
\luavarset{unpackexe} {"pdftex"} {Executable for running \texttt{unpack}}
-\luavarset{zipexe} {"zip"} {Executable for creating archive with \texttt{ctan}}
\luavarset{biberexe} {"biber"} {Biber executable}
\luavarset{bibtexexe} {"bibtex8"} {\BibTeX{} executable}
\luavarset{makeindexexe} {"makeindex"}{MakeIndex executable}
@@ -130,7 +129,6 @@
\luavarset{checkopts} {"-interaction=nonstopmode"}{Options passed to engine when running checks}
\luavarset{typesetopts}{"-interaction=nonstopmode"}{Options passed to engine when typesetting}
\luavarset{unpackopts} {""} {Options passed to engine when unpacking}
-\luavarset{zipopts} {"-v -r -X"} {Options passed to zip program}
\luavarset{biberopts} {""} {Biber options}
\luavarset{bibtexopts} {"-W"} {\BibTeX{} options}
\luavarset{makeindexopts}{""} {MakeIndex options}
@@ -148,6 +146,7 @@
\luavarseparator
\luavarset{asciiengines}{\{"pdftex"\}}{Engines which should log as pure ASCII}
\luavarset{checkruns} {1} {Number of runs to complete for a test before comparing the log}
+\luavarset{forcecheckruns}{false} {Always run \texttt{checkruns} runs and never stop early}
\luavarset{ctanreadme}{"README.md"} {Name of the file to send to CTAN as \texttt{README.\meta{ext}}}
\luavarset{ctanzip}{ctanpkg ... "-ctan"}{Name of the zip file (without extension) created for upload to CTAN}
\luavarset{epoch} {1463734800} {Epoch (Unix date) to set for test runs}
@@ -237,7 +236,7 @@
% }^^A
% }
%
-% \date{Released 2021-05-06}
+% \date{Released 2021-08-28}
%
% \maketitle
% \tableofcontents
@@ -314,7 +313,7 @@
%
% When the build system runs, it creates a directory |build/| for various unpacking, compilation, and testing purposes.
% 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.
-% A |build/| folder can be safety deleted; all material within is re-generated for each command of the \pkg{l3build} system.
+% A |build/| folder can be safely deleted; all material within is re-generated for each command of the \pkg{l3build} system.
%
% \subsection{The \texttt{build.lua} file}
%
@@ -379,6 +378,8 @@
% \item |--rerun| Run tests without unpacking/set up
% \item |--show-log-on-error| To be used in addition to \texttt{--halt-on-error} and results
% in the full \texttt{.log} file of a failed test to be shown on the console
+% \item |--show-saves| (|-S|) When tests fail, print the \texttt{l3build save} commands needed
+% to regenerate the tests assuming that the failures were false negatives.
% \item |--shuffle| Shuffle the order in which tests run
% \item |--texmfhome| Sets the location of the user tree for installing
% \end{itemize}
@@ -495,7 +496,7 @@
%
% Binary files should be specified with the \var{binaryfiles} variable (default \luavar{binaryfiles}); these are added to the zip archive without normalising line endings (text files are automatically converted to Unix-style line endings).
%
-% To create the archive, by default the binary \var{zipexe} is used (\luavar{zipexe}) with options \var{zipopts} (|-v -r -X|). The intermediate build directories \var{ctandir} and \var{tdsdir} are used to construct the archive.
+% The intermediate build directories \var{ctandir} and \var{tdsdir} are used to construct the archive.
% \end{buildcmd}
%
%
@@ -1117,6 +1118,34 @@
% \label{fig:test-tasks}
% \end{figure}
%
+% \subsection{Instructions for rebuilding test output}
+%
+% Sometimes changes to fundamental parts of the code can cause a lot of tests
+% to fail even though the actually tested systems are still working correctly.
+% This is especially common when the logging and error reporting systems
+% changes and therefore all log file based tests using the component fail with
+% these changes.
+%
+% In these cases, the option |--show-saves| can be passed to
+% |l3build check| in order to generate a list of |l3build save| commands which
+% can be executed to regenerate the expected output of all tests which fail.
+% Additionally it sometimes prints a list of |l3build check| commands for tests
+% which might still fail due to engine differences after running the |save|
+% commands. After running all these |l3build check| commands and all
+% |l3build save| commands listed by them, all tests will succeed.
+%
+% When bundles are used |l3build check --show-saves| has to be executed
+% separately for every module in the bundle.
+%
+% This option is potentially dangerous and therefore should only be used with
+% care. It can easily hide valid test failures between a bunch of spurious
+% changes. Therefore you should always take a close look at the difference
+% files generated by |l3build check| before running the generated
+% |l3build save| commands. Additionally it should only be used when you are
+% aware of the reason why a large number of tests failed and the change
+% causing the failures has been tested separately to have no unintended
+% side effects.
+%
% \subsection{Epoch setting}
%
% To produce predictable output when using dates, the test system offers the