diff options
author | Karl Berry <karl@freefriends.org> | 2018-12-18 23:33:00 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2018-12-18 23:33:00 +0000 |
commit | 25f0a34ef212818e30ee07866877d0ea7985c691 (patch) | |
tree | 662b89b9ef15c4f96048f02fb21320600954cd3a /Master/texmf-dist/source/latex | |
parent | 39e028ec9200b17474c8bc3c38aee237705bc2d7 (diff) |
l3build (18dec18)
git-svn-id: svn://tug.org/texlive/trunk@49450 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex')
-rw-r--r-- | Master/texmf-dist/source/latex/l3build/l3build.dtx | 213 |
1 files changed, 154 insertions, 59 deletions
diff --git a/Master/texmf-dist/source/latex/l3build/l3build.dtx b/Master/texmf-dist/source/latex/l3build/l3build.dtx index b4b13bf8331..b62f2e42ece 100644 --- a/Master/texmf-dist/source/latex/l3build/l3build.dtx +++ b/Master/texmf-dist/source/latex/l3build/l3build.dtx @@ -40,7 +40,7 @@ \makeatother \newenvironment{buildcmd}[1]{% \bigskip\par\noindent\hspace{-\parindent}% - \fbox{\ttfamily \textcolor[gray]{0.5}{\$} texlua build.lua #1}% + \fbox{\ttfamily \textcolor[gray]{0.5}{\$} l3build #1}% \nopagebreak\smallskip\nopagebreak\par\nopagebreak\noindent\ignorespaces } {} @@ -96,21 +96,10 @@ \luavarset{typesetdemofiles} {\{\}}{Files to typeset before the documentation for inclusion in main documentation files} \luavarset{typesetfiles} {\{"*.dtx"\}}{Files to typeset for documentation} \luavarset{typesetsuppfiles} {\{\}}{Files needed to support typesetting when \enquote{sandboxed}} -\luavarset{typesetsourcefiles}{\{\}}{Files to copy to unpacking when typesetting.} -\luavarset{unpackfiles} {\{"*.ins"\}}{Files to run to perform unpacking.} +\luavarset{typesetsourcefiles}{\{\}}{Files to copy to unpacking when typesetting} +\luavarset{unpackfiles} {\{"*.ins"\}}{Files to run to perform unpacking} \luavarset{unpacksuppfiles} {\{\}}{Files needed to support unpacking when \enquote{sandboxed}} \luavarseparator -\luavarset{bakext}{".bak"}{Extension of backup files} -\luavarset{dviext}{".dvi"}{Extension of DVI 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 @@ -124,14 +113,21 @@ \luavarseparator \luavarset{checkconfigs}{\{\}}{Configurations to use for tests} \luavarseparator -\luavarset{typesetexe}{"pdflatex"}{Executable for compiling \texttt{doc(s)}} -\luavarset{unpackexe} {"tex"} {Executable for running \texttt{unpack}} -\luavarset{zipexe} {"zip"} {Executable for creating archive with \texttt{ctan}} +\luavarset{typesetexe} {"pdflatex"} {Executable for compiling \texttt{doc(s)}} +\luavarset{unpackexe} {"tex"} {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} +\luavarset{curlexe} {"curl"} {Curl executable for \texttt{upload}} \luavarseparator -\luavarset{checkopts} {"-interaction=nonstopmode"}{Options based to engine when running checks.} -\luavarset{typesetopts}{"-interaction=nonstopmode"}{Options based to engine when typesetting.} -\luavarset{unpackopts} {""} {Options based to engine when unpacking.} -\luavarset{zipopts} {"-v -r -X"} {Options based to zip program.} +\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} \luavarseparator \luavarset{checksearch} {true}{Switch to search the system \texttt{texmf} for during checking} \luavarset{typesetsearch}{true}{Switch to search the system \texttt{texmf} for during typesetting} @@ -140,28 +136,35 @@ \luavarset{glossarystyle}{"gglo.ist"}{MakeIndex style file for glossary/changes creation} \luavarset{indexstyle} {"gind.ist"}{MakeIndex style for index creation} \luavarseparator -\luavarset{biberexe} {"biber"} {Biber executable} -\luavarset{biberopts} {""} {Biber options} -\luavarset{bibtexexe} {"bibtex8"} {\BibTeX{} executable} -\luavarset{bibtexopts} {"-W"} {\BibTeX{} options} -\luavarset{makeindexexe} {"makeindex"}{MakeIndex executable} -\luavarset{makeindexopts}{""} {MakeIndex options} -\luavarseparator \luavarset{forcecheckepoch}{"true"} {Force epoch when running tests} \luavarset{forcedocepoch} {"false"} {Force epoch when typesetting} \luavarseparator -\luavarset{asciiengines}{\{"pdftex"\}}{Engines which should log as sure ASCII} +\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{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 created for upload to CTAN} +\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} \luavarset{flatten} {true} {Switch to flatten any source structure when sending to CTAN} \luavarset{maxprintline}{79} {Length of line to use in log files} \luavarset{packtdszip} {false} {Switch to build a TDS-style zip file for CTAN} -\luavarset{typesetcmds} {""} {Instructions to be passed to \TeX{} when doing typesetting.} -\luavarset{typesetruns}{3} {Number of cycles of typesetting to carry out.} +\luavarset{typesetcmds} {""} {Instructions to be passed to \TeX{} when doing typesetting} +\luavarset{typesetruns}{3} {Number of cycles of typesetting to carry out} \luavarset{recordstatus}{false} {Switch to include error level from test runs in \texttt{.tlg} files} -\luavarset{manifestfile} {"MANIFEST.md"} {Filename to use for the manifest file.} +\luavarset{manifestfile} {"MANIFEST.md"} {Filename to use for the manifest file} +\luavarseparator +\luavarset{uploadconfig} {\meta{table}} {Metadata to describe the package for CTAN (see Table~\ref{tab:upload-setup})} +\luavarset{uploadconfig.pkg}{ctanpkg}{Name of the CTAN package} +\luavarseparator +\luavarset{bakext}{".bak"}{Extension of backup files} +\luavarset{dviext}{".dvi"}{Extension of DVI 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} } \allluavars @@ -223,7 +226,7 @@ % }^^A % } % -% \date{Released 2018-11-08} +% \date{Released 2018-12-18} % % \maketitle % \tableofcontents @@ -236,7 +239,10 @@ % % The \pkg{l3build} system is a Lua script for building \TeX{} packages, with particular emphasis on regression testing. % It is written in cross-platform Lua code, so can be used by any modern \TeX{} distribution with the |texlua| interpreter. -% A package for building with \pkg{l3build} can be 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.) +% Wrapper functions/binaries are distributed in the standard \TeX{} distributions so that the script can be called using +% \texttt{l3build} on the command line; run without arguments it prints a brief synopsis of its usage. +% +% 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.) % % Test files are written as standalone \TeX{} documents using the |regression-test.tex| setup file; documentation on writing these tests is discussed in Section~\ref{sec:writing-tests}. % @@ -301,31 +307,35 @@ % % \subsection{Main build commands} % -% In the working directory of a bundle or module, the following commands can be executed: +% In the working directory of a bundle or module, \pkg{l3build} is run by executing +% \begin{center} +% \texttt{l3build \meta{command} [\meta{option(s)}]} +% \end{center} +% where \texttt{\meta{command}} can be one of the following: % \begin{itemize}[noitemsep]\ttfamily % \item check % \item check \meta{name(s)} -% \item cmdcheck % \item clean % \item ctan % \item doc \meta{name(s)} % \item install +% \item manifest % \item save \meta{name(s)} % \item tag +% \item uninstall % \item unpack +% \item upload % \end{itemize} % These commands are described below. % % As well as these commands, the system recognises the options % \begin{itemize} -% \item |--config| (|-c|) Configuration(s) to use for testing -% \item |--date| Date to use when tagging -% data +% \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 -% testing +% \item |--engine| (|-e|) Sets the engine to use for testing % \item |--epoch| Sets the epoch for typesetting and testing % \item |--first| Name of the first test to run % \item |--force| (|-f|) Force checks to run even if sanity @@ -397,7 +407,7 @@ % % % \begin{buildcmd}{ctan} -% Creates an archive of the package and its documentation, suitable for uploading to CTAN +% Creates an archive of the package and its documentation, suitable for uploading to CTAN. % 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. % 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. % The archive therefore may contain two `views' of the package: @@ -520,13 +530,15 @@ % \end{buildcmd} % % \begin{buildcmd}{tag} -% Modifies the content of files specified by |tagfiles| to allow -% automatic updating of the release tag and date. The tag is given as a +% Modifies the contents of files specified by |tagfiles| using a search pattern +% to automatically update the `release tag' (or package version) and date. The tag is given as a % command line option, whilst the optional date should be passed using % |--date| (|-d|); if not given, the date will default to the current date in -% ISO format (YYYY-MM-DD). As detailed below, the standard set up has no search +% ISO format (YYYY-MM-DD). The standard set up has no search % pattern defined for this target and so no action will be taken \emph{unless} % tag substitution is set up. +% +% See Section~\ref{sec:tagging} for full details on this feature. % \end{buildcmd} % % \begin{buildcmd}{unpack} @@ -541,6 +553,15 @@ % By default this process allows files to be accessed in all standard |texmf| trees; this can be disabled by setting \var{unpacksearch} to |false|. % \end{buildcmd} % +% \begin{buildcmd}{upload} +% This target uses \texttt{curl} to upload the package zip file (created using \texttt{ctan}) to CTAN. +% To control the metadata used to upload the package, the \texttt{uploadconfig} table should be populated with a number of fields. +% These are documented in Table~\ref{tab:upload-setup}. +% Missing required fields will result in an interactive prompt for manual entry. +% +% See Section~\ref{sec:upload} for full details on this feature. +% \end{buildcmd} +% % \subsection{The \texttt{build.lua} file} % % The \texttt{build.lua} file used to control \pkg{l3build} is a simple Lua file @@ -606,7 +627,7 @@ % \label{fig:module} % \end{figure} % -% \subsection{Backward compatibly} +% \subsection{Backwards compatibility} % % Earlier releases of \pkg{l3build} required that the last line of % \texttt{build.lua} ran the main script, \emph{i.e.}~ that \texttt{build.lua} @@ -626,12 +647,14 @@ % % Note that in time support for loading \pkg{l3build} by calling the % \texttt{build.lua} script \emph{may} be removed: the recommended approach for -% new scripts is to run \pkg{l3build}. +% new scripts is to run \texttt{l3build}. % % \subsection{Variables} % % This section lists all variables defined in the |l3build.lua| script that are available for customisation. % +% \luavartypeset +% % \subsection{Interaction between tests} % % Tests are run in a single directory, so whilst they are may be isolated from @@ -641,8 +664,6 @@ % tests such that they do not use the same names for such files: this may lead % to variable outcomes depending on the order in which tests are run. % -% \luavartypeset -% % \subsection{Selective running of tests} % % The variables |includetests| and |excludetests| may be used to select which @@ -1145,28 +1166,36 @@ % \item Removal of blank lines % \end{itemize} % +% After this normalization takes place, the file can not usually be rendered +% properly. To check if the build system has produced a correct PDF, the +% pre-normalization PDF can be found in the \texttt{build} folder. +% % To allow platform-independence, PDF-based tests must use only Type~1 or % OpenType fonts: Type3 fonts are system-dependent. PDF files are % engine-specific, thus one |.tpf| file should be stored per engine to be % tested. % +% % \section{Release-focussed features} % % \subsection{Automatic tagging} +% \label{sec:tagging} % -% As detailed above, the |tag| target will automatically edit +% The |tag| target can automatically edit % source files to modify date and release tag. As standard, no automatic -% replacement takes place, but setting up a |updae_tag()| function -% will allow this to happen. This takes four arguments: -% \begin{itemize} +% replacement takes place, but setting up a |update_tag()| function +% will allow this to happen. This function takes four input arguments: +% \begin{enumerate}[nosep] % \item The file name % \item The full content of the file % \item The tag name % \item The tag date -% \end{itemize} -% and should return the (modified) contents for writing to disk. +% \end{enumerate} +% The |update_tag()| function should return the (modified) contents +% for writing to disk. % For example, the function used by |l3build| itself is % shown in Figure~\ref{fig:update-tag}. +% % \begin{figure} % \begin{lstlisting}[frame=single,language={[5.2]Lua},gobble = 6] % -- Detail how to set the version automatically @@ -1256,6 +1285,72 @@ % \label{fig:PDF} % \end{figure} % +% +% \subsection{Automated upload to CTAN} +% \label{sec:upload} +% +% The CTAN upload process is backed by an API, which \pkg{l3build} can use +% to send zip files for release. Along with the file, a variety of metadata +% must be specified about the package, including the version, license, and so on. +% A description of this metadata is outlined in Table~\ref{tab:upload-setup}, +% and a simple example of an extract from a \texttt{build.lua} file using this is shown +% in Figure~\ref{fig:uploadconfig}. +% Note that the \texttt{upload} target will \emph{not} execute the \texttt{ctan} target first. +% +% +% \begin{table}[p] +% \def\YES{\textbullet} +% \caption{Fields used in the \texttt{uploadconfig} setup table. The first section of fields are \emph{required} and if they are omitted the user will be interactively prompted for further input. Most commands take string input, but those that are indicated with `Multi' accept more than one entry using an array of strings.} +% \label{tab:upload-setup} +% \begin{minipage}{\linewidth} +% \begin{tabular}{@{}lccp{8cm}@{}} +% \toprule +% Field & Req. & Multi & Description \\ +% \midrule +% \texttt{author } & \YES & & Author name (semicolon-separated for multiple) \\ +% \texttt{ctanPath } & \YES & & CTAN path \\ +% \texttt{email } & \YES & & Email address of uploader \\ +% \texttt{license } & \YES & \YES & Package license(s)\footnote{See \url{https://ctan.org/license}} \\ +% \texttt{pkg } & \YES & & Package name \\ +% \texttt{summary } & \YES & & One-line summary \\ +% \texttt{uploader } & \YES & & Name of uploader \\ +% \texttt{version } & \YES & & Package version \\ +% \midrule +% \texttt{announcement} & & & Announcement text \\ +% \texttt{bugtracker } & & \YES & URL(s) of bug tracker \\ +% \texttt{description } & & & Short description/abstract \\ +% \texttt{development } & & \YES & URL(s) of development channels \\ +% \texttt{home } & & \YES & URL(s) of home page \\ +% \texttt{note } & & & Internal note to CTAN \\ +% \texttt{repository } & & \YES & URL(s) of source repositories \\ +% \texttt{support } & & \YES & URL(s) of support channels \\ +% \texttt{topic } & & \YES & Topic(s)\footnote{See \url{https://ctan.org/topics/highscore}} \\ +% \texttt{update } & & & Boolean \texttt{true} for an update, \texttt{false} for a new package \\ +% \bottomrule +% \end{tabular} +% \end{minipage} +% \end{table} +% +% +% \begin{figure}[p] +% \begin{lstlisting}[frame=single,language={[5.2]Lua},gobble = 6] +% uploadconfig = { +% pkg = "vertbars", +% version = "v1.0c", +% author = "Peter R Wilson; Will Robertson", +% license = "lppl1.3c", +% summary = "Mark vertical rules in margin of text", +% ctanPath = "/macros/latex/contrib/vertbars", +% repository = "https://github.com/wspr/herries-press/", +% uploader = "Will Robertson", +% email = [...], +% update = true, +% } +% \end{lstlisting} +% \caption{Example of \texttt{uploadconfig} from the \pkg{vertbars} package.} +% \label{fig:uploadconfig} +% \end{figure} +% % \section{Lua interfaces} % % Whilst for the majority of users the simple variable-based control methods @@ -1608,7 +1703,7 @@ % % Within a single group in the manifest listing, files can be matched against multiple variables. % For example, for |sourcefiles={*.dtx,*.ins}| the following (unsorted) file listing might result: -% \begin{itemize} +% \begin{itemize}[nosep] % \item foo.dtx % \item bar.dtx % \item foo.ins @@ -1833,7 +1928,7 @@ \begingroup % within the scope of this groups each line needs to end in % ! \catcode`\^^M\active % \gdef\SHOWFILE#1{% - \typeout{-------- #1 (start) ---------}% + \typeout{-------- #1 (start) ---------}% \IfFileExists{#1}% {\begingroup % \catcode`\^^M\active % @@ -1844,7 +1939,7 @@ \message{\@@input #1 }% \endgroup }% {\message{Not found}}% - \typeout{-------- #1 (end) -----------}% + \typeout{-------- #1 (end) -----------}% }% \endgroup % \end{macrocode} |