summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/l3build
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2018-08-03 21:16:27 +0000
committerKarl Berry <karl@freefriends.org>2018-08-03 21:16:27 +0000
commit5010c435d5c9e266b90f68227f41610b19b88465 (patch)
tree6b809d1324d4fac1a92e21c3920a5b459c088dc8 /Master/texmf-dist/source/latex/l3build
parent97b66e90dd2d069b12f64e3339c7486b748d222d (diff)
l3build (3aug18)
git-svn-id: svn://tug.org/texlive/trunk@48340 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/l3build')
-rw-r--r--Master/texmf-dist/source/latex/l3build/l3build.dtx101
1 files changed, 73 insertions, 28 deletions
diff --git a/Master/texmf-dist/source/latex/l3build/l3build.dtx b/Master/texmf-dist/source/latex/l3build/l3build.dtx
index fd2e652347b..f15e1b970a9 100644
--- a/Master/texmf-dist/source/latex/l3build/l3build.dtx
+++ b/Master/texmf-dist/source/latex/l3build/l3build.dtx
@@ -102,13 +102,18 @@
\luavarseparator
\luavarset{bakext}{".bak"}{Extension of backup files}
\luavarset{dviext}{".dvi"}{Extension of DVI files}
-\luavarset{lvtext}{".lvt"}{Extension of test files}
+\luavarset{lvtext}{".lvt"}{Extension of log-based test files}
\luavarset{tlgext}{".tlg"}{Extension of test file output}
+\luavarset{tpfext}{".tpf"}{Extension of PDF-based test output}
\luavarset{lveext}{".lve"}{Extension of auto-generating test file output}
\luavarset{logext}{".log"}{Extension of checking output, before processing it into a \texttt{.tlg}}
+\luavarset{pvtext}{".pvt"}{Extension of PDF-based test files}
\luavarset{pdfext}{".pdf"}{Extension of PDF file for checking and saving}
\luavarset{psext} {".ps"} {Extension of PostScript files}
\luavarseparator
+\luavarset{includetests}{\{"*"\}}{Test names to include when checking}
+\luavarset{excludetests}{\{\}} {Test names to exclude when checking}
+\luavarseparator
\luavarset{checkdeps} {\{\}}{List of dependencies for running checks}
\luavarset{typesetdeps}{\{\}}{List of dependencies for typesetting docs}
\luavarset{unpackdeps} {\{\}}{List of dependencies for unpacking}
@@ -135,7 +140,6 @@
\luavarset{glossarystyle}{"gglo.ist"}{MakeIndex style file for glossary/changes creation}
\luavarset{indexstyle} {"gind.ist"}{MakeIndex style for index creation}
\luavarseparator
-\luavarseparator
\luavarset{biberexe} {"biber"} {Biber executable}
\luavarset{biberopts} {""} {Biber options}
\luavarset{bibtexexe} {"bibtex8"} {\BibTeX{} executable}
@@ -217,7 +221,7 @@
% }^^A
% }
%
-% \date{Released 2018-05-10}
+% \date{Released 2018-08-02}
%
% \maketitle
% \tableofcontents
@@ -315,6 +319,7 @@
% \item |--config| (|-c|) Configuration(s) to use for testing
% \item |--date| Date to use when tagging
% data
+% \item |--dirty| Skip cleaning up of the test area
% \item |--dry-run| Runs the \texttt{install} target but does not copy
% any files: simply lists those that would be installed
% \item |--engine| (|-e|) Sets the engine to use for
@@ -328,11 +333,9 @@
% should stop as soon as possible, rather than running all requested
% tests; the difference file is printed in the terminal directly in the case of failure
% \item |--last| Name of the last test to run
-% \item |--pdf| (|-p|) Test PDF file against a reference
-% version rather than using a log comparison
% \item |--quiet| (|-q|) Suppresses output from unpacking
% \item |--rerun| Run tests without unpacking/set up
-% \item |--shuffle| Shuffle the order in whichs tests run
+% \item |--shuffle| Shuffle the order in which tests run
% \item |--texmfhome| Sets the location of the user tree for installing
% \end{itemize}
%
@@ -382,16 +385,6 @@
% test directory: this may be skipped using the |-s| option.
% \end{buildcmd}
%
-% \begin{buildcmd}{check -p}
-% Rather than the log-based checking carried out by the standard
-% |check| target, running with the |-p| option carries out a binary
-% comparison of the PDF files produced by typesetting against those
-% saved in \var{testfiledir}.
-%
-% This functionality requires \TeX{} Live 2016 or later as it needs support
-% from the engines not available in earlier releases.
-% \end{buildcmd}
-%
% \begin{buildcmd}{clean}
% This command removes all temporary files used for package bundling and regression testing.
% In the standard layout, these are all files within the directories defined by \var{localdir}, \var{testdir}, \var{typesetdir} and \var{unpackdir}, as well as all files defined in the \var{cleanfiles} variable in the same directory as the script.
@@ -496,15 +489,6 @@
% the \enquote{exit status} is zero, else non-zero.
% \end{buildcmd}
%
-% \begin{buildcmd}{save -p \meta{name(s)}}
-% This version of |save| will store the PDF files produced from
-% \texttt{\meta{name(s)}.lvt} in addition to the |.tlg| file, and thus allows
-% binary comparison of the result of typesetting.
-%
-% This functionality requires \TeX{} Live 2016 or later as it needs support
-% from the engines not available in earlier releases.
-% \end{buildcmd}
-%
% \begin{buildcmd}{manifest}
% Generates a `manifest' file which lists the files of the package as known to \pkg{l3build}.
% The filename of this file (by default \luavar{manifestfile}) can be set with the variable \var{manifestfile}.
@@ -650,6 +634,15 @@
%
% \luavartypeset
%
+% \subsection{Selective running of tests}
+%
+% The variables |includetests| and |excludetests| may be used to select which
+% tests are run: these variables take test \emph{names} not full file names.
+% The list of tests in |excludetests| overrides any matches in |includetests|,
+% meaning that tests can be disabled selectively. It also makes it possible
+% to disable test on for example a platform basis: the Lua core variable
+% |os.type| may be used to set |excludetests| only on some systems.
+%
% \subsection{Multiple sets of tests}
%
% In most cases, a single set of tests will be appropriate for the module, with
@@ -1116,6 +1109,24 @@
% \label{fig:expect-ins}
% \end{figure}
%
+% \subsection{PDF-based tests}
+%
+% In most cases, testing is best handled by using the text-based methods
+% outlined above. However, there are cases where the detail of output structure
+% is important. This can only be fully tested by comparing PDF structure.
+% To support this, \pkg{l3build} can be instructed to build and compare
+% PDF files by setting up tests in \texttt{.pvt} files. The following
+% normalization takes place:
+% \begin{itemize}
+% \item Replacement of binary streams by the marker |[BINARY STREAM]|
+% \item Removal of blank lines
+% \end{itemize}
+%
+% Testing on the result of typesetting \texttt{.pvt} files is carried out using
+% only the standard engine, as aspects of PDF files are not identical between
+% engines. To allow platform-independence, PDF-based tests must use only
+% Type1 or OpenType fonts: Type3 fonts are system-dependent.
+%
% \section{Release-focussed features}
%
% \subsection{Automatic tagging}
@@ -1222,7 +1233,6 @@
% \label{fig:PDF}
% \end{figure}
%
-%
% \section{Lua interfaces}
%
% Whilst for the majority of users the simple variable-based control methods
@@ -1247,7 +1257,6 @@
% \var{halt} & Boolean \\
% \var{help} & Boolean \\
% \var{names} & Table \\
-% \var{pdf} & Boolean \\
% \var{quiet} & Boolean \\
% \var{rerun} & Boolean \\
% \var{testfiledir} & Table \\
@@ -1443,6 +1452,24 @@
% |target| in this table is ignored.
% \end{function}
%
+% \subsection{Customising the target list}
+%
+% The targets known to \pkg{l3build} are stored in the global table
+% |target_list|. Each entry should have at least a |func|, pointing to the
+% function used to implement the target. This function will receive the
+% list of names given at the command line as a table argument.
+% In most cases, targets will also have a |desc|, used to construct |help()|
+% automatically. In addition, the following may also be used:
+% \begin{itemize}
+% \item |bundle_func| A variant of |func| used when at the top level of
+% a bundle
+% \item |bundle_target| A boolean to specify that when passing the target
+% name in a bundle, it should have |bundle| prepended.
+% \item |pre| A function executed before the main function, and receiving
+% the |names| as an argument; this allows checking of the |name| data
+% without impact on the main |func|.
+% \end{itemize}
+%
% \subsection{Customising the manifest file}
% \label{sec:manifest}
%
@@ -1815,7 +1842,6 @@
\SEPARATOR
\begingroup
\let\TYPE\LONGTYPEOUT
-
}
\protected\long\def\ENDTEST{%
\endgroup
@@ -1899,6 +1925,25 @@
\fi
% \end{macrocode}
%
+% Disable compression in PDF output.
+% \begin{macrocode}
+\ifnum 0%
+ \ifx\pdfoutput\@undefined\else\ifnum\pdfoutput>0 1\fi\fi
+ \ifx\outputmode\@undefined\else\ifnum\outputmode>0 1\fi\fi
+ >0 %
+ \ifx\pdfvariable\@undefined
+ \pdfcompresslevel=0 %
+ \pdfobjcompresslevel=0 %
+ \else
+ \pdfvariable compresslevel=0 %
+ \pdfvariable objcompresslevel=0 %
+ \fi
+\else
+ \special{dvipdfmx:config z 0}% Compress level
+ \special{dvipdfmx:config C 0x40}% Object compression
+\fi
+% \end{macrocode}
+%
% Finish up.
% \begin{macrocode}
\reset@catcodes