From ab1456ac100fab623d9d9e62c3ba878930d944aa Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Fri, 8 Feb 2019 23:00:59 +0000 Subject: l3build (7feb19) git-svn-id: svn://tug.org/texlive/trunk@49981 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/source/latex/l3build/l3build.dtx | 102 +++++++++++++++++---- 1 file changed, 82 insertions(+), 20 deletions(-) (limited to 'Master/texmf-dist/source/latex/l3build') diff --git a/Master/texmf-dist/source/latex/l3build/l3build.dtx b/Master/texmf-dist/source/latex/l3build/l3build.dtx index b62f2e42ece..d0bd63173a6 100644 --- a/Master/texmf-dist/source/latex/l3build/l3build.dtx +++ b/Master/texmf-dist/source/latex/l3build/l3build.dtx @@ -86,7 +86,7 @@ \luavarset{docfiles} {\{\}}{Files which are part of the documentation but should not be typeset} \luavarset{dynamicfiles} {\{ \}}{Secondary files to cleared before each test is run} \luavarset{excludefiles} {\{"*\string~"\}}{Files to ignore entirely (default for Emacs backup files)} -\luavarset{installfiles} {\{"*.sty","*.cls"\}}{Files to install to the \texttt{text} area of the \texttt{texmf} tree} +\luavarset{installfiles} {\{"*.sty","*.cls"\}}{Files to install to the \texttt{tex} area of the \texttt{texmf} tree} \luavarset{makeindexfiles} {\{"*.ist"\}}{MakeIndex files to be included in a TDS-style zip} \luavarset{scriptfiles} {\{ \}}{Files to install to the \texttt{scripts} area of the \texttt{texmf} tree} \luavarset{scriptmanfiles} {\{ \}}{Files to install to the \texttt{doc/man} area of the \texttt{texmf} tree} @@ -110,6 +110,7 @@ \luavarset{checkengines}{\{"pdftex", "xetex", "luatex"\}}{Engines to check with \texttt{check} by default} \luavarset{stdengine} {"pdftex"}{Engine to generate \texttt{.tlg} file from} \luavarset{checkformat} {"latex"} {Format to use for tests} +\luavarset{specialformats}{\meta{table}} {Non-standard engine/format combinations} \luavarseparator \luavarset{checkconfigs}{\{\}}{Configurations to use for tests} \luavarseparator @@ -226,7 +227,7 @@ % }^^A % } % -% \date{Released 2018-12-18} +% \date{Released 2019-02-06} % % \maketitle % \tableofcontents @@ -317,14 +318,16 @@ % \item check \meta{name(s)} % \item clean % \item ctan +% \item doc % \item doc \meta{name(s)} % \item install % \item manifest % \item save \meta{name(s)} -% \item tag +% \item tag \meta{tag} % \item uninstall % \item unpack % \item upload +% \item upload \meta{tag} % \end{itemize} % These commands are described below. % @@ -332,11 +335,14 @@ % \begin{itemize} % \item |--config| (|-c|) Configuration(s) to use for testing % \item |--date| Date to use when tagging data +% \item |--debug| Runs the target in debug mode (not supported by all targets) % \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 |--email| Sets the email address for CTAN upload % \item |--engine| (|-e|) Sets the engine to use for testing % \item |--epoch| Sets the epoch for typesetting and testing +% \item |--file| (|-F|) Take the upload announcement from the given file % \item |--first| Name of the first test to run % \item |--force| (|-f|) Force checks to run even if sanity % checks fail, \emph{e.g.}~when |--engine| is not given in @@ -347,6 +353,7 @@ % 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 |--message| (|-m|) Text for upload announcement % \item |--quiet| (|-q|) Suppresses output from unpacking % \item |--rerun| Run tests without unpacking/set up % \item |--shuffle| Shuffle the order in which tests run @@ -531,14 +538,15 @@ % % \begin{buildcmd}{tag} % 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). 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. +% to automatically update the `release tag' (or package version) and date. +% The tag is given as the command line option and the date using +% |--date| (|-d|). If not given, the date will default to the current date in +% ISO format (YYYY-MM-DD). If no option is given (i.e., no tag specified) the tag +% is passed through as |nil| to allow setting the tag programmatically. +% +% The standard setup has no search pattern defined for this target and so no action +% will be taken \emph{unless} tag substitution is set up by defining the Lua function +% |update_tag()|. See Section~\ref{sec:tagging} for full details on this feature. % \end{buildcmd} % % \begin{buildcmd}{unpack} @@ -758,6 +766,32 @@ % A series of example layouts and matching |build.lua| files are available from % \url{https://github.com/latex3/l3build/tree/master/examples}. % +% \subsection{Non-standard formats/binaries} +% +% The standard approach used by \pkg{l3build} is to use a combination +% of \var{engine} and \var{checkformat} to generate the \emph{binary} and +% \emph{format} combination used for tests. For example, when |pdftex| is +% the \var{engine} and |latex| is the \var{checkformat}, the system call +% used is +% \begin{verbatim} +% pdftex --fmt=pdflatex +% \end{verbatim} +% \emph{i.e.}~the binary names is the same as the \var{engine}, and the format +% is a simple substitution of the \var{checkformat} into \var{engine}, replacing +% |tex|. +% +% For more complex set ups, \var{specialformats} should be used. This is a +% table with one entry per \var{checkformat}. Each entry is itself a table, +% and these contain a list of engines and settings for |binary|, |format| +% and |options|. For example, for Con\TeX{}t and appropriate set up is +% \begin{verbatim} +% specialformats.context = { +% luatex = {binary = "context", format = ""}, +% pdftex = {binary = "texexec", format = ""}, +% xetex = {binary = "texexec", format = "", options = "--xetex"} +% } +% \end{verbatim} +% % \subsection{Output normalisation} % \label{sec:norm} % @@ -1186,10 +1220,10 @@ % 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 +% \item file name +% \item full content of the file +% \item tag name +% \item tag date % \end{enumerate} % The |update_tag()| function should return the (modified) contents % for writing to disk. @@ -1222,8 +1256,9 @@ % % To allow more complex tasks to take place, a hook |tag_hook()| is also % available. It will receive the tag name and date as arguments, and -% may be used to carry out arbitrary tasks during tagging (for example, -% setting a version control tag for an entire repository). +% may be used to carry out arbitrary tasks after the main tagging process. +% For example, this can be used to set a version control tag for an entire repository. +% % % \subsection{Typesetting documentation} % @@ -1295,8 +1330,34 @@ % 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. % +% \paragraph{Announcement text} +% It can be convenient not to include the announcement text within the |build.lua| file +% directly. The command line argument |--message| (|-m|) allows the announcement to be +% included as part of the |l3build| arguments, and |--file| (|-F|) reads the announcement +% from a specified file. Note that if the announcement text is omitted a `silent update' +% is performed; this should usually be performed for minor bug or documentation fixes only. +% +% \paragraph{Uploader details} +% The CTAN team use the uploader email address as a form of low-security sanity +% check that the upload is coming from a reputable source. Therefore, it is advisable not +% to store this information within a public |build.lua| file. It can be set on the command +% line with the |--email| option to \texttt{l3build}; alternatively, a private +% configuration file could be used to add this information at upload time. +% +% \paragraph{The \texttt{update} field} +% In most scenarios the |update| field does not need to be explicitly set. By default +% \pkg{l3build} assumes that the package being uploaded already exists on CTAN +% (|update=true|). If it does not, this is caught in the validation process before +% uploading and automatically corrected. If you set |update| explicitly this will be passed +% directly to CTAN in all circumstances, leading to errors if you attempt to update a +% non-existing package or if you attempt to upload a new package with the same name as a +% pre-existing one. +% +% If you have have difficulty with the upload process, add the option |--debug| to divert +% the request from CTAN to a service that redirects the input back again so it can be examined. % % \begin{table}[p] % \def\YES{\textbullet} @@ -1307,6 +1368,7 @@ % \toprule % Field & Req. & Multi & Description \\ % \midrule +% \texttt{announcement} & \YES & & Announcement text \\ % \texttt{author } & \YES & & Author name (semicolon-separated for multiple) \\ % \texttt{ctanPath } & \YES & & CTAN path \\ % \texttt{email } & \YES & & Email address of uploader \\ @@ -1316,7 +1378,6 @@ % \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 \\ @@ -1342,8 +1403,6 @@ % 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} @@ -1373,13 +1432,16 @@ % \var{date} & String \\ % \var{dirty} & Boolean \\ % \var{dry-run} & Boolean \\ +% \var{email} & String \\ % \var{engine} & Table \\ % \var{epoch} & String \\ +% \var{file} & string \\ % \var{first} & Boolean \\ % \var{force} & Boolean \\ % \var{full} & Boolean \\ % \var{halt-on-error} & Boolean \\ % \var{help} & Boolean \\ +% \var{message} & string \\ % \var{names} & Table \\ % \var{quiet} & Boolean \\ % \var{rerun} & Boolean \\ -- cgit v1.2.3