xtask 0.5.0
xtask: ^0.5.0 copied to clipboard
A task runner whose tasks are data. The graph lives in xtask.yaml; a job body is either an external process (argv, never a shell) or a verb the project implements in Dart.
Changelog #
0.5.0 #
Added #
- The installed
xtaskruns a project's verbs: in a repository with an entry point of its own, it hands the run to it and answers with its exit code. The run starts where you stand, a package never resolved getsdart pub getfirst — which Ctrl-C orSIGTERMstops, answering130or143— andXTASK_HAND_OVERSstops a loop at eight. Your own entry point. entry:names that entry point where it is notbin/xtask.dart— a tools package'stools/bin/xtask.dart, say.--validatesays when the file is missing, and--check-cireads a step running it asxtask.--graph [<name>]draws what a gate set or task pulls in, as a tree, without running anything; with no name, every gate set and then what none reaches.--report <file>writes the run as JSON,version: 1, as it goes: each task's result, seconds, code and why, andcomplete: falsewhere the run was killed. A run as JSON.unchanged: <set>fails a task that changed the files a set reaches, naming each — compared byte for byte, not asked of git.unchanged.containing: [paths]on a glob set keeps the members that hold every path:include: [packages/*]withcontaining: [test]is the packages with a suite.containing.platforms: [linux|macos|windows]: on another machine the task is skipped,linux only, and what needs it runs as though it had passed.platforms.secret-env: [NAMES]prints those variables' values as***in everything the engine writes, and on GitHub Actions hands each to::add-mask::. What a body prints itself is not filtered. Secrets.env-unset: [names]takes variables away from a task's body, andenv-paths: {NAME: path}sets them to paths from the root, absolute and in the machine's separators.env-unset,env-paths.- On a terminal the summary, the task headings and
--graphare coloured, byTERM,NO_COLORandFORCE_COLOR; a pipe gets the bytes it got before. A Windows console without ANSI gets ASCII marks. Colour, and ASCII. - For an entry point:
findRootandgateMembers, which answer wherextask.yamlis and what a gate set holds without a second engine, andXtaskFormatException, which they throw where--gate-membersrefuses.
Changed #
- A run ends with one tree instead of two blocks: a row per task with its mark
(
✓✗⊘⏹·), its time and its code or reason, aneach:task's members under it.--report,--names,--gate-membersand the GitHub markers are unchanged. - The package lives in
packages/xtaskof a workspace repository, andrepository:points there.
Fixed #
- Ctrl-C or
SIGTERMno longer leaves what the run started running: each process is sentSIGTERMand, after a grace,SIGKILL, and the run answers130or143. On Windows, Ctrl-C only. Ctrl-C, and SIGTERM.
0.4.0 #
Added #
--only <set>=<pattern>,…narrows a set for one run: everyeach:andall:in the plan that names it gets only the members a pattern matches, and--dry-runtakes it too. A set the file has not got, a set nothing in the plan expands, and a pattern matching no member are each a2. The summary saysover 2 of 17 members, and--check-cireports a step that runs a gate set narrowed.alone: true: under-jthe run waits for what it has started, runs the task, and starts nothing else until it has ended.--validaterefuses it besideexclusive:,serial:orinterruptible:, and on a task with no body.- For verbs:
context.tee(argv, workingDirectory:, timeout:), which iscapturewith the output shown as it arrives. A hand-builtVerbContextgives it throughrelay:. - For verbs:
context.file(path)andcontext.directory(path), a path from the repository root written with/, ending the task with2when it climbs out of the root or leads out through a link. --completion bash|zsh|fishprints a completion script, which reads task, gate set and set names from--nameswhen TAB is pressed.- A name that is not a task is answered with the near ones —
did you mean `check`?— or withxtask --list.
Fixed #
- An argument holding
%is refused for a batch file, as&and^are:cmd.exeexpands%VAR%on the command line before the file sees it. context.outhands on a line written with\r\nwithout its\r.
0.3.0 #
Breaking #
VerbContextrequiresroot:and is no longerconst. Only code that builds a context itself — a verb's tests — is affected.ExitCode.continuationNoticeis replaced by the top-levelcontinuationNotice(body:, continuation:).
Added #
--check-schema <path>answers 2 when a committed schema is not the one this engine emits.--check-cinames the tasks in a gate set that no job reaches.- For verbs:
context.root;context.capture(argv, workingDirectory:, timeout:), which starts a program ascontext.rundoes and returns its exit code and output;context.which(name, workingDirectory:); andcontext.out, aStringSinkoverlog.
Changed #
- A failed
then:names the task that finished and the continuation that failed, instead of always saying "the upload took place".
Fixed #
--check-cireadsdefaults: run: working-directory:on the job and the workflow. It reports a${{ … }}working directory instead of reading it as the root, and a${{ … }}continue-on-error:instead of reading it as false.- A blank name (
" ") is refused like an empty one. - The schema refuses what the parser refuses:
all:witheach:,timeout:orinterruptible: truewithoutrun:, a blank entry inneeds:,then:,gate:orexclusive:, and a blankdo:. - The README described
context.workingDirectoryas the repository root. It is where the task runs; a set's members are relative tocontext.root.
0.2.0 #
Breaking #
- Gate sets are declared with
gates: [...]and joined withgate: [...].collects:is gone. argv-from:isall:, and$allgoes where it is written.--parallelis-j <n>;-j autois the processor count, at most 8.- An absolute path, or one through
.., is refused inin:, a set member and aremoveargument. - A name containing a line break is refused.
removelists each path once, sorted.
Added #
values:sets,produced-by:on glob sets,$eachin arguments,exclusive:,interruptible:andserial:.- For verbs:
context.memberandcontext.run(argv, workingDirectory:).
Fixed #
- Seven paths that ended the process at 255 answer a documented code.
do: removerefuses its own directory ('',.,./) and deletes relative to where the task runs, not the root.x needs y,y then z,z needs xis no longer refused as a cycle.--check-cireads a step with the command line's own parser instead of guessing at shell. A step under anotherxtask.yamlor withcontinue-on-error: truedoes not count; a multi-line script, a${{ … }}expression and xtask outside command position are reported; the# xtask: not a gate — reasonmarker requires the reason;xtask.exeand.\xtaskare recognised.{lib,}is refused instead of crashing at match time.- A closed stdout (
| head -1) no longer ends the run. - The exit code no longer depends on scheduling.
--dry-runprints the resolved argv, directory andremovepaths.--validaterefuses everything a run would.- Every contradiction in a task is reported in one refusal.
- A repository-relative program is resolved from where the body runs.
- A set is read when its task is about to run, not at planning.
- YAML aliases, merge keys and invisible whitespace in an indent are refused.
- A killed task no longer leaves the run waiting on a grandchild.
Performance #
- Planning is linear in a chain's length, a glob prunes the walk, and a
removeof several patterns reads the tree once.
0.1.0 #
First release.
xtask.yamland--validate, with errors that name the line.- The graph:
needs,then, cycle detection, run-once, declared order, and five exit codes. - Bodies:
runas argv,dofor a verb the project registers,args,argv-from,each,in,env. Executables are resolved throughPATHandPATHEXT, and Windows batch shims are handled. env-required, checked before a body runs.- Sets: lists and globs with exclusions, in a deterministic order. A set that expands to nothing is an error.
- Gate sets through
collects:,--list,--gate-members, and folded log sections on a host that supports them. - The built-in
removeverb. --dry-run,--emit-schema,--why,--check-ci,--keep-goingand--parallel.- Per-task timings, printed after the last section.