From 25f0a34ef212818e30ee07866877d0ea7985c691 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Tue, 18 Dec 2018 23:33:00 +0000 Subject: l3build (18dec18) git-svn-id: svn://tug.org/texlive/trunk@49450 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/l3build/CHANGELOG.md | 10 +- Master/texmf-dist/doc/latex/l3build/README.md | 2 +- Master/texmf-dist/doc/latex/l3build/l3build.pdf | Bin 674222 -> 688963 bytes Master/texmf-dist/doc/man/man1/l3build.1 | 2 +- Master/texmf-dist/doc/man/man1/l3build.man1.pdf | Bin 15148 -> 15147 bytes Master/texmf-dist/scripts/l3build/l3build-help.lua | 2 +- .../texmf-dist/scripts/l3build/l3build-stdmain.lua | 9 +- .../texmf-dist/scripts/l3build/l3build-upload.lua | 237 +++++++++++++++++++++ .../scripts/l3build/l3build-variables.lua | 4 + Master/texmf-dist/scripts/l3build/l3build.lua | 9 +- Master/texmf-dist/source/latex/l3build/l3build.dtx | 213 +++++++++++++----- 11 files changed, 419 insertions(+), 69 deletions(-) create mode 100644 Master/texmf-dist/scripts/l3build/l3build-upload.lua (limited to 'Master') diff --git a/Master/texmf-dist/doc/latex/l3build/CHANGELOG.md b/Master/texmf-dist/doc/latex/l3build/CHANGELOG.md index 1b64ee6700d..a2c27f00465 100644 --- a/Master/texmf-dist/doc/latex/l3build/CHANGELOG.md +++ b/Master/texmf-dist/doc/latex/l3build/CHANGELOG.md @@ -7,6 +7,13 @@ this project uses date-based 'snapshot' version identifiers. ## [Unreleased] +## [2018-12-18] + +### Changed + +- Add new `upload` target which uses `curl` with the CTAN API to send a package + for release (see #1) + ## [2018-11-08] ### Changed @@ -199,7 +206,8 @@ this project uses date-based 'snapshot' version identifiers. - Rationalise short option names: removed `-d`, `-E`, `-r` - Target `cmdcheck`: specific to LaTeX3 kernel work -[Unreleased]: https://github.com/latex3/l3build/compare/2018-11-08...HEAD +[Unreleased]: https://github.com/latex3/l3build/compare/2018-12-18...HEAD +[2018-12-18]: https://github.com/latex3/l3build/compare/2018-11-08...2018-12-18 [2018-11-08]: https://github.com/latex3/l3build/compare/2018-10-30...2018-11-08 [2018-10-30]: https://github.com/latex3/l3build/compare/2018-10-25...2018-10-30 [2018-10-25]: https://github.com/latex3/l3build/compare/2018-09-26...2018-10-25 diff --git a/Master/texmf-dist/doc/latex/l3build/README.md b/Master/texmf-dist/doc/latex/l3build/README.md index 9fb833e65f3..2d88eb45457 100644 --- a/Master/texmf-dist/doc/latex/l3build/README.md +++ b/Master/texmf-dist/doc/latex/l3build/README.md @@ -1,7 +1,7 @@ l3build: a testing and building system for LaTeX3 ================================================= -Release 2018-11-08 +Release 2018-12-18 Overview -------- diff --git a/Master/texmf-dist/doc/latex/l3build/l3build.pdf b/Master/texmf-dist/doc/latex/l3build/l3build.pdf index c428631c5af..b26e510dd0e 100644 Binary files a/Master/texmf-dist/doc/latex/l3build/l3build.pdf and b/Master/texmf-dist/doc/latex/l3build/l3build.pdf differ diff --git a/Master/texmf-dist/doc/man/man1/l3build.1 b/Master/texmf-dist/doc/man/man1/l3build.1 index bdd309db3aa..70c51b20544 100644 --- a/Master/texmf-dist/doc/man/man1/l3build.1 +++ b/Master/texmf-dist/doc/man/man1/l3build.1 @@ -1,4 +1,4 @@ -.TH l3build 1 "2018-11-08" +.TH l3build 1 "2018-12-18" .SH NAME l3build \- Checking and building packages .SH SYNOPSIS diff --git a/Master/texmf-dist/doc/man/man1/l3build.man1.pdf b/Master/texmf-dist/doc/man/man1/l3build.man1.pdf index fe10c4b1522..4fbe5f737a4 100644 Binary files a/Master/texmf-dist/doc/man/man1/l3build.man1.pdf and b/Master/texmf-dist/doc/man/man1/l3build.man1.pdf differ diff --git a/Master/texmf-dist/scripts/l3build/l3build-help.lua b/Master/texmf-dist/scripts/l3build/l3build-help.lua index 18caf87daae..8c3877595fc 100644 --- a/Master/texmf-dist/scripts/l3build/l3build-help.lua +++ b/Master/texmf-dist/scripts/l3build/l3build-help.lua @@ -58,7 +58,7 @@ function help() end print("usage: " .. scriptname .. " [] []") print("") - print("The most commonly used l3build commands are:") + print("Valid commands are:") local longest,t = setup_list(target_list) for _,k in ipairs(t) do local target = target_list[k] diff --git a/Master/texmf-dist/scripts/l3build/l3build-stdmain.lua b/Master/texmf-dist/scripts/l3build/l3build-stdmain.lua index 26a229ce31c..f2d8797c830 100644 --- a/Master/texmf-dist/scripts/l3build/l3build-stdmain.lua +++ b/Master/texmf-dist/scripts/l3build/l3build-stdmain.lua @@ -58,7 +58,7 @@ target_list = return 0 end }, - bundlectan = + bundlectan = { func = bundlectan }, @@ -138,7 +138,12 @@ target_list = bundle_target = true, desc = "Unpacks the source files into the build tree", func = unpack - } + }, + upload = + { + desc = "Send archive to CTAN for public release", + func = upload + }, } -- diff --git a/Master/texmf-dist/scripts/l3build/l3build-upload.lua b/Master/texmf-dist/scripts/l3build/l3build-upload.lua new file mode 100644 index 00000000000..68692b0af4c --- /dev/null +++ b/Master/texmf-dist/scripts/l3build/l3build-upload.lua @@ -0,0 +1,237 @@ +--[[ + +File l3build-upload.lua Copyright (C) 2018 The LaTeX3 Project + +It may be distributed and/or modified under the conditions of the +LaTeX Project Public License (LPPL), either version 1.3c of this +license or (at your option) any later version. The latest version +of this license is in the file + + http://www.latex-project.org/lppl.txt + +This file is part of the "l3build bundle" (The Work in LPPL) +and all files in that bundle must be distributed together. + +----------------------------------------------------------------------- + +The development version of the bundle can be found at + + https://github.com/latex3/l3build + +for those people who are interested. + +--]] + + +-- UPLOAD() +-- +-- takes a package configuration table and an optional boolean +-- +-- if the upload parameter is not supplied or is not true, only package validation +-- is used, if upload is true then package upload will be attempted if validation +-- succeeds. + +-- fields are given as a string, or optionally for fields allowing multiple +-- values, as a table of strings. + +-- Mandatory fields are checked in Lua +-- Maximum string lengths are checked. + +-- Currently string values are not checked, eg licence names, or URL syntax. + +-- The input form could be used to construct a post body but +-- luasec is not included in texlua. Instead an external program is used to post. +-- As Windows (since April 2018) includes curl now use curl. +-- A version using ctan-o-mat is available in the ctan-post github repo. + +-- the main interface is +-- upload() +-- with a configuration table `uploadconfig` + + +local curl_debug = curl_debug or false -- to disable posting +-- For now, this is undocumented. + +local ctanupload = ctanupload or "ask" +-- if ctanupload is nil or false, only validation is attempted +-- if ctanupload is true the ctan upload URL will be used after validation +-- if upload is anything else, the user will be prompted whether to upload. +-- For now, this is undocumented. I think I would prefer to keep it always set to ask for the time being. + +function upload() + + local uploadfile = ctanzip..".zip" + + -- try a sensible default for the package name: + uploadconfig.pkg = uploadconfig.pkg or ctanpkg or nil + + -- start building the curl command: + ctan_post = curlexe .. " " + + -- build up the curl command field-by-field: + + -- field max desc mandatory multi + -- ---------------------------------------------------------------------------------------------------- + ctan_field("announcement", uploadconfig.announcement, 8192, "Announcement", false, false ) + ctan_field("author", uploadconfig.author, 128, "Author name", true, false ) + ctan_field("bugtracker", uploadconfig.bugtracker, 255, "URL(s) of bug tracker", false, true ) + ctan_field("ctanPath", uploadconfig.ctanPath, 255, "CTAN path", true, false ) + ctan_field("description", uploadconfig.description, 4096, "Short description of package", false, false ) + ctan_field("development", uploadconfig.development, 255, "URL(s) of development channels", false, true ) + ctan_field("email", uploadconfig.email, 255, "Email of uploader", true, false ) + ctan_field("home", uploadconfig.home, 255, "URL(s) of home page", false, true ) + ctan_field("license", uploadconfig.license, 2048, "Package license(s)", true, true ) + ctan_field("note", uploadconfig.note, 4096, "Internal note to ctan", false, false ) + ctan_field("pkg", uploadconfig.pkg, 32, "Package name", true, false ) + ctan_field("repository", uploadconfig.repository, 255, "URL(s) of source repositories", false, true ) + ctan_field("summary", uploadconfig.summary, 128, "One-line summary of package", true, false ) + ctan_field("support", uploadconfig.support, 255, "URL(s) of support channels", false, true ) + ctan_field("topic", uploadconfig.topic, 1024, "Topic(s)", false, true ) + ctan_field("update", uploadconfig.update, 8, "Boolean: true=update, false=new pkg", false, false ) + ctan_field("uploader", uploadconfig.uploader, 255, "Name of uploader", true, false ) + ctan_field("version", uploadconfig.version, 32, "Package version", true, false ) + + -- finish constructing the curl command: + ctan_post = ctan_post .. " --form 'file=@" .. tostring(uploadfile) .. ";filename=" .. tostring(uploadfile) .. "'" + ctan_post = ctan_post .. " https://ctan.org/submit/" + + -- avoid lower level error from post command if zip file missing + local zip=io.open(trim_space(tostring(uploadfile)),"r") + if zip~=nil then + io.close(zip) + else + error("Missing zip file '" .. tostring(uploadfile) .. "'") + end + + -- call post command to validate the upload at CTAN's validate URL + local exit_status=0 + local fp_return="" + + -- use popen not execute so get the return body local exit_status=os.execute(ctan_post .. "validate") + if (curl_debug==false) then + local fp = assert(io.popen(ctan_post .. "validate", 'r')) + fp_return = assert(fp:read('*a')) + fp:close() + else + fp_return="WARNING: curl_debug==true: posting disabled" + print(ctan_post) + end + if string.match(fp_return,"WARNING") or string.match(fp_return,"ERROR") then + exit_status=1 + end + + -- if upload requested and validation succeeded repost to the upload URL + if (exit_status==0 or exit_status==nil) then + if (ctanupload ~=nil and ctanupload ~=false and ctanupload ~= true) then + print("Validation successful, do you want to upload to CTAN? [y/n]" ) + local answer="" + io.write("> ") + io.flush() + answer=io.read() + if(string.lower(answer,1,1)=="y") then + ctanupload=true + end + end + if (ctanupload==true) then + local fp = assert(io.popen(ctan_post .. "upload", 'r')) + fp_return = assert(fp:read('*a')) + fp:close() +-- this is just html, could save to a file +-- or echo a cleaned up version + print('Response from CTAN:') + print(fp_return) + if string.match(fp_return,"WARNING") or string.match(fp_return,"ERROR") then + exit_status=1 + end + else + print("CTAN validation successful") + end + else + error("Warnings from CTAN package validation:\n" .. fp_return) + end + return exit_status +end + + +function trim_space(s) + return (s:gsub("^%s*(.-)%s*$", "%1")) +end + + +function ctan_field(fname,fvalue,max,desc,mandatory,multi) + if (type(fvalue)=="table" and multi==true) then + for i, v in pairs(fvalue) do + ctan_single_field(fname,v,max,desc,mandatory and i==1) + end + else + ctan_single_field(fname,fvalue,max,desc,mandatory) + end +end + + +function ctan_single_field(fname,fvalue,max,desc,mandatory) + print('ctan-post: ' .. fname .. ' ' ..tostring(fvalue or '??')) + if ((fvalue==nil and mandatory) or (fvalue == 'ask')) then + if (max < 256) then + fvalue=input_single_line_field(fname) + else + fvalue=input_multi_line_field(fname) + end + end + if (fvalue==nil or type(fvalue)~="table") then + local vs=trim_space(tostring(fvalue)) + if (mandatory==true and (fvalue == nil or vs=="")) then + error("The field " .. fname .. " must contain " .. desc) + end + if (fvalue ~=nil and string.len(vs) > 0) then + if (max > 0 and string.len(vs) > max) then + error("The field " .. fname .. " is longer than " .. max) + end + vs = vs:gsub('"','\\"') + vs = vs:gsub('`','\\`') + ctan_post=ctan_post .." --form " .. fname .. '="' .. vs .. '"' + end + else + error("The value of the field '" .. fname .."' must be a scalar not a table") + end +end + + +-- function for interactive multiline fields +function input_multi_line_field (name) + print("Enter " .. name .. " three or ctrl-D to stop") + + local field="" + + local answer_line + local return_count=0 + repeat + io.write("> ") + io.flush() + answer_line=io.read() + if answer_line=="" then + return_count=return_count+1 + else + for i=1,return_count,1 do + field = field .. "\n" + end + return_count=0 + if answer_line~=nil then + field = field .. "\n" .. answer_line + end + end + until (return_count==3 or answer_line==nil) + return field +end + +function input_single_line_field(name) + print("Enter " .. name ) + + local field="" + + io.write("> ") + io.flush() + field=io.read() + return field +end + diff --git a/Master/texmf-dist/scripts/l3build/l3build-variables.lua b/Master/texmf-dist/scripts/l3build/l3build-variables.lua index b3b999755dd..ad88aed00ce 100644 --- a/Master/texmf-dist/scripts/l3build/l3build-variables.lua +++ b/Master/texmf-dist/scripts/l3build/l3build-variables.lua @@ -185,3 +185,7 @@ tpfext = tpfext or ".tpf" -- Manifest options manifestfile = manifestfile or "MANIFEST.md" + +-- Upload settings +curlexe = curlexe or "curl" +uploadconfig = uploadconfig or {} diff --git a/Master/texmf-dist/scripts/l3build/l3build.lua b/Master/texmf-dist/scripts/l3build/l3build.lua index e40b8e6da74..3422f4d81a9 100755 --- a/Master/texmf-dist/scripts/l3build/l3build.lua +++ b/Master/texmf-dist/scripts/l3build/l3build.lua @@ -1,4 +1,4 @@ -#!/usr/bin/env texlua +#!/usr/bin/env texlua --[[ @@ -65,6 +65,7 @@ build_require("unpack") build_require("manifest") build_require("manifest-setup") build_require("tagging") +build_require("upload") build_require("stdmain") -- This has to come after stdmain(), @@ -96,7 +97,7 @@ end build_require("variables") -- Ensure that directories are 'space safe' -maindir = escapepath(maindir) +maindir = escapepath(maindir) docfiledir = escapepath(docfiledir) sourcefiledir = escapepath(sourcefiledir) supportdir = escapepath(supportdir) @@ -125,12 +126,12 @@ check_engines() -- -- Deal with multiple configs for tests -- - + -- When we have specific files to deal with, only use explicit configs -- (or just the std one) if options["names"] then checkconfigs = options["config"] or {stdconfig} -else +else checkconfigs = options["config"] or checkconfigs end 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} -- cgit v1.2.3