Builds and tasks
A project’s build has two levels. weaver.toml names the programs it
builds, with their options; a Wakefile holds the tasks around them,
generating, testing, packaging, written in Weaver and run by wv wake.
Named builds
Section titled “Named builds”A [build.<name>] section records a whole wv build command, so as not
to repeat its options:
[build.app]main = "src" # a folder, a file, or a list of filesout = "bin/app"
[build.app-dev]main = "src"out = "bin/app-dev"dev = true # unoptimized, with debug informationwv build app-dev # that onewv build # all of themwv run app --help # build it, then run it, --help going to itA build also takes kind ("bin", "lib" for a library callable from C,
or "extension"), g, sanitize, tzdata, pgo, target to compile
for another machine, target = "arm64-linux", and panic. Each build
compiles module by module, and keeps its objects: an edit recompiles only
the modules it changes.
Tasks: wake
Section titled “Tasks: wake”Everything else a project runs, generating code, the tests, a release, an
image, goes in a Wakefile.wft at its root. Its tasks are the public
functions of that file, and their /// comment is their help: there is no
other syntax to learn, and no shell quoting. The Wakefile is a Weaver
program, checked and compiled like any other.
// Wakefile.wft: the project's tasks, `wv wake -l` lists them.
import weft.wake.{run, needs, default, newer, RunError}import weaver.io.IoErrorimport weaver.{Fs}
/// Builds the program, if a source changed since.@defaultpub fn build() ! RunError { if newer("bin/app", ["src", "weaver.toml"]) { run("wv", "build", "app")! }}
/// Runs the tests, those matching pattern if given.@needs([build])pub fn test(pattern: String = "") ! RunError { if pattern.isEmpty() { run("wv", "test", "src")! } else { run("wv", "test", "-run", pattern, "src")! }}
/// Checks the formatting, then runs the tests.@needs([lint, test])pub fn check() { }
/// Says what wv fmt would change.pub fn lint() ! RunError = run("wv", "fmt", "-check", "src", "Wakefile.wft")!
/// Removes what the build wrote.pub fn clean() ! IoError = Fs.removeAll("bin")!The Wakefile imports weft/wake, a dependency of the project like any
other:
wv add weft/wakewv wake -init writes a Wakefile to start from, with a build and a
test task; outside a project, a weaver.toml that depends on
weft/wake too.
Running tasks
Section titled “Running tasks”wv wake -lTasks: build* Builds the program, if a source changed since. check Checks the formatting, then runs the tests. clean Removes what the build wrote. lint Says what wv fmt would change. test [pattern] Runs the tests, those matching pattern if given.wv wake # the default task, marked *wv wake check # lint and test first, then checkwv wake test parser # a task's arguments follow itwv wake build test # several, in orderwv wake -h test # a task's whole help, its arguments and needswv wake -v check # each task's start, end and timewv wake -t 10m check # cancelled beyond ten minutes- Arguments. A task’s parameters are read from the command line:
String,Int,Bool,Duration, or any type that adoptsParse. A default value makes one optional. - Needs.
@needs([a, b])runsaandbbefore the task, at the same time, and each only once in a run, however many tasks need it. A task that fails stops those that need it, andwv wakeexits with code- A cycle between needs is reported before anything runs.
- Names.
@defaultmarks the task run without a name,@alias("b")gives another name. A camelCase function is called in kebab case,runAllasrun-all, andpub namespace Docker { … }groups tasks calleddocker:image. - Where.
wv wakelooks for the Wakefile in the current directory, then up to the project’s root, and runs the tasks there. A larger one can be aWakefile/directory of.wftfiles. - Speed. The Wakefile is compiled once and kept in the cache: an
unchanged one starts in a fraction of a second, an edit recompiles only
its module.
wv buildleaves it out of the project’s programs.
What weft/wake provides
Section titled “What weft/wake provides”run(cmd, args…) |
runs a command on the terminal, and fails on a non-zero exit, saying which |
output(cmd, args…) |
runs it and gives its standard output, trimmed |
runIn(dir, …), runWith(env, …) |
in a directory, or with variables added |
newer(target, sources) |
whether target is missing, or older than one of its sources, folders walked |
together([job(…), …]) |
runs commands side by side, development servers, each line prefixed by its name, until one ends or Ctrl-C |
runNeeds([need(…)]) |
runs needs from a body, where a condition decides |
There are no make-style rules, where a recipe runs because its
prerequisites changed: newer lets a task decide, in code. The
registry documents its whole API, under
weft/wake.