From 66f6e60b6dc60cc08482030b92df223b6a51b15f Mon Sep 17 00:00:00 2001
From: Norbert Preining <norbert@preining.info>
Date: Sun, 29 Aug 2021 03:02:07 +0000
Subject: CTAN sync 202108290302

---
 macros/latex/contrib/l3build/l3build.dtx | 39 ++++++++++++++++++++++++++++----
 1 file changed, 34 insertions(+), 5 deletions(-)

(limited to 'macros/latex/contrib/l3build/l3build.dtx')

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
-- 
cgit v1.2.3

