From 36898810305246554a1e0e8a046879cb7c9e6db3 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sat, 28 Aug 2021 20:36:53 +0000 Subject: l3build (28aug21) git-svn-id: svn://tug.org/texlive/trunk@60344 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/source/latex/l3build/l3build.dtx | 39 +++++++++++++++++++--- 1 file changed, 34 insertions(+), 5 deletions(-) (limited to 'Master/texmf-dist/source') diff --git a/Master/texmf-dist/source/latex/l3build/l3build.dtx b/Master/texmf-dist/source/latex/l3build/l3build.dtx index 5171f109720..8d340552275 100644 --- a/Master/texmf-dist/source/latex/l3build/l3build.dtx +++ b/Master/texmf-dist/source/latex/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