Skip to content
Weaverv0.5.0

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.

A [build.<name>] section records a whole wv build command, so as not to repeat its options:

weaver.toml
[build.app]
main = "src" # a folder, a file, or a list of files
out = "bin/app"
[build.app-dev]
main = "src"
out = "bin/app-dev"
dev = true # unoptimized, with debug information
Terminal window
wv build app-dev # that one
wv build # all of them
wv run app --help # build it, then run it, --help going to it

A 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.

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.IoError
import weaver.{Fs}
/// Builds the program, if a source changed since.
@default
pub 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:

Terminal window
wv add weft/wake

wv 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.

Terminal window
wv wake -l
Tasks:
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.
Terminal window
wv wake # the default task, marked *
wv wake check # lint and test first, then check
wv wake test parser # a task's arguments follow it
wv wake build test # several, in order
wv wake -h test # a task's whole help, its arguments and needs
wv wake -v check # each task's start, end and time
wv 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 adopts Parse. A default value makes one optional.
  • Needs. @needs([a, b]) runs a and b before 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, and wv wake exits with code
    1. A cycle between needs is reported before anything runs.
  • Names. @default marks the task run without a name, @alias("b") gives another name. A camelCase function is called in kebab case, runAll as run-all, and pub namespace Docker { … } groups tasks called docker:image.
  • Where. wv wake looks for the Wakefile in the current directory, then up to the project’s root, and runs the tasks there. A larger one can be a Wakefile/ directory of .wft files.
  • 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 build leaves it out of the project’s programs.
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.