1 API

The following is the list of modules provided by this library. The stylesheet and the script that present this chapter in a browser are written beside it, as dokgen.css and dokgen.js; the manual says how a build points at them.


1.1 (maak archive)

The archive helpers a project needs around a release: make a tarball or a zip, unpack one, and see what is inside without unpacking it. They are thin, argument-list builders over the system tools rather than a second implementation of either format, so a tarball made here is the same tarball ‘tar’ would have made by hand.

Two families are exported, and each has a command builder next to the procedure that runs it:

tar-create, tar-extract, tar-list zip-create, zip-extract, zip-list

The ‘-argv’ builders return the argument list without running anything. They are what the procedures use, and they are exported because a task that wants to log, inspect or extend a command should not have to reimplement the flag order that the format requires.

Nothing here changes maak’s working directory permanently. ‘#:directory’ names the tree the files are read from, and the archive path is still resolved against the directory the task was started in.

One trap is worth knowing about, because tar reports it badly. Writing the archive inside the tree it is packing means tar reads a file that is still growing, and GNU tar aborts with "file changed as we read it" and exit code 1. A relative output name is therefore always written in the task directory, and a task that packs "." should not hand tar an absolute output path that points back into that tree.

1.1.1 Overview

  • tar-compression-option — Return the tar flags that select COMPRESSION, as a list.
  • tar-create — Write FILES as the tarball OUTPUT.
  • tar-create-argv — Return the argv that writes FILES as the tarball OUTPUT.
  • tar-extract — Unpack ARCHIVE, into DIRECTORY when one is named.
  • tar-extract-argv — Return the argv that unpacks ARCHIVE.
  • tar-list — Print the names of the files in ARCHIVE, without unpacking it.
  • tar-list-argv — Return the argv that prints the names of the files in ARCHIVE.
  • zip-create — Write FILES as the zip archive OUTPUT.
  • zip-create-argv — Return the argv that writes FILES as the zip archive OUTPUT.
  • zip-extract — Unpack ARCHIVE, into DIRECTORY when one is named.
  • zip-extract-argv — Return the argv that unpacks ARCHIVE.
  • zip-list — Print a listing of the files in ARCHIVE, without unpacking it.
  • zip-list-argv — Return the argv that lists the contents of ARCHIVE.

1.1.2 Procedures

Procedure: tar-compression-option compression

Return the tar flags that select COMPRESSION, as a list.

The names accepted are the ones a release actually uses: none, gz, bz2, xz and zstd. gzip, bzip2 and zst are accepted as aliases, so a caller can spell the compressor rather than its extension. A name that is not one of these raises a maak error instead of producing an archive tar would refuse to read.

Procedure: tar-create output files KEY: #:directory #:compression #:exclude #:verbose? #:allow-failure?

Write FILES as the tarball OUTPUT.

FILES is a list of paths relative to DIRECTORY, which defaults to the current directory. The compressor follows the output’s extension unless COMPRESSION names one, and EXCLUDE is a list of patterns to leave out.

OUTPUT is written in the directory the task started in, not in DIRECTORY, so packing the current directory does not put the growing tarball into the tree tar is reading. Passing an absolute OUTPUT that points inside the packed tree does, and tar then fails with "file changed as we read it".

(tar-create "maak-1.0.tar.gz" (list "src" "README.org" "LICENSE")
            #:exclude (list "*.o" "*.go"))
(tar-create "maak-1.0.tar.xz" (list ".") #:compression "xz")
Procedure: tar-create-argv output files KEY: #:directory #:compression #:exclude #:verbose?

Return the argv that writes FILES as the tarball OUTPUT.

FILES is a list of paths relative to DIRECTORY. With COMPRESSION auto, the output’s extension names the compressor (see tar-infer-compression); any other value is passed to tar-compression-option. EXCLUDE is a list of patterns, each passed as --exclude=PATTERN. With VERBOSE? the argv includes -v, so tar prints every file it adds.

Procedure: tar-extract archive KEY: #:directory #:strip-components #:verbose? #:allow-failure?

Unpack ARCHIVE, into DIRECTORY when one is named.

STRIP-COMPONENTS drops leading path components as the files are written; use 1 for the usual release tarball that wraps everything in one directory.

(tar-extract "maak-1.0.tar.gz" #:directory "build" #:strip-components 1)
Procedure: tar-extract-argv archive KEY: #:directory #:strip-components #:verbose?

Return the argv that unpacks ARCHIVE.

The compressor is detected from the archive itself, which is why no compression flag is needed here. DIRECTORY is where the files are written, and STRIP-COMPONENTS drops that many leading path components, which is how a release tarball with a single top-level directory is unpacked into the current one.

(tar-extract-argv "project-1.0.tar.gz" #:directory "build" #:strip-components 1)
Procedure: tar-list archive KEY: #:verbose? #:allow-failure?

Print the names of the files in ARCHIVE, without unpacking it.

With VERBOSE? tar prints the long listing instead of bare names.

Procedure: tar-list-argv archive KEY: #:verbose?

Return the argv that prints the names of the files in ARCHIVE.

Procedure: zip-create output files KEY: #:directory #:recursive? #:exclude #:junk-paths? #:quiet? #:verbose? #:allow-failure?

Write FILES as the zip archive OUTPUT.

FILES is a list of paths relative to DIRECTORY, which defaults to the current directory. The archive itself is written relative to the directory the task started in, so a ‘#:directory "dist"’ does not leave the zip inside dist.

(zip-create "maak-1.0.zip" (list "src" "README.org")
            #:exclude (list "*.go" "*.o"))
Procedure: zip-create-argv output files KEY: #:recursive? #:exclude #:junk-paths? #:quiet? #:verbose?

Return the argv that writes FILES as the zip archive OUTPUT.

The archive is created in the current directory; zip-create is the one that changes into #:directory for the duration of the command, because Info-ZIP has no -C-style option to name a tree. EXCLUDE is a list of patterns passed as -x, after the files, which is where zip expects them. #:junk-paths? stores bare file names rather than the paths they were found under.

Procedure: zip-extract archive KEY: #:directory #:overwrite? #:quiet? #:allow-failure?

Unpack ARCHIVE, into DIRECTORY when one is named.

With OVERWRITE? (the default) existing files are replaced without a prompt; with it #f they are kept and unzip skips them.

Procedure: zip-extract-argv archive KEY: #:directory #:overwrite? #:quiet?

Return the argv that unpacks ARCHIVE.

OVERWRITE? is unzip’s -o: files already there are replaced rather than asked about, which is what an unattended task needs. DIRECTORY is where the files are written.

Procedure: zip-list archive KEY: #:quiet? #:allow-failure?

Print a listing of the files in ARCHIVE, without unpacking it.

Procedure: zip-list-argv archive KEY: #:quiet?

Return the argv that lists the contents of ARCHIVE.


1.2 (maak bundle)

A project can ship its automation: one artefact that runs the Maak file on a machine with neither Guile nor maak installed. The artefact is a ‘guix pack’ of a generated package, so it is built by the Guix helpers this repository already has rather than by a second packaging system.

The generated package is deliberately small. It installs the Maak file and a launcher, and it propagates maak, Guile and whatever the project asks for; ‘guix pack -S /bin=bin’ then puts the launcher, maak, Guile and those tools on the pack’s ‘/bin’. The launcher puts its own directory first on PATH, so a task inside the bundle finds the maak and the Guile the bundle came with.

A package rather than a script that copies files: the closure is what makes the artefact self-contained, and it is Guix that knows how to compute it.

1.2.1 Overview

  • bundle — Build a self-contained bundle of NAME’s automation and return its path.
  • bundle-file-name — Return the file name a bundle of NAME in PACK-FORMAT is written to.
  • bundle-script — Return the Guix package file that defines a bundle for NAME.

1.2.2 Procedures

Procedure: bundle KEY: #:name #:format #:output #:maak-file #:maak-package #:packages #:home-page #:description #:load? #:verbose?

Build a self-contained bundle of NAME’s automation and return its path.

The bundle is a Guix pack of a generated package that installs MAK-FILE and a launcher, and carries maak, Guile and PACKAGES with it, so it runs on a machine with none of them. FORMAT is a ‘guix pack’ format: "tarball" (made relocatable, so it extracts anywhere), "squashfs" or "docker". OUTPUT names the file; by default it is NAME-bundle with an extension for FORMAT.

With LOAD? a docker pack is loaded into the container engine afterwards, using the ‘(maak container)’ helper, so the image is ready to run as well as written.

(bundle #:name "site" #:maak-file "maak.scm"
        #:packages '("git" "curl") #:format "tarball")
Procedure: bundle-file-name name pack-format

Return the file name a bundle of NAME in PACK-FORMAT is written to.

Procedure: bundle-script KEY: #:name #:maak-file #:maak-package #:packages #:home-page #:description

Return the Guix package file that defines a bundle for NAME.

MAK-FILE is the Maak file to ship; MAK-PACKAGE is a Scheme expression that evaluates to the maak package, and PACKAGES are the extra package names the automation needs. The expression is inserted as written, so it is trusted input: it is how a project points at its own build of maak.

The package installs the Maak file under ‘share/NAME’ and a launcher in ‘bin/NAME’, and propagates maak, Guile and the packages, so ‘guix pack -S /bin=bin’ gives a pack whose ‘bin’ holds all of them.


1.3 (maak cargo)

Cargo and Rust helpers, and the pieces a crate reaches for that are not a ‘cargo build’: the metadata ‘cargo metadata’ hands back as JSON, the path an artefact lands at, and the toolchains rustup manages.

There is no build engine here either. ‘cargo-argv’ is a pure builder: it returns the words of a cargo invocation, so a test asserts the command line without a Rust toolchain installed, and ‘cargo’ feeds that list to ‘run’, so ‘–dry-run’ prints it and ‘–plan’ records it. An option that does not fit the keywords travels as an argument, which is how a subcommand maak has never heard of is still a cargo command.

The programs are parameters, honoured from MAAK_CARGO then CARGO and MAAK_RUSTUP then RUSTUP. A value may carry a wrapper or a toolchain (‘"cargo +nightly"’), which is split into words the way an unquoted shell word is, so a task can pin a nightly for one command.

‘cargo metadata’ is read even in a dry run, like pkg-config: it reads the project rather than changing it, and a plan that left out the version a package task would publish would be a plan of a different release.

1.3.1 Overview

  • cargo-command — A parameter object.
  • rustup-command — A parameter object.
  • cargo — Run cargo SUBCOMMAND with ARGUMENTS, as separate words.
  • cargo-argv — Return the argv that runs cargo SUBCOMMAND, without running it.
  • cargo-artifact-path — Return where cargo writes the artefact called NAME.
  • cargo-bench — Run the benchmarks with cargo, passing ARGUMENTS.
  • cargo-binaries — Return the names of the binary targets of PACKAGE, or of the only package.
  • cargo-build — Build the package with cargo, passing ARGUMENTS.
  • cargo-check — Type-check the package with cargo, passing ARGUMENTS.
  • cargo-clean — Remove the build artefacts with cargo, passing ARGUMENTS.
  • cargo-clippy — Lint the package with ‘cargo clippy’, passing ARGUMENTS.
  • cargo-doc — Build the documentation with cargo, passing ARGUMENTS.
  • cargo-fetch — Fetch the dependencies with cargo, passing ARGUMENTS.
  • cargo-fmt — Format the sources with ‘cargo fmt’, passing ARGUMENTS.
  • cargo-install — Install a cargo binary, passing ARGUMENTS.
  • cargo-metadata — Return ‘cargo metadata’ as parsed JSON, a string-keyed alist.
  • cargo-output — Run the cargo ARGV and return its standard output as a string.
  • cargo-package — Return the metadata of one package, or raise when it cannot be chosen.
  • cargo-package-names — Return the names of the packages in the workspace, in cargo’s order.
  • cargo-package-version — Return the version cargo reports for PACKAGE, or for the only package.
  • cargo-publish — Publish the package with cargo, passing ARGUMENTS.
  • cargo-run — Run the binary with cargo; put the program’s own words after "–".
  • cargo-target-directory — Return the directory cargo writes its artefacts into.
  • cargo-test — Run the tests with cargo, passing ARGUMENTS.
  • cargo-update — Update the dependencies with cargo, passing ARGUMENTS.
  • rustup — Run rustup with ARGUMENTS.
  • rustup-active-toolchain — Return the toolchain rustup would use here, as its name.
  • rustup-argv — Return the argv that runs rustup with ARGUMENTS.
  • rustup-component-add — Add COMPONENT, for example "rustfmt" or "clippy", to the active toolchain.
  • rustup-install — Install TOOLCHAIN, for example "nightly".
  • rustup-output — Run rustup with ARGUMENTS and return its standard output.
  • rustup-target-add — Add the compilation TARGET to the active toolchain.
  • rustup-toolchains — Return the names of the installed toolchains.

1.3.2 Parameters

Parameter: cargo-command

Default value:

"cargo"
Parameter: rustup-command

Default value:

"rustup"

1.3.3 Procedures

Procedure: cargo subcommand KEY: #:arguments #:verbose?

Run cargo SUBCOMMAND with ARGUMENTS, as separate words.

This is the short form: the words after SUBCOMMAND are arguments, so ‘(cargo-build "–release")’ passes cargo’s own ‘–release’. Use ‘cargo-argv’ when the structured options are wanted, and ‘run’ to execute what it returns.

(cargo "test" #:arguments '("--workspace" "--all-features"))
Procedure: cargo-argv subcommand KEY: #:arguments #:manifest-path #:package #:features #:no-default-features? #:all-features? #:target #:release? #:profile #:jobs #:offline? #:locked? #:frozen? #:quiet? #:verbose #:color #:message-format #:timings?

Return the argv that runs cargo SUBCOMMAND, without running it.

Global options are placed before SUBCOMMAND and the command’s own options after it, which is the grammar cargo accepts for every subcommand. ARGUMENTS are appended as they are, so an option this builder does not name, or the words a ‘cargo run’ passes to the program after ‘–’, still reach cargo.

FEATURES takes a string or a list and is joined with commas, the way ‘–features’ spells it. VERBOSE is #t for one ‘-v’ or a positive number for that many. RELEASE? and PROFILE cannot both be given: cargo spells the release profile both ways, and asking for two profiles is a question with no answer.

(cargo-argv "build" #:release? #t #:features '("openssl" "serde"))
⇒ ("cargo" "build" "--features" "openssl,serde" "--release")

(cargo-argv "run" #:arguments '("--" "--help"))
⇒ ("cargo" "run" "--" "--help")
Procedure: cargo-artifact-path name KEY: #:profile #:release? #:triple #:manifest-path

Return where cargo writes the artefact called NAME.

PROFILE is the cargo profile, ‘debug’ by default; RELEASE? is the shorthand for ‘release’. TRIPLE names a cross-compilation target’s directory. The path is composed from ‘cargo metadata”s target directory, so a workspace with ‘CARGO_TARGET_DIR’ set answers with the directory cargo will really use.

Procedure: cargo-bench . arguments

Run the benchmarks with cargo, passing ARGUMENTS.

Procedure: cargo-binaries KEY: #:package #:manifest-path

Return the names of the binary targets of PACKAGE, or of the only package.

Procedure: cargo-build . arguments

Build the package with cargo, passing ARGUMENTS.

Procedure: cargo-check . arguments

Type-check the package with cargo, passing ARGUMENTS.

Procedure: cargo-clean . arguments

Remove the build artefacts with cargo, passing ARGUMENTS.

Procedure: cargo-clippy . arguments

Lint the package with ‘cargo clippy’, passing ARGUMENTS.

Procedure: cargo-doc . arguments

Build the documentation with cargo, passing ARGUMENTS.

Procedure: cargo-fetch . arguments

Fetch the dependencies with cargo, passing ARGUMENTS.

Procedure: cargo-fmt . arguments

Format the sources with ‘cargo fmt’, passing ARGUMENTS.

Procedure: cargo-install . arguments

Install a cargo binary, passing ARGUMENTS.

Procedure: cargo-metadata KEY: #:manifest-path #:no-deps? #:offline? #:locked?

Return ‘cargo metadata’ as parsed JSON, a string-keyed alist.

This is how a task learns the workspace’s members, a package’s version and where its artefacts land, without guessing at a path or re-reading Cargo.toml. The query runs even in a dry run.

Procedure: cargo-output argv KEY: #:allow-failure?

Run the cargo ARGV and return its standard output as a string.

The query runs even in a dry run: it reads the project rather than changing it, and a plan that left out what ‘cargo metadata’ says would be a plan of a different project. A failure raises a maak error naming the command, or comes back as #f when the caller asked for the exit status instead.

Procedure: cargo-package KEY: #:name #:manifest-path

Return the metadata of one package, or raise when it cannot be chosen.

Without NAME the answer is the only package in the workspace; a workspace with several packages needs one named, because picking the first would silently describe the wrong crate.

Procedure: cargo-package-names KEY: #:manifest-path

Return the names of the packages in the workspace, in cargo’s order.

Procedure: cargo-package-version KEY: #:package #:manifest-path

Return the version cargo reports for PACKAGE, or for the only package.

Procedure: cargo-publish . arguments

Publish the package with cargo, passing ARGUMENTS.

A dry run of the release is ‘(cargo-publish "–dry-run")’, and cargo’s own flag is what makes it one: maak’s dry run prints the command instead.

Procedure: cargo-run . arguments

Run the binary with cargo; put the program’s own words after "–".

Procedure: cargo-target-directory KEY: #:manifest-path

Return the directory cargo writes its artefacts into.

Procedure: cargo-test . arguments

Run the tests with cargo, passing ARGUMENTS.

Procedure: cargo-update . arguments

Update the dependencies with cargo, passing ARGUMENTS.

Procedure: rustup . arguments

Run rustup with ARGUMENTS.

Procedure: rustup-active-toolchain

Return the toolchain rustup would use here, as its name.

Procedure: rustup-argv . arguments

Return the argv that runs rustup with ARGUMENTS.

Procedure: rustup-component-add component

Add COMPONENT, for example "rustfmt" or "clippy", to the active toolchain.

Procedure: rustup-install toolchain

Install TOOLCHAIN, for example "nightly".

Procedure: rustup-output arguments KEY: #:allow-failure?

Run rustup with ARGUMENTS and return its standard output.

Procedure: rustup-target-add target

Add the compilation TARGET to the active toolchain.

Procedure: rustup-toolchains

Return the names of the installed toolchains.


1.4 (maak cc)

C and C++ build helpers, and the pieces a Makefile or an Automake project reaches for when it moves to maak. There is no build engine here: a compiler invocation is still a command built at the moment a task runs, so ‘–dry-run’ prints it, ‘–plan’ records it, and ‘-j’/‘–watch’ work as they do for every other task.

Two decisions are worth naming.

The argv builders are pure. ‘compile-argv’, ‘link-argv’ and ‘static-library-argv’ return a list of words; the runners ‘compile’, ‘link’ and ‘static-library’ feed that list to ‘run’. A test can assert the command line without a C compiler installed, which is the same split the rest of maak keeps between a description and its execution.

There is no automatic timestamp-driven rebuild. ‘up-to-date?’ compares a target with its inputs, and a task decides whether to use it; the cache arrives as an explicit ‘#:incremental?’ or an ‘unless’, never as a hidden second runner. That is what keeps a dependency from becoming a daemon.

The compilers are parameters, so a task can pin them lexically, and their defaults honour the variables a Makefile would: MAAK_CC, then CC, then ‘cc’; MAAK_CXX, then CXX, then ‘c++’; MAAK_AR, then AR, then ‘ar’. A value may carry flags (‘"ccache gcc"’), which are split into words before the compiler arguments. ‘CFLAGS’, ‘CPPFLAGS’, ‘LDFLAGS’ and ‘LDLIBS’ are not read automatically; ‘environment-flags’ reads one when a task asks for it, so the task says which of them reach which command.

1.4.1 Overview

  • ar-command — A parameter object.
  • c-compiler — A parameter object.
  • cxx-compiler — A parameter object.
  • pkg-config-command — A parameter object.
  • compile — Compile SOURCE to OUTPUT, or to SOURCE’s ‘.o’ beside it.
  • compile-argv — Return the argv that compiles SOURCE to OUTPUT, without running it.
  • compile-objects — Compile every SOURCE to its object under DIRECTORY, up to JOBS at once.
  • compiler-for — Return the compiler for LANGUAGE as a list of words.
  • environment-flags — Return the whitespace-separated words of environment variable NAME.
  • link — Link OBJECTS into OUTPUT.
  • link-argv — Return the argv that links OBJECTS into OUTPUT, without running it.
  • object-file — Return the object file a SOURCE compiles to.
  • pkg-config — Run pkg-config for PACKAGES and return its output as a string.
  • pkg-config-argv — Return the argv that asks pkg-config for PACKAGES, without running it.
  • pkg-config-cflags — Return the compiler flags pkg-config names for PACKAGES, as a list.
  • pkg-config-exists? — Return #t when pkg-config knows every one of PACKAGES.
  • pkg-config-libs — Return the linker flags pkg-config names for PACKAGES, as a list.
  • pkg-config-version — Return the version pkg-config reports for PACKAGE.
  • static-library — Write OBJECTS into the static library OUTPUT.
  • static-library-argv — Return the argv that writes OBJECTS into a static library OUTPUT.
  • up-to-date? — Return #t when OUTPUT exists and is not older than any of INPUTS.

1.4.2 Parameters

Parameter: ar-command

Default value:

"ar"
Parameter: c-compiler

Default value:

"cc"
Parameter: cxx-compiler

Default value:

"c++"
Parameter: pkg-config-command

Default value:

"pkg-config"

1.4.3 Procedures

Procedure: compile source KEY: #:output #:includes #:defines #:flags #:language #:compiler #:standard #:pic? #:depfile? #:verbose?

Compile SOURCE to OUTPUT, or to SOURCE’s ‘.o’ beside it.

The keywords are ‘compile-argv”s. The command goes through ‘run’, so a dry run prints it, a plan records it, and a failure names the compiler and the source.

(compile "src/a.c" #:output "build/a.o" #:includes '("include"))
Procedure: compile-argv source KEY: #:output #:includes #:defines #:flags #:language #:compiler #:standard #:pic? #:depfile?

Return the argv that compiles SOURCE to OUTPUT, without running it.

INCLUDES become ‘-I’ arguments, DEFINES ‘-D’ arguments, and FLAGS are inserted verbatim. STANDARD becomes ‘-std=STANDARD’. PIC? adds ‘-fPIC’, and DEPFILE? adds ‘-MMD -MP’, so the compiler writes the dependency file beside the object; maak does not read that file, and ‘up-to-date?’ is how a task uses it.

(compile-argv "src/a.c" #:output "build/a.o"
              #:includes '("include") #:defines '("NDEBUG")
              #:flags '("-O2" "-Wall") #:standard "c11")
Procedure: compile-objects sources KEY: #:directory #:jobs #:incremental? #:includes #:defines #:flags #:language #:compiler #:standard #:pic? #:depfile? #:verbose?

Compile every SOURCE to its object under DIRECTORY, up to JOBS at once.

Each object is named with ‘object-file’, so ‘src/a.c’ in DIRECTORY ‘build’ becomes ‘build/a.o’. With INCREMENTAL? #t an object newer than its source is left alone; without it every object is compiled, which is what a clean build wants. JOBS above one starts that many compilers at once, each a process of its own; a failure is reported with how many of them failed, and the compilers’ own messages are above it.

(compile-objects '("src/a.c" "src/b.c")
                 #:directory "build" #:jobs 4 #:incremental? #t
                 #:includes '("include") #:depfile? #t)
Procedure: compiler-for language OPT: compiler

Return the compiler for LANGUAGE as a list of words.

LANGUAGE is ‘c’, ‘c++’, ‘"c’ or ‘"c++’". COMPILER, when given, overrides the ‘c-compiler’ or ‘cxx-compiler’ parameter. A compiler value with flags is split into words, so ‘MAAK_CC="ccache gcc"’ works.

Procedure: environment-flags name OPT: default

Return the whitespace-separated words of environment variable NAME.

This is how a migrated task reads ‘CFLAGS’, ‘CPPFLAGS’, ‘LDFLAGS’ or ‘LDLIBS’ when it decides to honour them. Nothing is read automatically: the task says which variable reaches which command.

(compile "src/a.c" #:flags (environment-flags "CFLAGS"))

Link OBJECTS into OUTPUT.

The keywords are ‘link-argv”s, plus VERBOSE? for the command line. Use ‘#:flags’ for ‘LDFLAGS’ (before the objects) and ‘#:link-flags’ for ‘LDLIBS’ and pkg-config’s libs (after them).

Return the argv that links OBJECTS into OUTPUT, without running it.

LIBRARIES become ‘-l’ arguments and LIBRARY-PATHS ‘-L’ arguments. FLAGS are inserted before the objects, which is where ‘LDFLAGS’ goes; LINK-FLAGS are inserted after the objects and the libraries, which is where ‘LDLIBS’ and the pre-formed flags pkg-config returns go. SHARED? adds ‘-shared’, STATIC? adds ‘-static’, and SONAME adds ‘-Wl,-soname,SONAME’, which is the usual three things a libtool link line was doing.

(link-argv '("build/a.o" "build/b.o")
           #:output "build/app" #:libraries '("m")
           #:library-paths '("build") #:flags '("-pthread")
           #:link-flags (pkg-config-libs '("zlib")))
Procedure: object-file source OPT: directory

Return the object file a SOURCE compiles to.

The source’s extension is replaced with ‘.o’ and its directory is kept, or DIRECTORY is used instead. ‘src/a.c’ becomes ‘src/a.o’; with DIRECTORY ‘build’, it becomes ‘build/a.o’. Only the file name is used for DIRECTORY, so two sources with the same base name collide there; give them different directories or different names.

Procedure: pkg-config packages KEY: #:mode #:static?

Run pkg-config for PACKAGES and return its output as a string.

MODE and STATIC? are ‘pkg-config-argv”s. The query runs even in a dry run, because it reads the system: ‘maak –plan’ then shows the flags a compile would really use.

(pkg-config '("gtk+-3.0"))              ;; => "-I... -pthread ..."
(pkg-config '("zlib") #:mode 'libs)     ;; => "-lz"
Procedure: pkg-config-argv packages KEY: #:mode #:static?

Return the argv that asks pkg-config for PACKAGES, without running it.

MODE is ‘cflags’, ‘libs’, ‘modversion’ or ‘exists’. With MODE ‘libs’ and STATIC? the ‘–static’ flag is added, so pkg-config names the libraries a static link needs.

(pkg-config-argv '("gtk+-3.0") #:mode 'cflags)
⇒ ("pkg-config" "--cflags" "gtk+-3.0")
Procedure: pkg-config-cflags packages

Return the compiler flags pkg-config names for PACKAGES, as a list.

(pkg-config-cflags '("gtk+-3.0"))
⇒ ("-I/gnu/store/.../include/gtk-3.0" ...)
Procedure: pkg-config-exists? packages

Return #t when pkg-config knows every one of PACKAGES.

(pkg-config-exists? '("zlib" "openssl"))
Procedure: pkg-config-libs packages KEY: #:static?

Return the linker flags pkg-config names for PACKAGES, as a list.

With STATIC? #t the ‘–static’ answer is used, which names the transitive libraries a static link needs.

Procedure: pkg-config-version package

Return the version pkg-config reports for PACKAGE.

(pkg-config-version "zlib")
⇒ "1.3.1"
Procedure: static-library output objects KEY: #:archiver #:verbose?

Write OBJECTS into the static library OUTPUT.

(static-library "build/libfoo.a" (map (lambda (source) (object-file source "build"))
                                       '("src/a.c" "src/b.c")))
Procedure: static-library-argv output objects KEY: #:archiver

Return the argv that writes OBJECTS into a static library OUTPUT.

The archiver is ‘ar rcs’, which creates the archive, inserts the objects and writes the index; ARCHIVER overrides the ‘ar-command’ parameter.

(static-library-argv "build/libfoo.a" '("build/a.o" "build/b.o"))
Procedure: up-to-date? output inputs

Return #t when OUTPUT exists and is not older than any of INPUTS.

A missing output or a missing input is not up to date. This is the explicit check a task uses to skip a compile; maak never applies it on its own, because a dependency that decides whether a task runs is the thing maak was written to leave to the task.

(unless (up-to-date? "build/a.o" '("src/a.c" "include/a.h"))
  (compile "src/a.c" #:output "build/a.o"))

1.5 (maak container)

Container helpers for the two engines a Linux machine is likely to have. Podman and Docker share almost all of their command line, so a task written against one should not have to be rewritten for the other: the engine is a parameter, detected once from PATH and overridable per call or with MAAK_CONTAINER_ENGINE.

The same is true of Compose, with one extra wrinkle: Podman has both ‘podman compose‘ and the older ‘podman-compose‘, so the compose program is a parameter of its own. MAAK_COMPOSE names it, and a call can pass ‘#:program‘.

Every helper has an ‘-argv‘ builder next to it. The builder returns the list of words without running anything: that is what the procedures feed to ‘run‘, what –dry-run prints, and what a test can assert without needing a container runtime.

Nothing here starts a container as a side effect of loading the module.

1.5.1 Overview

1.5.2 Parameters

Parameter: container-compose-command

Default value:

("podman-compose")
Parameter: container-engine

Default value:

"podman"

1.5.3 Procedures

Procedure: compose-argv arguments KEY: #:program #:file #:project #:env-files #:profiles

Return the argv that runs Compose with ARGUMENTS.

FILE is –file, PROJECT is –project-name, ENV-FILES are passed as –env-file, and PROFILES as –profile. They come before the subcommand, which is where both Docker Compose and podman-compose expect them.

Procedure: compose-available? KEY: #:program

Return #t when the Compose PROGRAM can be found on PATH.

PROGRAM is the list of words container-compose-command returns; its first word is what is looked for.

Procedure: compose-build services KEY: #:program #:file #:project #:env-files #:profiles #:no-cache? #:pull? #:allow-failure? #:verbose?

Build SERVICES with Compose; see ‘compose-build-argv‘.

Procedure: compose-build-argv services KEY: #:program #:file #:project #:env-files #:profiles #:no-cache? #:pull?

Return the argv that builds SERVICES, or every service when it is empty.

Procedure: compose-config services KEY: #:program #:file #:project #:env-files #:profiles #:quiet? #:services? #:allow-failure? #:verbose?

Render the Compose configuration; see ‘compose-config-argv‘.

Procedure: compose-config-argv services KEY: #:program #:file #:project #:env-files #:profiles #:quiet? #:services?

Return the argv that renders the resolved Compose configuration.

QUIET? asks Compose to validate without printing; SERVICES? asks for only the service definitions, and the service names are passed as arguments when given. The quiet flag is spelled -q because that is the form both Compose implementations accept.

Procedure: compose-down services KEY: #:program #:file #:project #:env-files #:profiles #:volumes? #:remove-orphans? #:rmi #:timeout #:allow-failure? #:verbose?

Stop and remove SERVICES with Compose; see ‘compose-down-argv‘.

Procedure: compose-down-argv services KEY: #:program #:file #:project #:env-files #:profiles #:volumes? #:remove-orphans? #:rmi #:timeout

Return the argv that stops and removes SERVICES, or the whole project.

VOLUMES? also removes named volumes, which is what makes a test environment return to a clean state; it is off by default because the data is otherwise kept between runs.

Procedure: compose-exec service command KEY: #:program #:file #:project #:env-files #:profiles #:tty? #:user #:workdir #:index #:no-tty? #:allow-failure? #:verbose?

Run COMMAND in SERVICE with Compose; see ‘compose-exec-argv‘.

Procedure: compose-exec-argv service command KEY: #:program #:file #:project #:env-files #:profiles #:tty? #:user #:workdir #:index #:no-tty?

Return the argv that runs COMMAND in SERVICE.

NO-TTY? (the default) passes -T, which both Docker Compose and podman-compose spell the same way. A task needs it: without it Compose tries to allocate a terminal, and a command run from a pipeline or a CI job does not have one. TTY? asks for a terminal instead, and wins over the default: the two flags contradict each other, so only one is ever emitted. Pass #:no-tty? #f for an interactive shell that should not be told what to do either way.

Procedure: compose-logs services KEY: #:program #:file #:project #:env-files #:profiles #:follow? #:tail #:no-color? #:allow-failure?

Print the logs of SERVICES with Compose; see ‘compose-logs-argv‘.

Procedure: compose-logs-argv services KEY: #:program #:file #:project #:env-files #:profiles #:follow? #:tail #:no-color?

Return the argv that prints the logs of SERVICES, or of the whole project.

Procedure: compose-output arguments KEY: #:program #:file #:project #:env-files #:profiles #:allow-failure?

Run Compose with ARGUMENTS and return its output as a string.

Procedure: compose-ps services KEY: #:program #:file #:project #:env-files #:profiles #:all? #:format #:allow-failure?

List the containers of SERVICES with Compose; see ‘compose-ps-argv‘.

Procedure: compose-ps-argv services KEY: #:program #:file #:project #:env-files #:profiles #:all? #:format

Return the argv that lists the containers of SERVICES, or of the project.

ALL? is Docker Compose’s –all; podman-compose has no equivalent flag and lists the project’s containers already, so leave it off with that program.

Procedure: compose-pull services KEY: #:program #:file #:project #:env-files #:profiles #:ignore-pull-failures? #:allow-failure? #:verbose?

Pull the images of SERVICES with Compose; see ‘compose-pull-argv‘.

Procedure: compose-pull-argv services KEY: #:program #:file #:project #:env-files #:profiles #:ignore-pull-failures?

Return the argv that pulls the images of SERVICES.

IGNORE-PULL-FAILURES? is Docker Compose’s flag; podman-compose does not accept it, so leave it off with that program.

Procedure: compose-restart services KEY: #:program #:file #:project #:env-files #:profiles #:timeout #:allow-failure? #:verbose?

Restart SERVICES with Compose; see ‘compose-restart-argv‘.

Procedure: compose-restart-argv services KEY: #:program #:file #:project #:env-files #:profiles #:timeout

Return the argv that restarts SERVICES.

Procedure: compose-run service command KEY: #:program #:file #:project #:env-files #:profiles #:remove? #:no-deps? #:user #:workdir #:allow-failure? #:verbose?

Run COMMAND in a one-off container for SERVICE; see ‘compose-run-argv‘.

Procedure: compose-run-argv service command KEY: #:program #:file #:project #:env-files #:profiles #:remove? #:no-deps? #:user #:workdir

Return the argv that runs COMMAND in a one-off container for SERVICE.

REMOVE? (the default) passes –rm; NO-DEPS? keeps Compose from starting the service’s dependencies.

Procedure: compose-up services KEY: #:program #:file #:project #:env-files #:profiles #:detach? #:build? #:force-recreate? #:remove-orphans? #:no-start? #:wait? #:allow-failure? #:verbose?

Start SERVICES with Compose; see ‘compose-up-argv‘.

Procedure: compose-up-argv services KEY: #:program #:file #:project #:env-files #:profiles #:detach? #:build? #:force-recreate? #:remove-orphans? #:no-start? #:wait?

Return the argv that starts SERVICES, or every service when it is empty.

DETACH? (the default) is –detach, because a task that starts a stack wants its shell back. BUILD? rebuilds images, FORCE-RECREATE? replaces the containers, REMOVE-ORPHANS? is on by default, and WAIT? waits for the services to be healthy before returning.

Procedure: container arguments KEY: #:engine #:allow-failure? #:verbose?

Run ENGINE with ARGUMENTS, a list of strings.

The escape hatch for subcommands without a wrapper, such as ‘volume ls‘. Nothing is handed to a shell, so a label or a path with a space in it stays one argument.

Procedure: container-argv arguments KEY: #:engine

Return the argv that runs ENGINE with ARGUMENTS.

This is the shared shape of every helper below: the engine first, then the subcommand and its flags. It is exported because a subcommand without a wrapper is still a subcommand – pass ‘(list "volume" "ls")‘ and it works.

Procedure: container-available? KEY: #:engine

Return #t when ENGINE can be found on PATH.

Procedure: container-build context KEY: #:engine #:tag #:file #:target #:build-args #:labels #:no-cache? #:pull? #:platform #:network #:quiet? #:allow-failure? #:verbose?

Build the image described by CONTEXT; see ‘container-build-argv‘.

Procedure: container-build-argv context KEY: #:engine #:tag #:file #:target #:build-args #:labels #:no-cache? #:pull? #:platform #:network #:quiet?

Return the argv that builds the image described by CONTEXT.

TAG is –tag, FILE is –file, TARGET is –target, and BUILD-ARGS and LABELS are lists of strings. CONTEXT is the directory sent to the engine, normally the last argument.

Procedure: container-exec name command KEY: #:engine #:interactive? #:tty? #:env #:workdir #:user #:allow-failure? #:verbose?

Run COMMAND in the container NAME; see ‘container-exec-argv‘.

Procedure: container-exec-argv name command KEY: #:engine #:interactive? #:tty? #:env #:workdir #:user

Return the argv that runs COMMAND in the container NAME.

COMMAND is a list of strings. INTERACTIVE? and TTY? are the usual -i and -t; a non-interactive command needs neither, which is what a build step wants.

Procedure: container-images KEY: #:engine #:arguments #:allow-failure?

List images; see ‘container-images-argv‘.

Procedure: container-images-argv KEY: #:engine #:arguments

Return the argv that lists images, with any extra ARGUMENTS.

Procedure: container-inspect names KEY: #:engine #:format #:type #:allow-failure?

Inspect NAMES; see ‘container-inspect-argv‘.

Procedure: container-inspect-argv names KEY: #:engine #:format #:type

Return the argv that inspects NAMES.

FORMAT is passed as –format, which is how a task reads a field rather than the whole JSON document. TYPE is –type for engines that accept it.

Procedure: container-logs name KEY: #:engine #:follow? #:tail #:since #:allow-failure?

Print the logs of the container NAME; see ‘container-logs-argv‘.

Procedure: container-logs-argv name KEY: #:engine #:follow? #:tail #:since

Return the argv that prints the logs of the container NAME.

FOLLOW? is –follow; TAIL is a number or the word all, passed as –tail; SINCE is passed as –since.

Procedure: container-output arguments KEY: #:engine #:allow-failure?

Run ENGINE with ARGUMENTS and return its output as a string.

This is the reading counterpart of ‘container‘: the output is a value a task can trim and compare rather than a line on the terminal. In dry-run mode nothing runs, the command is printed, and the empty string comes back.

Procedure: container-ps KEY: #:engine #:all? #:allow-failure?

List containers; see ‘container-ps-argv‘.

Procedure: container-ps-argv KEY: #:engine #:all?

Return the argv that lists containers, including stopped ones with ALL?.

Procedure: container-pull image KEY: #:engine #:allow-failure?

Pull IMAGE; see ‘container-pull-argv‘.

Procedure: container-pull-argv image KEY: #:engine

Return the argv that pulls IMAGE.

Procedure: container-push image KEY: #:engine #:allow-failure?

Push IMAGE; see ‘container-push-argv‘.

Procedure: container-push-argv image KEY: #:engine

Return the argv that pushes IMAGE.

Procedure: container-rm names KEY: #:engine #:force? #:volumes? #:allow-failure?

Remove the containers NAMES; see ‘container-rm-argv‘.

Procedure: container-rm-argv names KEY: #:engine #:force? #:volumes?

Return the argv that removes the containers NAMES.

FORCE? is the default because a task that removes a container means it, and a running container would otherwise fail the whole task.

Procedure: container-run image KEY: #:engine #:command #:name #:detach? #:remove? #:interactive? #:tty? #:env #:publish #:volume #:mount #:workdir #:entrypoint #:network #:user #:platform #:pull #:labels #:privileged? #:allow-failure? #:verbose?

Run IMAGE as a container; see ‘container-run-argv‘ for the options.

Procedure: container-run-argv image KEY: #:engine #:command #:name #:detach? #:remove? #:interactive? #:tty? #:env #:publish #:volume #:mount #:workdir #:entrypoint #:network #:user #:platform #:pull #:labels #:privileged?

Return the argv that runs IMAGE as a container.

COMMAND is the list of arguments passed to the image, after its name. The defaults are the ones an unattended task wants: REMOVE? is #t, so a finished container leaves nothing behind, and nothing is attached to the terminal unless INTERACTIVE? or TTY? asks for it. ENV, PUBLISH, VOLUME, MOUNT and LABELS are lists of strings, each passed with its flag.

Procedure: container-stop names KEY: #:engine #:allow-failure?

Stop the containers NAMES, a list of strings.

Procedure: container-stop-argv names KEY: #:engine

Return the argv that stops the containers NAMES.

Procedure: container-tag source target KEY: #:engine #:allow-failure?

Tag SOURCE as TARGET; see ‘container-tag-argv‘.

Procedure: container-tag-argv source target KEY: #:engine

Return the argv that gives SOURCE the additional name TARGET.

Procedure: detect-compose-command KEY: #:engine #:path #:preferred

Return the words that run Compose, as a list.

PREFERRED, when non-empty, is split on whitespace and used as it stands. For Podman, the standalone ‘podman-compose‘ is preferred when it is installed, and ‘podman compose‘ is used otherwise; Docker always answers ‘docker compose‘. The engine is passed in rather than read from the parameter, so the result is a pure function of its arguments.

Procedure: detect-container-engine KEY: #:path #:preferred

Return the container engine maak should use.

PREFERRED, when non-empty, wins unchanged. Otherwise Podman is chosen when it is on PATH, then Docker. The fallback is Podman even when neither is installed, so a missing engine is reported as a missing program rather than silently replaced by another one.

PATH is the search path, PATH itself by default, so the choice can be tested without changing the process environment.

(detect-container-engine #:path search-path)
(detect-container-engine #:preferred engine-name)
Procedure: run-compose arguments KEY: #:program #:file #:project #:env-files #:profiles #:allow-failure? #:verbose?

Run Compose with ARGUMENTS, a list of strings.

The escape hatch for subcommands without a wrapper, such as ‘top‘. FILE, PROJECT, ENV-FILES and PROFILES are passed before the subcommand, the way both Compose implementations expect.


1.6 (maak declarative)

Task files in JSON, TOML and YAML: the same tasks a Maak file defines, for a project that wants a list and none of the language.

A data file describes less than Scheme does, and the difference is the point. A task is a name, a docstring, one or more commands, and the handful of declarations ‘task-metadata!’ already carries. There are no arguments, no conditions and no loops; a project that needs those writes the Maak file, where the whole language is available.

Reading a data file is reading data and then building the definitions maak runs. Nothing in the file becomes source text: the commands are strings in a list, the environment is an alist, and the form that is evaluated is built here from validated values. A string command is a shell line, because the file said so; a list is a program and its arguments, run without a shell.

The task order is the file’s order, because the parsers keep the order of a mapping. A dependency is a name another task in the same file must have finished before, as ‘#:depends’ is in a Maak file.

1.6.1 Overview

1.6.2 Macros

Macro: task-file-task-depends x

Undocumented macro.

Macro: task-file-task-doc x

Undocumented macro.

Macro: task-file-task-example x

Undocumented macro.

Macro: task-file-task-hidden? x

Undocumented macro.

Macro: task-file-task-name x

Undocumented macro.

Macro: task-file-task? x

Undocumented macro.

1.6.3 Procedures

Procedure: declarative-file? path

Return #t when PATH is a task file in a format maak reads.

Procedure: load-task-file path

Define PATH’s tasks in module ‘(maak)’ and return their names, in file order.

The definitions are built from the data, not read as text: a command is a list of strings that ‘run’ executes without a shell, or one string that ‘$’ hands to the shell because the file asked for a shell line.

Procedure: read-task-file path

Return the tasks PATH describes, as ‘<task-file-task>’ values in file order.

The schema is closed: an unknown key is an error rather than something ignored, because a task file that says something maak does not read is a task file whose author believes something false.

Procedure: task-file-call-graph path

Return the calls PATH declares, as the alist ‘static-call-graph’ returns.

A data file has no body to read, so the only edge is a ‘depends’ entry.

Procedure: task-file-descriptions path

Return PATH’s tasks as ‘<task-description>’ values, in file order.

1.6.4 Variables

Variable: declarative-task-files
("maak.yaml" "maak.yml" "maak.toml" "maak.json")

1.7 (maak dsl)

1.7.1 Overview

  • get-module-var — Get a variable from the currently loaded maak file module.
  • job-command — An undocumented macro.
  • job-pid — An undocumented macro.
  • job? — An undocumented macro.
  • make-plan-step — An undocumented macro.
  • pipeline-errors — An undocumented macro.
  • pipeline-outputs — An undocumented macro.
  • pipeline-result? — An undocumented macro.
  • plan-step-argv — An undocumented macro.
  • plan-step-async? — An undocumented macro.
  • plan-step-dev-null? — An undocumented macro.
  • plan-step-directory — An undocumented macro.
  • plan-step-env — An undocumented macro.
  • plan-step-kind — An undocumented macro.
  • plan-step-sudo? — An undocumented macro.
  • plan-step-task — An undocumented macro.
  • plan-step? — An undocumented macro.
  • stage? — An undocumented macro.
  • text — An undocumented macro.
  • banner? — A parameter object.
  • color? — A parameter object.
  • current-task — A parameter object.
  • dry-run? — A parameter object.
  • elevation-command — A parameter object.
  • maak-load-path — A parameter object.
  • plan-steps — A parameter object.
  • quiet? — A parameter object.
  • $ — Executes a shell command constructed from a list of strings.
  • add-load-path! — Prepend DIR to Guile’s load path and record it as a maak load path.
  • add-load-paths! — Prepend every directory of DIRS to the load path, in order.
  • argv->string — Return ARGV as a command line a shell would read back as the same words.
  • blank-line? — Return #t when STR is empty or only whitespace.
  • bold-output — Return X emphasised for a terminal, or X unchanged when styling is off.
  • cat — Print FILE to standard output.
  • command-on-path? — Return #t when COMMAND is an executable in one of the directories in PATH.
  • cp — Copy a file or directory from X to Y.
  • decorate-command — Return CMD with the decorations a task asked for, applied in a fixed order.
  • dedent-string — Remove the common leading indentation from a multiline STR.
  • delete-file-recursively — Delete a directory and all its contents recursively.
  • detect-elevation-command — Return the command maak should use to run something as root.
  • environment-assignments — Return ENV as a list of ‘KEY=VALUE’ strings.
  • environment-load-paths — Return the directories named by ‘MAAK_LOAD_PATH’.
  • error-message-string — Return the most descriptive string Guile attached to a caught error.
  • exception->message — Return a one-line human message for a caught error.
  • find-maak-error — Return the ‘&maak-error’ among KEY and VALS, or ‘#f’.
  • guix-container — Run CMD-PARTS in a Guix container defined by MANIFEST.
  • guix-pack — Build a ‘guix pack’ of the program in FILE.
  • guix-shell — Run CMD-PARTS inside a Guix shell made of PACKAGES.
  • indent-string — Indent every line of STR by BY spaces.
  • job-done? — Return #t when JOB has finished, without waiting for it.
  • job-exit-code — Wait for JOB when needed and return its exit code.
  • leading-whitespace-count — Return the number of leading space and tab characters in STR.
  • log-error — An undocumented procedure.
  • log-info — An undocumented procedure.
  • log-message — An undocumented procedure.
  • log-separator — An undocumented procedure.
  • maak-error-hint — An undocumented procedure.
  • maak-error-message — An undocumented procedure.
  • maak-error? — An undocumented procedure.
  • maak-proc? — Predicate that indicates whether a procedure is a valid maak proc.
  • maak-task? — Predicate that indicates whether it is a valid maak task.
  • make-maak-error — An undocumented procedure.
  • manifest-shell — Execute a command inside a Guix shell defined by a manifest file.
  • mkdir-p — Create a directory and all necessary parent directories.
  • mv — Move or rename a file or directory.
  • pipeline-ok? — Return #t when every stage of the pipeline that produced RESULT succeeded.
  • planning? — Return #t when a plan is being recorded.
  • program-shell — Execute a command inside a Guix shell defined by a program file.
  • raise-maak-error — Raise a ‘&maak-error’ with MESSAGE and an optional HINT.
  • record-plan! — Record STEP in the plan being collected, if there is one.
  • remkdir-p — Remove a directory if it exists, then recreate it.
  • rm-rf — Delete PATH recursively, forcefully and verbosely.
  • run — Run a program and its arguments without a shell.
  • run-pipeline — Run a pipeline of programs without a shell.
  • shell-quote — Return STR quoted so that a shell reads it as one literal word.
  • split-load-path — Split a ‘PATH’-style colon separated STR into a list of directories.
  • stage — Describe one stage of a pipeline, with the options ‘run’ takes.
  • string-lines — Split STR on newlines into a list of lines.
  • syscall — Executes a shell command and checks its exit code.
  • task-error — Raise a user-facing error from a task.
  • time-machine — Execute a command using a pinned Guix revision via ‘guix time-machine‘.
  • time-machine-manifest-shell — Execute a command inside a Guix shell defined by a manifest file,
  • time-machine-program-shell — Execute a command inside a Guix shell defined by a program file,
  • unlines — Join LINES with newlines, adding no trailing newline.
  • unwords — Join WORDS with single spaces.
  • wait-job — Wait for JOB to finish and return #t when it exited with code 0.
  • with-load-path — Call THUNK with DIRS added to the load path, restoring it afterwards.
  • ~ — A utility function to format a string (interpolation).
  • &maak-error — A record type.

1.7.2 Macros

Macro: get-module-var x

Get a variable from the currently loaded maak file module.

Macro: job-command x

Undocumented macro.

Macro: job-pid x

Undocumented macro.

Macro: job? x

Undocumented macro.

Macro: make-plan-step x

Undocumented macro.

Macro: pipeline-errors x

Undocumented macro.

Macro: pipeline-outputs x

Undocumented macro.

Macro: pipeline-result? x

Undocumented macro.

Macro: plan-step-argv x

Undocumented macro.

Macro: plan-step-async? x

Undocumented macro.

Macro: plan-step-dev-null? x

Undocumented macro.

Macro: plan-step-directory x

Undocumented macro.

Macro: plan-step-env x

Undocumented macro.

Macro: plan-step-kind x

Undocumented macro.

Macro: plan-step-sudo? x

Undocumented macro.

Macro: plan-step-task x

Undocumented macro.

Macro: plan-step? x

Undocumented macro.

Macro: stage? x

Undocumented macro.

Macro: text x

Undocumented macro.

1.7.3 Parameters

Parameter: banner?

Default value:

#t
Parameter: color?

Default value:

#t
Parameter: current-task

Default value:

#f
Parameter: dry-run?

Default value:

#f
Parameter: elevation-command

Default value:

"sudo"
Parameter: maak-load-path

Default value:

()
Parameter: plan-steps

Default value:

#f
Parameter: quiet?

Default value:

#f

1.7.4 Procedures

Procedure: $ cmd-parts KEY: #:verbose? #:join #:env #:sudo? #:dev-null? #:allow-failure? #:async?

Executes a shell command constructed from a list of strings.

($ '("echo -n" "hello-world"))

;; as root, in the background, quietly, and without caring whether it fails
($ '("systemctl daemon-reload")
   #:sudo? #t #:async? #t #:dev-null? #t #:allow-failure? #t)

ARGUMENTS:

  • cmd-parts (list): A list of strings that will be joined to form the command.
  • #:verbose? (boolean, default #f): If #t, logs the generated command before executing it.
  • #:join (string, default " "): A string to use as a separator when joining the command parts.
  • #:env (alist, list of strings, or string, default ’()): Environment variables to set for this command only, given as an alist ((("CI" . "1"))), as "KEY=VALUE" strings, or as one such string. They are passed through env and reach the command itself.
  • #:sudo? (boolean, default #f): If #t, the command runs through the configured privilege escalation command – doas when it is installed, sudo otherwise, or whatever MAAK_ELEVATE names. See elevation-command.
  • #:dev-null? (boolean, default #f): If #t, both standard output and standard error are discarded to /dev/null.
  • #:allow-failure? (boolean, default #f): If #t, a non-zero exit code does not raise: #f is returned instead, so a task can decide what a failure means. The command line itself is left alone, which is what lets the task be told the command failed.
  • #:async? (boolean, default #f): If #t, the command is started in the background and a job record is returned (see run), instead of a boolean.

RETURNS: The result of the syscall function: #t if the command completes with an exit code of 0, #f if it failed and #:allow-failure? was given, and a job record when #:async? was given.

Procedure: add-load-path! dir

Prepend DIR to Guile’s load path and record it as a maak load path.

Returns the canonical name of the directory that was added, which makes it usable in a ‘let’ when a task wants to report what it did. This is a procedure rather than the ‘add-to-load-path’ syntax because a task computes the directory at run time.

Procedure: add-load-paths! dirs

Prepend every directory of DIRS to the load path, in order.

Returns the list of directories that were added.

Procedure: argv->string argv

Return ARGV as a command line a shell would read back as the same words.

Used for the dry-run line and for logging; what actually runs is the ARGV list itself, so quoting is only there to make the printed command copyable.

Procedure: blank-line? str

Return #t when STR is empty or only whitespace.

Procedure: bold-output x

Return X emphasised for a terminal, or X unchanged when styling is off.

See ‘color?’: ‘NO_COLOR’ turns the escapes off for a whole run.

Procedure: cat file KEY: #:verbose? #:expand?

Print FILE to standard output.

Procedure: command-on-path? command path

Return #t when COMMAND is an executable in one of the directories in PATH.

Procedure: cp x y KEY: #:recursive? #:force? #:verbose? #:verbose-copy? #:expand?

Copy a file or directory from X to Y.

ARGUMENTS: x: Source file or directory. y: Destination path.

recursive?: If #t, copy directories recursively (‘-r‘). Defaults to #t. force?: If #t, overwrite existing files without prompting (‘-f‘). Defaults to #f. verbose?: If #t, logs the final shell command before execution. Defaults to #f. verbose-copy?: If #t, enables verbose output from ‘cp‘ (‘-v‘). Defaults to #t. expand?: If #t, the shell expands X and Y, so a wildcard names the files it matches. Defaults to #f, which passes both as one argument each.

Constructs and executes a command of the form:

cp [OPTIONS] X Y

through ‘run‘, so X and Y reach ‘cp‘ as one argument each and a path with a space in it is copied rather than split.

RETURNS: #t if the copy succeeds.

ERRORS: Signals an error if the underlying ‘cp‘ command exits with a non-zero status.

Procedure: decorate-command cmd KEY: #:env #:sudo? #:dev-null?

Return CMD with the decorations a task asked for, applied in a fixed order.

The environment comes first and goes through ‘env’ rather than as a ‘KEY=VALUE’ prefix, because everything after a ‘guix shell –’ is executed directly: a prefix there would be looked up as a program name and fail with 127.

Whether a failure is allowed is not a decoration of the command line at all; ‘syscall’ reads the exit code, which a ‘|| true’ in the line would have hidden. Backgrounding is not one either: a trailing ‘&’ leaves nothing to wait on, so ‘#:async?’ forks instead and hands back a job (see ‘run’).

Procedure: dedent-string str

Remove the common leading indentation from a multiline STR.

Tabs are expanded to four spaces, leading and trailing blank lines are removed, and the smallest indentation shared by the remaining lines is stripped from all of them. Blank lines in the middle are preserved as empty lines.

(dedent-string "   hello world")
⇒ "hello world"
Procedure: delete-file-recursively dir KEY: #:verbose? #:expand?

Delete a directory and all its contents recursively. Runs ‘rm -rfv DIR‘ through ‘run‘, so DIR reaches ‘rm‘ as one argument however it is spelled. The deletion is recursive, forced and verbose.

With EXPAND? #t the shell expands DIR, so ‘build/*.o’ names every matching file; the same opt-in applies to the other file helpers via ‘run’.

ARGUMENTS:

  • dir (string): The path of the directory (or file) to delete.
  • #:verbose? (boolean, default #f): If #t, logs the generated command before executing it.

RETURNS: #t if the command succeeded.

ERRORS: Signals an error if the underlying shell command exits with a non-zero status.

Procedure: detect-elevation-command KEY: #:path #:preferred

Return the command maak should use to run something as root.

PREFERRED, when non-empty, wins unchanged, which is how ‘MAAK_ELEVATE’ lets a user name an escalation program maak has never heard of. Otherwise ‘doas’ is chosen when it is on PATH, and ‘sudo’ when it is not: ‘doas’ is the smaller tool and the one a machine that has it usually means, while ‘sudo’ remains the fallback every other system understands.

PATH is the search path, ‘PATH’ itself by default, so the function can be tested without changing the process environment.

(detect-elevation-command #:path "/usr/bin:/bin")     ;; => "sudo"
(detect-elevation-command #:preferred "doas -n")      ;; => "doas -n"
Procedure: environment-assignments env

Return ENV as a list of ‘KEY=VALUE’ strings.

ENV may be #f, a single string, a list of strings, or an alist of pairs, so a caller can pass whatever shape it already has. An entry that is not a pair is used as it stands, which is what makes the plain string list useful when a value cannot be written as a literal.

Procedure: environment-load-paths

Return the directories named by ‘MAAK_LOAD_PATH’.

‘GUILE_LOAD_PATH’ is already honoured by Guile itself and is deliberately not merged here; this is the maak-specific extra so a task can add paths without clobbering the user’s global setting.

Procedure: error-message-string key vals

Return the most descriptive string Guile attached to a caught error.

The shape of the arguments depends on who raised the error. A call to ‘error’ arrives as (#f MESSAGE () #f), where the message is the second element, while a primitive failure such as ‘(car 1)’ arrives as (#f MESSAGE (1) (1)) whose *first* string is only the name of the procedure – reporting that as the message would hide the one sentence the user needs. The second element is the message in both shapes, so it is preferred, and the remaining values are searched only when it is not a string, as when ‘throw’ is handed a key and a message but no irritants.

Procedure: exception->message key vals

Return a one-line human message for a caught error.

It prefers an attached exception message, then the message among the raising values, and only then falls back to the raw key. Guile raises many errors with a format *template* (for example ‘no code for module ~S’) plus the arguments; those are filled in here so the user never sees a bare ‘~S’.

Procedure: find-maak-error key vals

Return the ‘&maak-error’ among KEY and VALS, or ‘#f’.

Guile hands a ‘catch’ handler the raising key followed by its values; a ‘raise-exception’ of our condition type arrives as the first value, so both are searched. This is what lets ‘main’ tell our own messages apart from internal errors.

Procedure: guix-container cmd-parts KEY: #:manifest #:pure? #:network? #:share #:expose #:join #:verbose? #:env #:sudo? #:dev-null? #:allow-failure? #:async?

Run CMD-PARTS in a Guix container defined by MANIFEST.

A container isolates the process from the host: no network unless NETWORK? is #t, no access to the home directory unless it is SHARE’d. SHARE and EXPOSE are lists of ‘HOST=DEST’ (or ‘HOST’) strings passed through as ‘-S’ and ‘-E’.

(guix-container '("maak test")
                #:manifest "manifest.scm"
                #:share '("/home/joe"))
Procedure: guix-pack cmd-parts KEY: #:file #:format #:image-tag #:output #:relocatable? #:symlinks #:extra-packages #:join #:verbose? #:env #:sudo? #:dev-null? #:allow-failure? #:async?

Build a ‘guix pack’ of the program in FILE.

FORMAT is any ‘guix pack –format’ value ("docker", "squashfs", "tarball"). IMAGE-TAG names a docker image, OUTPUT names the file to write instead of letting ‘guix pack’ choose one, SYMLINKS are ‘TARGET=SOURCE’ entries for ‘-S’, and EXTRA-PACKAGES are appended to the pack. With RELOCATABLE? a tarball is made relocatable, so it can be extracted anywhere rather than at ‘/’.

(guix-pack '() #:format "docker" #:image-tag "maak"
           #:symlinks '("/bin=bin") #:extra-packages '("bash"))
Procedure: guix-shell cmd-parts KEY: #:packages #:pure? #:manifest #:file #:join #:verbose? #:env #:sudo? #:dev-null? #:allow-failure? #:async?

Run CMD-PARTS inside a Guix shell made of PACKAGES.

This is the package-list sibling of ‘manifest-shell’ and ‘program-shell’: the environment is described inline rather than in a manifest or a ‘guix.scm’. PACKAGES may be a list of strings ("guile", "coreutils") or a single string, which is used as-is.

(guix-shell '("guile -c '(+ 1 2)'") #:packages '("guile"))
Procedure: indent-string str KEY: #:by #:first?

Indent every line of STR by BY spaces.

When FIRST? is #f the first line is left flush, which is what aligning a continuation underneath an existing prefix needs.

Procedure: job-done? job

Return #t when JOB has finished, without waiting for it.

A finished job is reaped here, so a background process that a task never waits for does not stay a zombie for the rest of the run.

Procedure: job-exit-code job

Wait for JOB when needed and return its exit code.

Returns #f when the process was terminated by a signal, which is also what ‘status:exit-val’ says about such a status.

Procedure: leading-whitespace-count str

Return the number of leading space and tab characters in STR.

Procedure: log-error msg . args

Undocumented procedure.

Procedure: log-info msg . args

Undocumented procedure.

Procedure: log-message msg

Undocumented procedure.

Procedure: log-separator

Undocumented procedure.

Procedure: maak-error-hint obj

Undocumented procedure.

Procedure: maak-error-message obj

Undocumented procedure.

Procedure: maak-error? obj

Undocumented procedure.

Procedure: maak-proc? x

Predicate that indicates whether a procedure is a valid maak proc.

A parameter is a procedure too – ‘(define build-args (make-parameter ’()))’ returns one – and it is a value a task reads rather than a task, so it is not a maak proc even though it can be called.

Procedure: maak-task? x

Predicate that indicates whether it is a valid maak task.

Procedure: make-maak-error a b

Undocumented procedure.

Procedure: manifest-shell cmd-parts KEY: #:verbose? #:pure? #:join #:manifest #:env #:sudo? #:dev-null? #:allow-failure? #:async?

Execute a command inside a Guix shell defined by a manifest file.

ARGUMENTS:

cmd-parts: A list of strings representing the command to run inside the Guix shell environment.

#:verbose?: If #t, logs the fully constructed command before execution. Defaults to #f. #:pure?: If #t, it will run in a pure isolated shell (clean). Defaults to #f. #:join: The string separator used when joining command segments. Defaults to a single space. #:manifest: Path to the manifest file (in Scheme) describing the package environment. Defaults to "manifest.scm".

Constructs and executes a command of the form:

    guix shell -m MANIFEST -- <cmd ...>

using the ‘$‘ wrapper to enforce proper execution and error handling.

RETURNS: #t if the command succeeds.

ERRORS: Signals an error if the underlying shell command exits with a non-zero status.

Procedure: mkdir-p dir KEY: #:verbose? #:expand?

Create a directory and all necessary parent directories. Executes ‘mkdir -pv DIR‘ through ‘run‘. Parent directories are created as needed and each created directory is printed. A DIR that contains spaces is one directory, not several.

ARGUMENTS:

  • dir: The path of the directory to create.
  • #:verbose? (boolean, default #f): If #t, logs the generated command before executing it.

RETURNS: #t if the command completed successfully.

ERRORS: Signals an error if the underlying shell command exits with a non-zero code.

Procedure: mv x y KEY: #:verbose? #:expand?

Move or rename a file or directory. Executes ‘mv -v X Y‘ through ‘run‘, so X and Y reach ‘mv‘ as one argument each. The ‘-v‘ flag prints each move operation performed.

ARGUMENTS:

  • x (string): The source file or directory.
  • y (string): The destination path.
  • #:verbose? (boolean, default #f): If #t, logs the generated command before executing it.

RETURNS: #t if the command succeeds.

ERRORS: Signals an error if the underlying shell command returns a non-zero exit code.

Procedure: pipeline-ok? result

Return #t when every stage of the pipeline that produced RESULT succeeded.

RESULT is what ‘run-pipeline’ returns when asked to capture the output, whether or not failures were allowed.

Procedure: planning?

Return #t when a plan is being recorded.

Procedure: program-shell cmd-parts KEY: #:verbose? #:pure? #:join #:file #:env #:sudo? #:dev-null? #:allow-failure? #:async?

Execute a command inside a Guix shell defined by a program file.

ARGUMENTS: cmd-parts: A list of strings representing the command to run inside the Guix shell environment.

#:verbose?: If #t, logs the full constructed command before execution. Defaults to #f.

#:join: String used to join command segments. Defaults to a single space. #:file: Path to the Guix program or manifest file defining the shell environment. Defaults to "guix.scm".

Constructs and executes a command of the form:

    guix shell -f FILE -- <cmd ...>

using the ‘$‘ wrapper to safely run the command and check for errors.

RETURNS: #t if the command succeeds.

ERRORS: Signals an error if the underlying shell command exits with a non-zero status.

Procedure: raise-maak-error message KEY: #:hint

Raise a ‘&maak-error’ with MESSAGE and an optional HINT.

MESSAGE is the single line the user reads; HINT, when given, is printed underneath as a suggestion for what to do next. Prefer this over ‘error’ in library code so the CLI can keep the report short.

Procedure: record-plan! step

Record STEP in the plan being collected, if there is one.

Procedure: remkdir-p dir KEY: #:verbose? #:expand?

Remove a directory if it exists, then recreate it. This results in an empty directory, regardless of its previous state. Calls ‘delete-file-recursively‘ then ‘mkdir-p‘ on DIR.

ARGUMENTS:

  • dir: The path of the directory to recreate.
  • #:verbose? (boolean, default #f): If #t, logs the generated command before executing it.

RETURNS: #t if the operations succeed.

ERRORS: Signals an error if any underlying shell command fails.

Procedure: rm-rf path KEY: #:verbose? #:expand?

Delete PATH recursively, forcefully and verbosely.

A short spelling of delete-file-recursively, for the times a task says rm -rfv build in the shell. It is an alias rather than a second implementation, so it takes the same #:verbose? and #:expand? keywords and behaves the same way.

(rm-rf "build")
(rm-rf "build/*.o" #:expand? #t)
Procedure: run argv KEY: #:verbose? #:env #:sudo? #:dev-null? #:allow-failure? #:async? #:expand?

Run a program and its arguments without a shell.

ARGV is a list of strings: the program to run, followed by one string per argument. Nothing is split or interpolated, so a path with a space in it stays one argument. This is the default way to run a program; ‘$’ is for the lines that genuinely need a shell – pipes, redirections, globs, ‘$(...)’ and ‘VAR=value’ prefixes.

With #:expand? #t the arguments are joined with spaces and handed to the shell, so wildcards, ‘~’ and ‘$VAR’ are expanded the way a shell expands them. That is opt-in because the shell sees words rather than arguments: a path with a space in it becomes several words again, which is exactly what a caller asking for a pattern wants and exactly what the default prevents.

(run (list "mkdir" "-p" build-dir))
(run (list "git" "commit" "-m" message))

;; start a server in the background and wait for it later
(let ((server (run (list "guix" "shell" "--" "run-server")
                   #:async? #t)))
  (log-info "server started as ~a
" (job-pid server))
  (wait-job server))

ARGUMENTS:

  • argv (list): The program and its arguments, each a string.
  • #:verbose? (boolean, default #f): If #t, logs the command before running it.
  • #:env (alist, list of strings, or string, default ’()): Environment variables for this program only, in the shapes ‘$’ accepts.
  • #:sudo? (boolean, default #f): If #t, the program runs through the configured privilege escalation command – doas when it is installed, sudo otherwise, or whatever MAAK_ELEVATE names. See elevation-command.
  • #:dev-null? (boolean, default #f): If #t, standard output and standard error are connected to /dev/null.
  • #:allow-failure? (boolean, default #f): If #t, a non-zero exit code does not raise: #f is returned instead.
  • #:async? (boolean, default #f): If #t, the program is started in the background and a job record is returned.
  • #:expand? (boolean, default #f): If #t, ARGV is joined into one shell line and the shell expands wildcards, ‘~’ and ‘$VAR’ in it. The arguments are then words rather than literals.

RETURNS: #t if the program exits with code 0, #f if it failed and failures were allowed, and a job record when #:async? was given.

ERRORS: Signals a maak error when the program exits non-zero and failures are not allowed.

Procedure: run-pipeline stages KEY: #:verbose? #:allow-failure? #:env #:async? #:capture?

Run a pipeline of programs without a shell.

STAGES is a non-empty list of stages. A stage is an argument list shaped like the ARGV of ‘run’ – the program first, then one string per argument – or a stage form, which adds the options ‘run’ takes for that stage alone. The standard output of each stage is the standard input of the next, and the whole pipeline is done when every stage has finished.

(run-pipeline (list (list "cat" file)
                    (list "grep" "-v" "^#")
                    (list "sort" "-u")))

;; a stage with an environment and a file of its own, and one that needs root
(run-pipeline (list (stage (list "sort" "-u")
                           #:env '("LC_ALL=C")
                           #:tee "sorted.txt")
                    (stage (list "tee" log) #:sudo? #t)))

;; keep what every stage wrote for the task to look at
(define result (run-pipeline (list (list "git" "diff" "--cached")
                                   (list "grep" "^+"))
                             #:capture? #t
                             #:allow-failure? #t))
(pipeline-outputs result)   ;; one string per stage, in order
(pipeline-ok? result)       ;; #f when a stage failed

Unlike a shell’s ‘|’, which reports the exit status of the last stage alone, a pipeline that fails anywhere reports the stages that failed and raises; pass #:allow-failure? #t to get #f instead and decide in the task. This is the pipefail behaviour, and it is the one that does not let a failing producer hide behind a successful consumer.

A pipeline’s output can be looked at afterwards in two ways. A stage with #:tee keeps a copy of what it wrote in a file the task names, and the stage after it reads the same bytes while it runs: nothing is held back until the pipeline ends. #:capture? #t records every stage the same way, in temporary files, and hands the bytes back in the result instead of printing them; the last stage’s output is then the last entry of pipeline-outputs. Capturing is the way to make a decision from what a pipeline produced – a count of changed files, the list a ‘grep’ matched – without running the pipeline twice.

ARGUMENTS:

  • stages (list): The stages to run, each an argument list or a stage.
  • #:verbose? (boolean, default #f): If #t, logs the pipeline, decorations included, before running it.
  • #:allow-failure? (boolean, default #f): If #t, a failing stage does not raise: #f is returned instead (or the result, when the output was captured), so the task can decide what it means.
  • #:env (alist, list of strings, or string, default ’()): Environment variables for every stage of the pipeline, in the shapes ‘$’ accepts. A stage’s own #:env is added to these, later names winning.
  • #:capture? (boolean, default #f): If #t, every stage’s standard output is recorded and returned in a <pipeline-result>, and the pipeline prints nothing itself. The result’s pipeline-outputs holds one string per stage, in stage order, and pipeline-ok? says whether every stage succeeded. A stage that also has #:tee records into that file, which is left in place.
  • #:async? (boolean, default #f): If #t, the whole pipeline is started in the background and a job record is returned. It is the pipeline that becomes a job, not a stage: a stage cannot finish before the stage after it has read what it wrote. The job’s exit code is 0 when every stage succeeded and 1 otherwise, whatever #:allow-failure? said. An asynchronous pipeline cannot capture its output, because the bytes would be read in the background process; give the stage a #:tee file instead.

RETURNS: #t when every stage exits with code 0, #f when a stage failed and failures were allowed, a <pipeline-result> when #:capture? was given, and a job record when #:async? was given.

ERRORS: Signals a maak error naming the failing stage or stages when a pipeline fails and failures are not allowed, and when #:capture? and #:async? are asked for together.

Procedure: shell-quote str

Return STR quoted so that a shell reads it as one literal word.

The POSIX recipe: wrap the value in single quotes and turn every embedded single quote into the four characters backslash-quote-quote-quote. Unlike ‘~s’, this is safe for spaces, tabs, ‘$’, backticks and newlines.

Procedure: split-load-path str

Split a ‘PATH’-style colon separated STR into a list of directories.

An empty entry is dropped, so a trailing or doubled colon does not add the current directory twice.

Procedure: stage argv KEY: #:env #:sudo? #:tee

Describe one stage of a pipeline, with the options ‘run’ takes.

ARGV is a program and its arguments, in the shape ‘run’ takes them. ENV sets names for this stage alone, in the shapes ‘$’ accepts; they are added to the pipeline’s own environment, later names winning. With SUDO? the stage runs through the configured privilege escalation command (see ‘elevation-command’). TEE names a file that the stage’s standard output is also written to, the way ‘tee’ does it: the stage after this one reads the same bytes, and the file keeps them for the task to look at once the pipeline is done.

(run-pipeline (list (stage (list "grep" "-v" "^#")
                           #:env '("LC_ALL=C")
                           #:tee "clean.txt")
                    (stage (list "sort" "-u"))))

A stage is a description only; ‘run-pipeline’ starts it.

Procedure: string-lines str

Split STR on newlines into a list of lines.

Procedure: syscall cmd KEY: #:allow-failure? #:async?

Executes a shell command and checks its exit code.

ARGUMENTS:

  • cmd (string): The shell command to be executed.
  • #:allow-failure? (boolean, default #f): If #t, a non-zero exit code or a signal does not raise: it comes back as #f, the way ‘cmd || true’ would keep a shell going, except that the task also learns that the command failed.
  • #:async? (boolean, default #f): If #t, the command is started in the background and a job record is returned instead of a boolean. The command still runs through a shell, so pipes and redirections keep working, but the fork is maak’s: ‘job-pid’, ‘job-done?’, ‘wait-job’ and ‘job-exit-code’ can read the process.

RETURNS: #t if the command completes with an exit code of 0, #f if it failed and failures are allowed, and a job record when #:async? was given.

ERRORS: Signals an error if the command returns a non-zero exit code or is terminated by a signal. The message names the command, and the exit code when there is one.

Procedure: task-error message KEY: #:hint #:args

Raise a user-facing error from a task.

This is what a task calls when it cannot do its job: the message is printed as one line, the hint (when given) underneath it, and no Guile backtrace follows. ARGS, when given, are handed to ‘format’ to build the message, so a task can report the value that made it give up.

(task-error "no compiled artefact for ~a" #:args (list host))
(task-error "the deploy key is missing"
            #:hint "Set DEPLOY_KEY, or run maak deploy --dry-run.")
Procedure: time-machine cmd-parts KEY: #:verbose? #:join #:channels #:env #:sudo? #:dev-null? #:allow-failure? #:async?

Execute a command using a pinned Guix revision via ‘guix time-machine‘.

ARGUMENTS: cmd-parts: A list of strings representing the command to run after the ‘guix time-machine‘ invocation.

#:verbose?: If #t, logs the final constructed command before running it. Defaults to #f. #:join: The string used to join command segments when constructing the final command. Defaults to a single space. #:channels: Path to the channels file used to pin the Guix revision. Defaults to "channels.scm".

Constructs and executes a command of the form:

    guix time-machine --channels=CHANNELS -- <cmd ...>

using the ‘$‘ wrapper to run the resulting shell command safely.

RETURNS: #t if the command succeeds.

ERRORS: Signals an error if the underlying command exits with a non-zero status.

Procedure: time-machine-manifest-shell cmd-parts KEY: #:verbose? #:pure? #:join #:channels #:manifest #:env #:sudo? #:dev-null? #:allow-failure? #:async?

Execute a command inside a Guix shell defined by a manifest file, using a pinned Guix revision via ‘guix time-machine‘.

ARGUMENTS: cmd-parts: A list of strings representing the command to run inside the pinned Guix shell environment.

#:verbose?: If #t, logs the composed command before execution. Defaults to #f. #:pure?: If #t, it will run in a pure isolated shell (clean). Defaults to #f. join: String used to join command segments. Defaults to a single space. #:channels: Path to the channels file used to pin the Guix revision. Defaults to "channels.scm". #:manifest: Path to the manifest file describing the package environment. Defaults to "manifest.scm".

Constructs and executes a command of the form:

    guix time-machine --channels=CHANNELS -- shell -m MANIFEST -- <cmd ...>

This provides a reproducible shell environment defined by the manifest file and pinned to the Guix revision specified in the channels file.

RETURNS: #t if the command succeeds.

ERRORS: Signals an error if any underlying shell command exits with a non-zero status.

Procedure: time-machine-program-shell cmd-parts KEY: #:verbose? #:pure? #:join #:channels #:file #:env #:sudo? #:dev-null? #:allow-failure? #:async?

Execute a command inside a Guix shell defined by a program file, using a pinned Guix revision via ‘guix time-machine‘.

ARGUMENTS: cmd-parts: A list of strings representing the command to run inside the pinned Guix shell environment.

#:verbose?: If #t, logs the composed command before execution. Defaults to #f. #:pure?: If #t, it will run in a pure isolated shell (clean). Defaults to #f. #:join: String used to join command segments. Defaults to a single space. #:channels: Path to the channels file used to pin the Guix revision. Defaults to "channels.scm". #:file: Path to the Guix program file (e.g. guix.scm) defining the environment. Defaults to "guix.scm".

Constructs and executes a command of the form:

    guix time-machine --channels=CHANNELS -- shell -f FILE -- <cmd ...>

This provides a reproducible development environment defined by the program file and pinned to the Guix revision specified in the channels file.

RETURNS: #t if the command succeeds.

ERRORS: Signals an error if any underlying shell command exits with a non-zero status.

Procedure: unlines lines

Join LINES with newlines, adding no trailing newline.

Procedure: unwords words

Join WORDS with single spaces.

Procedure: wait-job job

Wait for JOB to finish and return #t when it exited with code 0.

Returns #f for a non-zero exit or a signal. Waiting twice is fine: the status is remembered after the first wait.

Procedure: with-load-path dirs thunk

Call THUNK with DIRS added to the load path, restoring it afterwards.

DIRS is a list of directory names. The load path is saved and restored even when THUNK raises, so a failing task does not leave the process with a polluted search path.

(with-load-path '("./lib" "./src")
  (lambda () (use-modules (my project))))
Procedure: ~ . args

A utility function to format a string (interpolation). Alias for (apply format #f ARGS).

(~ "Hello world, my name is ~a and I am ~a years old"
    "Joe"
    30)

ARGUMENTS:

  • args (list): A list of arguments where the first element is the format string and the subsequent elements are the values to be substituted.

RETURNS: A newly allocated string resulting from the formatting operation.

1.7.5 Record Types

Record type: &maak-error

This record type has the following fields:

  • message
  • hint

1.8 (maak elisp)

Emacs Lisp helpers: the batch commands an Emacs package’s automation reaches for, and the conventions a package is expected to keep.

‘emacs-batch-argv’ is the pure builder and ‘emacs-batch’ the runner, so a command is printed by ‘–dry-run’ and recorded by ‘–plan’. The higher level ‘elisp-byte-compile’, ‘elisp-checkdoc’ and ‘elisp-ert’ are the three things a package’s CI does; they run Emacs with ‘-Q’, so the result does not depend on the machine’s init file.

The practice helpers read the file rather than run Emacs: a package’s version is the ‘;; Version:’ header, its feature is the ‘(provide ...)’ form, and ‘elisp-practices’ answers with the conventions a file is missing. That makes them cheap enough to call in a test and precise enough to gate a release.

The program is a parameter, honoured from MAAK_EMACS then EMACS; a value may carry flags the way a shell would read them, as in ‘MAAK_EMACS="emacs -nw"’.

1.8.1 Overview

  • emacs-command — A parameter object.
  • elisp-byte-compile — Byte-compile FILES in batch, with LOAD-PATHS on the load path.
  • elisp-checkdoc — Run ‘checkdoc’ on FILES in batch, with LOAD-PATHS on the load path.
  • elisp-ert — Load TEST-FILES and run the ERT tests matching SELECTOR in batch.
  • elisp-feature — Return the first feature PATH provides, or #f.
  • elisp-files — Return every ‘.el’ file under DIRECTORY, recursively, sorted.
  • elisp-footer? — Return #t when PATH carries its ‘;;; FILE ends here’ footer.
  • elisp-header — Return the value of the ‘;; FIELD:’ header in PATH, or #f.
  • elisp-lexical-binding? — Return #t when PATH sets lexical-binding on its first line.
  • elisp-package-requires — Return the ‘;; Package-Requires:’ header of PATH as it is written, or #f.
  • elisp-package-version — Return the ‘;; Version:’ header of PATH, or #f.
  • elisp-practices — Return the conventions PATH is missing, as a list of sentences.
  • elisp-practices-ok? — Return #t when PATH keeps every convention ‘elisp-practices’ checks.
  • elisp-provides — Return the features PATH provides, as written by ‘(provide ...)’.
  • elisp-quote — Return TEXT as an Emacs Lisp string literal.
  • elisp-version — Return the Emacs version the configured program reports.
  • emacs-batch — Run Emacs in batch, forwarding OPTIONS to ‘emacs-batch-argv’.
  • emacs-batch-argv — Return the argv that runs Emacs in batch, without running it.
  • emacs-capture — Run Emacs in batch with OPTIONS and return its standard output.
  • emacs-output — Run the Emacs batch ARGV and return its standard output.

1.8.2 Parameters

Parameter: emacs-command

Default value:

"emacs"

1.8.3 Procedures

Procedure: elisp-byte-compile files KEY: #:load-paths #:warnings-as-errors?

Byte-compile FILES in batch, with LOAD-PATHS on the load path.

With WARNINGS-AS-ERRORS? a warning from the compiler fails the command, which is what a CI gate wants; the default reports the warnings and succeeds.

Procedure: elisp-checkdoc files KEY: #:load-paths

Run ‘checkdoc’ on FILES in batch, with LOAD-PATHS on the load path.

checkdoc reports; it does not fail the command. A gate that has to fail is ‘elisp-byte-compile’ with ‘#:warnings-as-errors? #t’.

Procedure: elisp-ert test-files KEY: #:load-paths #:selector

Load TEST-FILES and run the ERT tests matching SELECTOR in batch.

SELECTOR is ERT’s selector as an Emacs Lisp expression, ‘t‘ by default, so every test runs. A string selector is written quoted for Lisp – ‘"\"foo\""‘ – and a tag selector as the form it is, ‘"(tag smoke)"‘. The expression is inserted as written, which is safe because it comes from the Maak file rather than from a report. Emacs exits non-zero when a test fails.

Procedure: elisp-feature path

Return the first feature PATH provides, or #f.

Procedure: elisp-files OPT: directory

Return every ‘.el’ file under DIRECTORY, recursively, sorted.

Hidden directories and their contents are skipped, which leaves a checkout’s ‘.git’ and an editor’s cache out of the list.

Procedure: elisp-footer? path

Return #t when PATH carries its ‘;;; FILE ends here’ footer.

Procedure: elisp-header path field

Return the value of the ‘;; FIELD:’ header in PATH, or #f.

This is how a package’s version and requirements are written in the file itself, above the commentary.

Procedure: elisp-lexical-binding? path

Return #t when PATH sets lexical-binding on its first line.

Procedure: elisp-package-requires path

Return the ‘;; Package-Requires:’ header of PATH as it is written, or #f.

Procedure: elisp-package-version path

Return the ‘;; Version:’ header of PATH, or #f.

Procedure: elisp-practices path

Return the conventions PATH is missing, as a list of sentences.

The list is empty when the file keeps them all. The checks are the parts of the Emacs Lisp packaging conventions that a reader can see without running anything: lexical binding, the version header, the commentary and code sections, the feature it provides, and the footer.

Procedure: elisp-practices-ok? path

Return #t when PATH keeps every convention ‘elisp-practices’ checks.

Procedure: elisp-provides path

Return the features PATH provides, as written by ‘(provide ...)’.

Procedure: elisp-quote text

Return TEXT as an Emacs Lisp string literal.

The quotes and backslashes are escaped, so a selector or a path reaches the ‘–eval’ expression as data rather than as more Lisp.

Procedure: elisp-version

Return the Emacs version the configured program reports.

Procedure: emacs-batch . options

Run Emacs in batch, forwarding OPTIONS to ‘emacs-batch-argv’.

(emacs-batch #:functions '("batch-byte-compile")
             #:arguments '("foo.el"))
Procedure: emacs-batch-argv KEY: #:quick? #:load-paths #:load-files #:evals #:functions #:arguments

Return the argv that runs Emacs in batch, without running it.

QUICK? adds ‘-Q’, which keeps the site file and the init file out of the run; it is on by default because a package’s CI should not depend on the machine’s configuration. LOAD-PATHS become ‘-L’ words and LOAD-FILES ‘-l’ words; EVALS become ‘–eval’ and FUNCTIONS ‘-f’. ARGUMENTS are appended last, where a function such as ‘batch-byte-compile’ reads the files it was given.

(emacs-batch-argv #:load-paths '(".") #:evals '("(princ emacs-version)"))
⇒ ("emacs" "--batch" "-Q" "-L" "." "--eval" "(princ emacs-version)")
Procedure: emacs-capture . options

Run Emacs in batch with OPTIONS and return its standard output.

This is the keyword form of ‘emacs-output’: ‘(emacs-capture #:evals ’("(princ emacs-version)"))’.

Procedure: emacs-output argv KEY: #:allow-failure?

Run the Emacs batch ARGV and return its standard output.

A query runs even in a dry run, because it reads the project rather than changing it. An expression that prints with ‘princ’ is what puts a value on this output; ‘message’ writes to standard error.


1.9 (maak explain)

‘maak explain TASK’ answers the question a run leaves implicit: where the task sits in the composition, how the environment it reads was put together, and which environment file had the last word. Nothing here runs a task.

The composition is read from the Maak file rather than observed: every call to a task name inside another task’s body is an edge, so the graph is what the file says, not a trace of one run. A call hidden behind ‘apply’, a higher-order procedure or a macro is not seen; the page that documents ‘explain’ says so.

The environment is reported from the same files a run would read, in the same order, and against the process environment the run started with. The rule is ‘load-env-file”s: the process wins, and otherwise the first file that sets a name wins because later files do not override. The report says which file that was and what the ones after it tried to say.

1.9.1 Overview

  • environment-alist — Return ENVIRONMENT-STRINGS as an alist of ‘(NAME .
  • environment-report — Return how the environment variables FILES mention would be resolved.
  • explain-text — Return the explanation of TASK as the text a person reads.

1.9.2 Procedures

Procedure: environment-alist environment-strings

Return ENVIRONMENT-STRINGS as an alist of ‘(NAME . VALUE)’.

ENVIRONMENT-STRINGS is what ‘(environment)’ returns: one ‘NAME=VALUE’ string per variable. A string without an ‘=’ is skipped rather than guessed at.

Procedure: environment-report files base-env

Return how the environment variables FILES mention would be resolved.

FILES are the environment files a run would read, in order; BASE-ENV is the process environment before any of them. Each answer is ‘(NAME VALUE SOURCE IGNORED)’, where SOURCE is ‘"process environment"’ or the file that won, and IGNORED is a list of ‘(FILE . VALUE)’ the other files said.

The precedence is ‘load-env-file”s: the process environment wins, and among files the first one to set a name wins, because later files do not override. A variable no file mentions is not reported at all, so the answer never dumps an unrelated environment.

Procedure: explain-text KEY: #:task #:file #:doc #:needs #:example #:calls #:called-by #:env-files #:env-report #:load-paths #:elevation

Return the explanation of TASK as the text a person reads.

TASK is its name as a string, FILE the Maak file, DOC its docstring, NEEDS the dependencies it declared and EXAMPLE the invocation it declared. CALLS and CALLED-BY are the names from the static call graph, ENV-FILES and ENV-REPORT are what ‘environment-report’ answered, LOAD-PATHS the resolved load path and ELEVATION the privilege escalation command in use.


1.10 (maak formats)

Reading JSON, TOML and YAML without a dependency.

A Maak file is Scheme, and Scheme is the whole language. The formats here exist for the task files documented on docs/task-files.org, where a project wants a list of tasks and none of the language, and for ‘(maak cargo)’, which reads ‘cargo metadata’ but cannot ask a Guile build to carry a JSON library just for that.

Each reader understands a documented subset and refuses the rest. That is the important half: a parser that guessed at an anchor, a multi-line scalar or a second document would hand a task a command it did not read. An unsupported construct is a maak error with its line, never a silently different value.

The data representation is deliberately small:

mapping an alist of (string . value) in file order, so a listing keeps the order the file wrote; sequence a proper list; scalar a string, an exact or inexact number, #t, #f, or the symbol ‘null’ for a missing value.

An empty list is both an empty mapping and an empty sequence; the schema that consumes it knows which it meant. ‘data-mapping?’ and ‘data-sequence?’ answer for every other value.

Nothing here evaluates anything. The text is parsed into data, and the caller decides what the data means, which is why a task file can be read on a machine that has no reason to trust it.

1.10.1 Overview

  • data-file-format — Return ‘json’, ‘toml’ or ‘yaml’ for PATH’s extension, or #f.
  • data-keys — Return the keys of MAPPING, in the order the file wrote them.
  • data-mapping? — Return #t when VALUE is a mapping: a list of string-keyed pairs.
  • data-ref — Return the value KEY names in MAPPING, or DEFAULT when it names none.
  • data-sequence? — Return #t when VALUE is a sequence rather than a mapping.
  • json-read-string — Read TEXT as one JSON value.
  • read-data-file — Read PATH as JSON, TOML or YAML, chosen by its extension.
  • toml-read-string — Read TEXT as one TOML document.
  • yaml-read-string — Read TEXT as one YAML document.

1.10.2 Procedures

Procedure: data-file-format path

Return ‘json’, ‘toml’ or ‘yaml’ for PATH’s extension, or #f.

Procedure: data-keys mapping

Return the keys of MAPPING, in the order the file wrote them.

Procedure: data-mapping? value

Return #t when VALUE is a mapping: a list of string-keyed pairs.

An empty list is a mapping as well as an empty sequence; a caller that has to tell them apart knows which one it asked for.

Procedure: data-ref mapping key OPT: default

Return the value KEY names in MAPPING, or DEFAULT when it names none.

Procedure: data-sequence? value

Return #t when VALUE is a sequence rather than a mapping.

Procedure: json-read-string text KEY: #:source

Read TEXT as one JSON value.

Objects become string-keyed alists, arrays lists, ‘null’ the symbol ‘null’, and a duplicate key is an error rather than a value that silently wins.

Procedure: read-data-file path

Read PATH as JSON, TOML or YAML, chosen by its extension.

A missing file and an extension maak does not read are maak errors: a task file that cannot be read is not an empty task list.

Procedure: toml-read-string text KEY: #:source

Read TEXT as one TOML document.

Tables become nested string-keyed alists, arrays lists, and a key defined twice is an error. The subset is the one a task file needs; see the note above for what is refused.

Procedure: yaml-read-string text KEY: #:source

Read TEXT as one YAML document.

The subset is documented above; anything outside it is a maak error rather than a value that was guessed at.


1.11 (maak frontend)

Frontend helpers: npm, pnpm and yarn behind one set of procedures, the package.json a project already has, and the scripts a web build runs.

The three managers agree on what a project is and disagree on how to spell half the verbs: ‘npm ci’ against ‘pnpm install –frozen-lockfile’ against ‘yarn install –immutable’, ‘npm install’ against ‘pnpm add’, ‘npm exec –’ against ‘pnpm exec’. That disagreement is the whole reason this module exists. A task says what it means – install from the lock file, add a dependency, run a script – and the manager the checkout pins supplies the words.

Which manager that is comes from the lock file, because the lock file is written by whichever tool the project actually ran, and is not something a checkout carries by accident. ‘MAAK_PACKAGE_MANAGER‘ overrides it, and ‘package-manager‘ is a parameter, so a task can pin one for a single call. The value is a program rather than a name, so ‘"corepack pnpm"‘ is allowed the way ‘"cargo +nightly"‘ is: the last word is the manager, and the words before it are run first.

There is no build engine here. The scripts in package.json are the build’s own description, and ‘frontend-run’ runs one; a task that wants vite, webpack or tsc by name uses ‘frontend-exec’, which is the manager’s own way of running a binary from ‘node_modules’.

1.11.1 Overview

  • package-json-file — A parameter object.
  • package-manager — A parameter object.
  • detect-package-manager — Return the package manager DIRECTORY pins, named as its program is.
  • frontend — Run the package manager with WORDS, forwarding OPTIONS to ‘frontend-argv’.
  • frontend-add — Add PACKAGES as dependencies, from the registry or the file system.
  • frontend-argv — Return the argv that runs WORDS with the project’s package manager.
  • frontend-build — Run the ‘build’ script, passing ARGUMENTS to it.
  • frontend-check — Run the ‘lint’, ‘test’ and ‘build’ scripts, in that order.
  • frontend-ci — Install the dependencies exactly as the lock file records them.
  • frontend-exec — Run COMMAND from ‘node_modules/.bin’, passing ARGUMENTS to it.
  • frontend-format — Run the ‘format’ script, passing ARGUMENTS to it.
  • frontend-install — Install the project’s dependencies, passing ARGUMENTS to the manager.
  • frontend-lint — Run the ‘lint’ script, passing ARGUMENTS to it.
  • frontend-output — Run the frontend ARGV and return its standard output as a string.
  • frontend-publish — Publish the package, passing ARGUMENTS to the manager.
  • frontend-remove — Remove PACKAGES from the dependencies.
  • frontend-run — Run the package.json SCRIPT, passing ARGUMENTS to it.
  • frontend-test — Run the ‘test’ script, passing ARGUMENTS to it.
  • package-dependencies — Return the dependencies package.json declares, with the ranges it gives them.
  • package-dev-dependencies — Return the development dependencies package.json declares.
  • package-json — Return PATH read as JSON, a string-keyed alist, in file order.
  • package-manager-kind — Return the package manager MANAGER runs, as one of ‘npm’, ‘pnpm’ or ‘yarn’.
  • package-name — Return the name package.json gives the package.
  • package-scripts — Return the names of the scripts package.json defines, in file order.
  • package-version — Return the version package.json gives the package.

1.11.2 Parameters

Parameter: package-json-file

Default value:

"package.json"
Parameter: package-manager

Default value:

"npm"

1.11.3 Procedures

Procedure: detect-package-manager KEY: #:directory

Return the package manager DIRECTORY pins, named as its program is.

The lock file is the answer because it is the file the manager itself wrote: ‘package-lock.json’ is npm’s, ‘pnpm-lock.yaml’ is pnpm’s and ‘yarn.lock’ is yarn’s. A checkout with none of them answers ‘npm’, the manager every machine with Node already has.

DIRECTORY is the project’s root, the current directory by default, so the function can be tested without changing where the process runs.

Procedure: frontend words . options

Run the package manager with WORDS, forwarding OPTIONS to ‘frontend-argv’.

(frontend '("run" "build"))
Procedure: frontend-add packages KEY: #:dev? #:arguments

Add PACKAGES as dependencies, from the registry or the file system.

PACKAGES is one name or a list of them. DEV? asks for a development dependency, which npm and pnpm spell ‘–save-dev’ and yarn spells ‘–dev’. ARGUMENTS are the manager’s own words, appended last.

Procedure: frontend-argv words KEY: #:arguments #:directory

Return the argv that runs WORDS with the project’s package manager.

WORDS is the command and its words – ‘’("run" "build")’ for a script, or ‘’("install")’. The manager’s program comes first, then the flag that points it at DIRECTORY when one is given, then WORDS, then ARGUMENTS as they are, so an option this module does not name still reaches the manager.

(frontend-argv '("run" "build"))
⇒ ("npm" "run" "build")

(frontend-argv '("install") #:directory "web")
⇒ ("npm" "--prefix" "web" "install")
Procedure: frontend-build . arguments

Run the ‘build’ script, passing ARGUMENTS to it.

Procedure: frontend-check

Run the ‘lint’, ‘test’ and ‘build’ scripts, in that order.

The three are the scripts a web build usually has; a project that names them otherwise writes the three ‘frontend-run’ calls itself. The order is the cheap failure first, so a lint error stops the run before the bundle is built.

Procedure: frontend-ci . arguments

Install the dependencies exactly as the lock file records them.

This is what a CI run wants and what a developer’s ‘frontend-install’ must not be: it refuses to update the lock file, so a build that would have changed it fails instead. The words are the manager’s own – ‘npm ci’, ‘pnpm install –frozen-lockfile’, ‘yarn install –immutable’ (or ‘–frozen-lockfile’ on Yarn 1).

Procedure: frontend-exec command . arguments

Run COMMAND from ‘node_modules/.bin’, passing ARGUMENTS to it.

This is how a task runs a tool the project installed without knowing whether the manager needs ‘–’ between its own words and the tool’s.

Procedure: frontend-format . arguments

Run the ‘format’ script, passing ARGUMENTS to it.

Procedure: frontend-install . arguments

Install the project’s dependencies, passing ARGUMENTS to the manager.

Procedure: frontend-lint . arguments

Run the ‘lint’ script, passing ARGUMENTS to it.

Procedure: frontend-output argv KEY: #:allow-failure?

Run the frontend ARGV and return its standard output as a string.

A query runs even in a dry run: it reads the project rather than changing it – ‘npm pkg get version’ is the usual one. A failure raises a maak error naming the command, or comes back as #f when the caller asked for the exit status.

Procedure: frontend-publish . arguments

Publish the package, passing ARGUMENTS to the manager.

A dry run of the release is ‘(frontend-publish "–dry-run")’: npm’s own flag is what makes it one, while maak’s dry run prints the command instead.

Procedure: frontend-remove packages KEY: #:arguments

Remove PACKAGES from the dependencies.

PACKAGES is one name or a list of them; ARGUMENTS are the manager’s own words.

Procedure: frontend-run script . arguments

Run the package.json SCRIPT, passing ARGUMENTS to it.

‘run’ is the one verb all three managers spell the same way, so this is the wrapper a task reads best with. The words after SCRIPT go to the script, so a task that forwards a flag writes them after it:

(frontend-run "build")
(frontend-run "test" "--" "--watch")
Procedure: frontend-test . arguments

Run the ‘test’ script, passing ARGUMENTS to it.

Procedure: package-dependencies

Return the dependencies package.json declares, with the ranges it gives them.

Procedure: package-dev-dependencies

Return the development dependencies package.json declares.

Procedure: package-json OPT: path

Return PATH read as JSON, a string-keyed alist, in file order.

The file is read even in a dry run, like pkg-config: it describes the project rather than changing it, and the version a publish would use is in it.

Procedure: package-manager-kind OPT: manager

Return the package manager MANAGER runs, as one of ‘npm’, ‘pnpm’ or ‘yarn’.

MANAGER is the program, so a wrapper is read from its last word: ‘"corepack pnpm"’ is pnpm. A name this module has no spelling for is a maak error rather than a guess, because the verbs differ and a wrong one would install something the project did not ask for.

Procedure: package-name

Return the name package.json gives the package.

Procedure: package-scripts

Return the names of the scripts package.json defines, in file order.

Procedure: package-version

Return the version package.json gives the package.


1.12 (maak git)

The git commands a project’s Maak file usually wants, and the source archives it usually ships, as procedures rather than tasks. A Maak file decides which of them to expose, and under which names:

(define-module (maak) #:use-module (maak git))

(define (commit message) "Commit every tracked change." (git-commit message))

Every command goes through ‘run’, which hands the arguments to git as a list: a commit message with spaces or quotes reaches git as one argument, and no shell splits it again. Nothing here assumes a project layout – the archive helpers take the file name and the prefix, and ‘git’ itself takes ‘#:directory’ – so the same procedures serve a checkout here and one elsewhere.

‘git-output’ is the reading counterpart of ‘git’: it runs the same command and returns what git printed, which is what a task needs to make a decision (the current branch, the tags, whether the tree is dirty) rather than merely to show the user the output.

A command that fails stops the task with git’s own message and a maak error naming the command, the way any other ‘run’ does.

1.12.1 Overview

  • git — Run git with ARGUMENTS, a list of strings, in DIRECTORY.
  • git-add — Stage PATHS, or every change in the tree when none is named.
  • git-archive — Write REVISION as OUTPUT with git archive, under PREFIX, in FORMAT.
  • git-archive-tar — Write REVISION as the gzipped tarball OUTPUT, under PREFIX.
  • git-archive-zip — Write REVISION as the zip OUTPUT, under PREFIX.
  • git-argv — Return the argv that runs git with ARGUMENTS in DIRECTORY.
  • git-branch — List the branches, or create the branches NAMES name.
  • git-checkout — Run git checkout with ARGUMENTS.
  • git-cherry-pick — Cherry-pick with any arguments git cherry-pick takes.
  • git-clean — Remove untracked files with any arguments git clean takes.
  • git-clone — Clone URL into DIRECTORY, with BRANCH, DEPTH or BARE? when given.
  • git-commit — Commit with MESSAGE, every tracked change by default.
  • git-config — Read or write configuration with any arguments git config takes.
  • git-current-branch — Return the branch the checkout in DIRECTORY is on.
  • git-current-revision — Return the full hash of the commit checked out in DIRECTORY.
  • git-describe — Describe a commit, with any arguments git describe takes.
  • git-describe-tag — Return the most recent tag reachable from HEAD in DIRECTORY.
  • git-diff — Show the changes between the working tree and the index, or as ARGUMENTS say.
  • git-dirty? — Return #t when the checkout in DIRECTORY has anything uncommitted.
  • git-fetch — Fetch from the remote, with any arguments git fetch takes.
  • git-init — Initialise a git repository here, with any arguments git init takes.
  • git-log — Show the history as a decorated one-line graph, twenty commits by default.
  • git-merge — Merge with any arguments git merge takes.
  • git-output — Run git with ARGUMENTS in DIRECTORY and return what it printed.
  • git-pull — Pull from the upstream branch, with any arguments git pull takes.
  • git-push — Push the current branch, with any arguments git push takes.
  • git-rebase — Rebase with any arguments git rebase takes.
  • git-remote — Manage remotes with any arguments git remote takes.
  • git-remote-url — Return the URL configured for remote NAME in DIRECTORY.
  • git-remotes — Return the names of the remotes configured in DIRECTORY, sorted.
  • git-reset — Reset with any arguments git reset takes.
  • git-restore — Restore paths with any arguments git restore takes.
  • git-rev-parse — Ask git about revisions, with any arguments git rev-parse takes.
  • git-revert — Revert with any arguments git revert takes.
  • git-show — Show a commit, tag or other object, with any arguments git show takes.
  • git-stash — Stash with any arguments git stash takes.
  • git-status — Show the current branch and a short status of the working tree.
  • git-submodule — Manage submodules with any arguments git submodule takes.
  • git-switch — Switch to BRANCH, creating it with CREATE? or discarding local changes with
  • git-tag — Tag the current commit as NAME, without an annotation unless MESSAGE is given.
  • git-tags — Return the names of the tags in DIRECTORY, sorted.

1.12.2 Procedures

Procedure: git arguments KEY: #:directory #:allow-failure? #:verbose?

Run git with ARGUMENTS, a list of strings, in DIRECTORY.

This is what every wrapper below is made of, and the way to reach a command that has no wrapper – git fetch, git reset, a subcommand added tomorrow. Nothing is handed to a shell, so a value with spaces in it stays one argument.

(git (list "fetch" "--all"))
(git (list "log" "--oneline" "-3") #:directory "/path/to/checkout")

A command that exits non-zero raises a maak error naming it, unless ALLOW-FAILURE? is #t, in which case the call answers #f.

Procedure: git-add . paths

Stage PATHS, or every change in the tree when none is named.

Procedure: git-archive output KEY: #:format #:prefix #:revision #:directory

Write REVISION as OUTPUT with git archive, under PREFIX, in FORMAT.

FORMAT is one git archive understands, tar.gz and zip being the usual ones. PREFIX is the directory the archive unpacks into, and it carries its own trailing slash. DIRECTORY is the checkout to read from.

(git-archive "maak-1.0.tar.gz" #:prefix "maak-1.0/")
Procedure: git-archive-tar output KEY: #:prefix #:revision #:directory

Write REVISION as the gzipped tarball OUTPUT, under PREFIX.

Procedure: git-archive-zip output KEY: #:prefix #:revision #:directory

Write REVISION as the zip OUTPUT, under PREFIX.

Procedure: git-argv arguments KEY: #:directory

Return the argv that runs git with ARGUMENTS in DIRECTORY.

The checkout is named with -C rather than by changing maak’s working directory, so a task can read another checkout without disturbing its own. Exposed because the argument list is the interface every wrapper shares: a test can assert it, and a caller can log or extend it without running git.

Procedure: git-branch . names

List the branches, or create the branches NAMES name.

Procedure: git-checkout . arguments

Run git checkout with ARGUMENTS.

For a branch, git-switch says what it means; this wrapper is for the rest of git checkout – restoring paths, detached commits, --orphan.

Procedure: git-cherry-pick . arguments

Cherry-pick with any arguments git cherry-pick takes.

Procedure: git-clean . arguments

Remove untracked files with any arguments git clean takes.

git clean does nothing without -f; pass it, and -d for directories, because there is no safer default that would still be useful.

Procedure: git-clone url KEY: #:directory #:branch #:depth #:bare? #:verbose?

Clone URL into DIRECTORY, with BRANCH, DEPTH or BARE? when given.

git clone is the one command that cannot be pointed at a checkout with -C, because the checkout it makes is the destination; the destination is therefore the final argument rather than a decoration. Without DIRECTORY git names the directory after the repository, exactly as it does on the command line.

(git-clone "https://example.org/project.git" #:depth 1)
(git-clone "../other" #:directory "vendor/other" #:branch "trunk")
Procedure: git-commit message KEY: #:all? #:amend? #:allow-empty? #:sign?

Commit with MESSAGE, every tracked change by default.

ALL? is the -a that stages modified and deleted tracked files without a separate git add; it is #t for the common case of committing the working tree. AMEND? replaces the last commit, ALLOW-EMPTY? makes a commit with no changes, and SIGN? signs it with the configured GPG key.

(git-commit "fix: keep the config when it is missing")
(git-commit "docs: typo" #:all? #f)     ;; commit only what is staged
Procedure: git-config . arguments

Read or write configuration with any arguments git config takes.

Procedure: git-current-branch KEY: #:directory

Return the branch the checkout in DIRECTORY is on.

A detached HEAD answers with the revision rather than the word HEAD, so a task that tags a release from CI still gets something it can record.

Procedure: git-current-revision KEY: #:directory

Return the full hash of the commit checked out in DIRECTORY.

Procedure: git-describe . arguments

Describe a commit, with any arguments git describe takes.

Procedure: git-describe-tag KEY: #:directory

Return the most recent tag reachable from HEAD in DIRECTORY.

(git-describe-tag)   ;; => v0.10.0
Procedure: git-diff . arguments

Show the changes between the working tree and the index, or as ARGUMENTS say.

Use --cached to compare the index with the last commit, or name two revisions to compare them with each other.

Procedure: git-dirty? KEY: #:directory

Return #t when the checkout in DIRECTORY has anything uncommitted.

Both staged and unstaged changes count, as do untracked files: this is the question git status --porcelain answers, rather than the narrower one git diff --quiet answers.

Procedure: git-fetch . arguments

Fetch from the remote, with any arguments git fetch takes.

Procedure: git-init . arguments

Initialise a git repository here, with any arguments git init takes.

Procedure: git-log . arguments

Show the history as a decorated one-line graph, twenty commits by default.

Procedure: git-merge . arguments

Merge with any arguments git merge takes.

Procedure: git-output arguments KEY: #:directory #:allow-failure?

Run git with ARGUMENTS in DIRECTORY and return what it printed.

This is the reading half of git: the output is a string the task can trim, split and compare, not a line on the terminal. A command that exits non-zero raises, unless ALLOW-FAILURE? is #t, in which case the partial output is returned – the same contract as capture. In dry-run mode nothing runs, the command is printed, and the empty string comes back.

(string-trim (git-output (list "rev-parse" "--abbrev-ref" "HEAD")))
Procedure: git-pull . arguments

Pull from the upstream branch, with any arguments git pull takes.

Procedure: git-push . arguments

Push the current branch, with any arguments git push takes.

A bare push does not send tags that are not annotated; (git-push "--tags") sends them too.

Procedure: git-rebase . arguments

Rebase with any arguments git rebase takes.

Procedure: git-remote . arguments

Manage remotes with any arguments git remote takes.

(git-remote (list "add" "origin" "https://example.org/project.git"))
(git-remote (list "-v"))
Procedure: git-remote-url name KEY: #:directory

Return the URL configured for remote NAME in DIRECTORY.

Procedure: git-remotes KEY: #:directory

Return the names of the remotes configured in DIRECTORY, sorted.

Procedure: git-reset . arguments

Reset with any arguments git reset takes.

--soft and --mixed keep the changes; --hard throws them away, which is what makes this wrapper worth naming explicitly in a task.

Procedure: git-restore . arguments

Restore paths with any arguments git restore takes.

Procedure: git-rev-parse . arguments

Ask git about revisions, with any arguments git rev-parse takes.

Procedure: git-revert . arguments

Revert with any arguments git revert takes.

Procedure: git-show . arguments

Show a commit, tag or other object, with any arguments git show takes.

Procedure: git-stash . arguments

Stash with any arguments git stash takes.

The bare call saves the working tree; pass pop to bring it back, or list to see what is saved.

Procedure: git-status

Show the current branch and a short status of the working tree.

Procedure: git-submodule . arguments

Manage submodules with any arguments git submodule takes.

Procedure: git-switch branch KEY: #:create? #:force?

Switch to BRANCH, creating it with CREATE? or discarding local changes with FORCE? when asked.

git switch is the modern spelling of the checkout half of git checkout: it changes branches and nothing else, which is why it is the default here.

Procedure: git-tag name KEY: #:message #:force?

Tag the current commit as NAME, without an annotation unless MESSAGE is given.

An annotated tag is what git push --follow-tags and most release tooling expects, so passing MESSAGE is the usual choice for a release; a lightweight tag is the default because it changes nothing in the history.

(git-tag "v1.2.0" #:message "maak 1.2.0")
Procedure: git-tags KEY: #:directory

Return the names of the tags in DIRECTORY, sorted.


1.13 (maak gradle)

Gradle helpers: the tasks a JVM project runs, as argv a task can inspect.

As with Maven and Cargo, the builder is pure and the runner feeds it to ‘run’, so ‘–dry-run’ prints the invocation and ‘–plan’ records it. The daemon, the build cache and the parallel flag are opt-in keywords because they are decisions about a machine rather than about the project.

The program is a parameter, honoured from MAAK_GRADLE then GRADLE, and a checkout’s ‘gradlew’ is what ‘gradle-wrapper-command’ answers, because that is the Gradle version the project pins. A task opts in with ‘(parameterize ((gradle-command (gradle-wrapper-command))) ...)’.

1.13.1 Overview

1.13.2 Parameters

Parameter: gradle-command

Default value:

"gradle"

1.13.3 Procedures

Procedure: gradle tasks . options

Run the Gradle TASKS, forwarding OPTIONS to ‘gradle-argv’.

(gradle "test" #:arguments '("--tests" "*Integration*"))
Procedure: gradle-argv tasks KEY: #:arguments #:project-dir #:build-file #:properties #:exclude-tasks #:offline? #:refresh-dependencies? #:no-daemon? #:parallel? #:build-cache? #:rerun-tasks? #:continue? #:stacktrace? #:full-stacktrace? #:warning-mode #:console #:quiet? #:info? #:debug? #:max-workers

Return the argv that runs the Gradle TASKS, without running it.

TASKS is a task name or a list of them, as Gradle spells them (‘:module:task‘ included). PROJECT-DIR and BUILD-FILE choose the build; PROPERTIES become ‘-P’ words; EXCLUDE-TASKS become ‘-x’ words. The daemon, cache, parallel and rerun flags are keywords, because they decide how a machine runs the build. ARGUMENTS are appended as they are.

(gradle-argv '("clean" "build")
             #:project-dir "service"
             #:properties '(("version" . "1.2.3"))
             #:no-daemon? #t)
⇒ ("gradle" "--project-dir" "service" "-Pversion=1.2.3"
           "--no-daemon" "clean" "build")
Procedure: gradle-assemble . arguments

Assemble the project’s artefacts, passing ARGUMENTS.

Procedure: gradle-build . arguments

Run the full build, passing ARGUMENTS.

Procedure: gradle-check . arguments

Run the checks, passing ARGUMENTS.

Procedure: gradle-clean . arguments

Remove the build output, passing ARGUMENTS.

Procedure: gradle-dependencies . arguments

Print the dependency report, passing ARGUMENTS.

Procedure: gradle-output argv KEY: #:allow-failure?

Run the Gradle ARGV and return its standard output.

A query runs even in a dry run, because it reads the project rather than changing it.

Procedure: gradle-projects . arguments

List the project’s modules, passing ARGUMENTS.

Procedure: gradle-publish . arguments

Publish the artefacts, passing ARGUMENTS.

Procedure: gradle-run . arguments

Run the application task, passing ARGUMENTS.

Procedure: gradle-tasks . arguments

List the project’s tasks, passing ARGUMENTS.

Procedure: gradle-test . arguments

Run the tests, passing ARGUMENTS.

Procedure: gradle-wrapper-command OPT: directory

Return the Gradle command to use in DIRECTORY.

A checkout with an executable ‘gradlew’ answers with it, because that is the Gradle version the project pins; otherwise the answer is ‘gradle-command’.

Procedure: gradle-wrapper? OPT: directory

Return #t when DIRECTORY holds an executable Gradle wrapper.


1.14 (maak guix)

Guix asked for values. The helpers in ‘(maak dsl)’ build command lines – ‘guix shell’, ‘guix pack’, ‘guix time-machine’ – because that is what a task usually wants: the environment, the container, the binary. The helpers here answer the other question: what *is* the package at this-pin, and where did building it put the result? ‘guix time-machine’ answers that by starting a whole second Guix; a Scheme program can ask it directly, and keep the answer as a value.

The asking happens in ‘guix repl’, which is Guix’s own Guile with Guix’s own modules on the load path. Nothing in maak imports ‘(guix ...)‘: a maak built on a machine without Guix has to compile and run exactly like one built with it, so the dependency is on the *program* at the moment a task calls one of these, not on the build. A machine without Guix gets a one-line error with a hint, from the call that needed it, and every other part of maak is unaffected.

The price is a process per query: about a third of a second for the repl plus the store connection. ‘cached-channel-instance’ keeps the second query against the same pins cheap, because the channel checkout is already in the store.

1.14.1 Overview

  • guix-available? — Return #t when a ‘guix’ program is on ‘PATH’.
  • guix-build — Build PACKAGE as CHANNELS pins it and return its output path.
  • guix-build-at — Build PACKAGE at Guix REVISION and return its output path.
  • guix-channels — Return the channel pins FILE names, as an alist of name and commit.
  • guix-derivation — Return the derivation file name of PACKAGE as CHANNELS pins it.
  • guix-derivation-at — Return the derivation file name of PACKAGE at Guix REVISION.
  • guix-program — Run a program from PACKAGE as CHANNELS pins it.
  • guix-program-at — Run a program from PACKAGE, built by Guix REVISION, with ARGS.

1.14.2 Procedures

Procedure: guix-available?

Return #t when a ‘guix’ program is on ‘PATH’.

Procedure: guix-build package KEY: #:channels #:system

Build PACKAGE as CHANNELS pins it and return its output path.

Building is what makes the answer usable: the output path is the directory the package installed into, with its ‘bin’, ‘lib’ and ‘share’ underneath.

(guix-build "hello")
⇒ "/gnu/store/…-hello-2.12.3"

Guix’s own build log goes to standard error as it does for ‘guix build’, so a long build still shows its progress.

Procedure: guix-build-at revision package KEY: #:url #:system

Build PACKAGE at Guix REVISION and return its output path.

The pinned form of ‘guix-build’: REVISION is a commit of the Guix repository at URL, and no channels file is read.

Procedure: guix-channels KEY: #:file

Return the channel pins FILE names, as an alist of name and commit.

(guix-channels)
⇒ (("guix" . "0fb918d61609f3aadc2d8ecc212926b3bdfabb4c"))

The file is a normal ‘channels.scm’, the one ‘guix describe -f channels’ writes; the answer names every channel it lists, in the order they appear. This is the pin the ‘-at’ helpers replace, and the one ‘guix time-machine’ would read.

Procedure: guix-derivation package KEY: #:channels #:system

Return the derivation file name of PACKAGE as CHANNELS pins it.

PACKAGE is a package name, looked up in the Guix that CHANNELS names rather than in the one running. SYSTEM is the target system, or #f for this machine’s. Nothing is built: the derivation is the recipe, and its file name is enough for ‘guix build’ or for a later ‘build-derivations’.

(guix-derivation "hello")
⇒ "/gnu/store/…-hello-2.12.3.drv"

A channels file that has never been fetched is fetched here, with the network and the time that takes; afterwards Guix’s channel cache answers at once.

Procedure: guix-derivation-at revision package KEY: #:url #:system

Return the derivation file name of PACKAGE at Guix REVISION.

REVISION is a commit of the Guix repository at URL, which defaults to the canonical one. This is the ‘guix time-machine –commit=REVISION’ question asked as a value: which Guix is not the one running, and no channels file has to exist for it.

(guix-derivation-at "0fb918d61609f3aadc2d8ecc212926b3bdfabb4c" "hello")
Procedure: guix-program package args KEY: #:program #:channels #:system #:verbose? #:env #:sudo? #:dev-null? #:allow-failure? #:async?

Run a program from PACKAGE as CHANNELS pins it.

ARGS are the arguments the program gets, each a string. PROGRAM names the program inside the package’s output and defaults to the package’s own name: a bare name is looked for in ‘bin’, and a name with a slash in it is taken as a path from the output’s root. The package is built first, so the program that runs is the one that pin names and not whatever the machine happens to have installed.

(guix-program "hello" '("--version"))
(guix-program "coreutils" '("-l" "/gnu/store") #:program "ls")
(guix-program "diffutils" (list "-u" a b) #:program "diff" #:async? #t)

The decorations are ‘run”s: ‘#:env’, ‘#:sudo?’, ‘#:dev-null?’, ‘#:allow-failure?’ and ‘#:async?’, so the program can be a job like any other.

In a dry run the store query is printed instead of the program line, because the path is only known once Guix has answered; #t is returned.

Procedure: guix-program-at revision package args KEY: #:program #:url #:system #:verbose? #:env #:sudo? #:dev-null? #:allow-failure? #:async?

Run a program from PACKAGE, built by Guix REVISION, with ARGS.

The pinned form of ‘guix-program’: the package comes from the Guix at REVISION of URL rather than from the pinned channels file, which is what a task wants when it has to run one old tool for one step. PROGRAM and the decorations are ‘guix-program”s.

(guix-program-at "0fb918d61609f3aadc2d8ecc212926b3bdfabb4c"
                 "hello" '(--version))

1.15 (maak i18n)

The gettext workflow, packaged as maak builtins.

Keeping a program translated means running the same four GNU gettext tools in the same order – ‘xgettext’ to gather the strings, ‘msginit’ to start a language, ‘msgmerge’ to fold new strings into it, and ‘msgfmt’ to compile the catalogue the program actually loads. Every project ends up writing those invocations by hand in its maak file; this module writes them once.

The layout is the conventional one:

DIR/TEXTDOMAIN.pot the template DIR/LANG/LC_MESSAGES/TEXTDOMAIN.po one language DIR/LANG/LC_MESSAGES/TEXTDOMAIN.mo the compiled catalogue

so a project that follows the convention only names its DIR, its TEXTDOMAIN, and the LANGUAGES it ships.

1.15.1 Overview

  • i18n-compile — Compile LANGUAGE’s .po file into the .mo catalogue the program loads.
  • i18n-compile-all — Run ‘i18n-compile’ for every language of LANGUAGES, skipping missing files.
  • i18n-extract — Extract translatable strings from source files into the .pot template.
  • i18n-init — Create LANGUAGE’s .po file from the .pot template.
  • i18n-init-all — Run ‘i18n-init’ for every language of LANGUAGES.
  • i18n-language — Return the language the process should translate into.
  • i18n-locale-dir — Return the catalogue directory of LANGUAGE inside DIR.
  • i18n-merge — Fold the current .pot template into LANGUAGE’s .po file, in place.
  • i18n-merge-all — Run ‘i18n-merge’ for every language of LANGUAGES, skipping missing files.
  • i18n-mo-file — Return the path of LANGUAGE’s compiled machine object file (the one the program loads).
  • i18n-po-file — Return the path of LANGUAGE’s portable object file (the one a translator edits).
  • i18n-pot-file — Return the path of the template TEXTDOMAIN.pot inside DIR.
  • i18n-refresh — Do the whole gettext cycle: extract, merge, then compile.
  • i18n-source-globs — Return the file patterns of DIRECTORIES that ‘xgettext’ should read.
  • i18n-translator — Install the catalogue in DIR for TEXTDOMAIN and return a translate procedure.

1.15.2 Procedures

Procedure: i18n-compile language KEY: #:dir #:textdomain #:verbose?

Compile LANGUAGE’s .po file into the .mo catalogue the program loads.

Procedure: i18n-compile-all languages KEY: #:dir #:textdomain #:verbose?

Run ‘i18n-compile’ for every language of LANGUAGES, skipping missing files.

Procedure: i18n-extract KEY: #:dir #:textdomain #:directories #:extensions #:keywords #:copyright-holders #:package-name #:from-code #:update? #:verbose?

Extract translatable strings from source files into the .pot template.

DIRECTIONS is the list of directories to scan, EXTENSIONS the file types in them, and KEYWORDS the function names xgettext should treat as translatable (‘G_’ by default). With UPDATE? the strings are joined into an existing template instead of starting a fresh one, which keeps translator comments and previous line references.

(i18n-extract #:directories '("lib" "app/views"))
Procedure: i18n-init language KEY: #:dir #:textdomain #:verbose?

Create LANGUAGE’s .po file from the .pot template.

The language directory is created when missing, so a new translation starts with one call. LANGUAGE is a locale name such as nl_NL.

Procedure: i18n-init-all languages KEY: #:dir #:textdomain #:only-missing? #:verbose?

Run ‘i18n-init’ for every language of LANGUAGES.

With ONLY-MISSING? (the default) a language whose .po already exists is skipped, so the call can live in a task that is run repeatedly without clobbering translators’ work with a fresh template.

Procedure: i18n-language

Return the language the process should translate into.

The first of ‘LANGUAGE’, ‘LC_ALL’, ‘LC_MESSAGES’ and ‘LANG’ that is set, with its character encoding and any modifier stripped; when none is set, ‘en_US’ is assumed.

Procedure: i18n-locale-dir language KEY: #:dir

Return the catalogue directory of LANGUAGE inside DIR.

(i18n-locale-dir "nl_NL")
⇒ "po/nl_NL/LC_MESSAGES"
Procedure: i18n-merge language KEY: #:dir #:textdomain #:verbose?

Fold the current .pot template into LANGUAGE’s .po file, in place.

Procedure: i18n-merge-all languages KEY: #:dir #:textdomain #:verbose?

Run ‘i18n-merge’ for every language of LANGUAGES, skipping missing files.

Procedure: i18n-mo-file language KEY: #:dir #:textdomain

Return the path of LANGUAGE’s compiled machine object file (the one the program loads).

Procedure: i18n-po-file language KEY: #:dir #:textdomain

Return the path of LANGUAGE’s portable object file (the one a translator edits).

Procedure: i18n-pot-file KEY: #:dir #:textdomain

Return the path of the template TEXTDOMAIN.pot inside DIR.

Procedure: i18n-refresh languages KEY: #:dir #:textdomain #:directories #:extensions #:keywords #:copyright-holders #:package-name #:verbose?

Do the whole gettext cycle: extract, merge, then compile.

This is the one call a project normally puts in its maak file; the individual steps stay available for anything more unusual.

Procedure: i18n-source-globs directories KEY: #:extensions

Return the file patterns of DIRECTORIES that ‘xgettext’ should read.

A glob that matches nothing is handed to xgettext as itself, and xgettext refuses the whole invocation over the missing file – writing no template at all rather than the strings it did find. Only directories that exist are therefore asked for, so adding or removing a source tree is all a refresh ever needs.

(i18n-source-globs '("lib" "app/views"))
Procedure: i18n-translator KEY: #:dir #:textdomain #:language

Install the catalogue in DIR for TEXTDOMAIN and return a translate procedure.

The returned procedure takes one message and returns its translation, falling back to the original when the catalogue has no entry. LANGUAGE defaults to ‘i18n-language’.

(define G_ (i18n-translator #:dir "po" #:textdomain "maak"))
(G_ "Hello")

1.16 (maak maak)

1.16.1 Overview

  • get-module-var — Get a variable from the currently loaded maak file module.
  • job-command — An undocumented macro.
  • job-pid — An undocumented macro.
  • job? — An undocumented macro.
  • pipeline-errors — An undocumented macro.
  • pipeline-outputs — An undocumented macro.
  • pipeline-result? — An undocumented macro.
  • stage? — An undocumented macro.
  • text — An undocumented macro.
  • ar-command — A parameter object.
  • banner? — A parameter object.
  • c-compiler — A parameter object.
  • cargo-command — A parameter object.
  • container-compose-command — A parameter object.
  • container-engine — A parameter object.
  • cxx-compiler — A parameter object.
  • dry-run? — A parameter object.
  • elevation-command — A parameter object.
  • emacs-command — A parameter object.
  • fetch-command — A parameter object.
  • gradle-command — A parameter object.
  • maak-load-path — A parameter object.
  • maven-command — A parameter object.
  • package-json-file — A parameter object.
  • package-manager — A parameter object.
  • pkg-config-command — A parameter object.
  • pyproject-file — A parameter object.
  • python-command — A parameter object.
  • quiet? — A parameter object.
  • rustup-command — A parameter object.
  • sift-command — A parameter object.
  • uv-command — A parameter object.
  • uvx-command — A parameter object.
  • $ — Executes a shell command constructed from a list of strings.
  • add-load-path! — Prepend DIR to Guile’s load path and record it as a maak load path.
  • add-load-paths! — Prepend every directory of DIRS to the load path, in order.
  • available-task-names — Return the names of the tasks maak can currently run, sorted.
  • bold-output — Return X emphasised for a terminal, or X unchanged when styling is off.
  • bundle — Build a self-contained bundle of NAME’s automation and return its path.
  • bundle-file-name — Return the file name a bundle of NAME in PACK-FORMAT is written to.
  • bundle-script — Return the Guix package file that defines a bundle for NAME.
  • capture — Run COMMAND and return its standard output as a string.
  • cargo — Run cargo SUBCOMMAND with ARGUMENTS, as separate words.
  • cargo-argv — Return the argv that runs cargo SUBCOMMAND, without running it.
  • cargo-artifact-path — Return where cargo writes the artefact called NAME.
  • cargo-bench — Run the benchmarks with cargo, passing ARGUMENTS.
  • cargo-binaries — Return the names of the binary targets of PACKAGE, or of the only package.
  • cargo-build — Build the package with cargo, passing ARGUMENTS.
  • cargo-check — Type-check the package with cargo, passing ARGUMENTS.
  • cargo-clean — Remove the build artefacts with cargo, passing ARGUMENTS.
  • cargo-clippy — Lint the package with ‘cargo clippy’, passing ARGUMENTS.
  • cargo-doc — Build the documentation with cargo, passing ARGUMENTS.
  • cargo-fetch — Fetch the dependencies with cargo, passing ARGUMENTS.
  • cargo-fmt — Format the sources with ‘cargo fmt’, passing ARGUMENTS.
  • cargo-install — Install a cargo binary, passing ARGUMENTS.
  • cargo-metadata — Return ‘cargo metadata’ as parsed JSON, a string-keyed alist.
  • cargo-output — Run the cargo ARGV and return its standard output as a string.
  • cargo-package — Return the metadata of one package, or raise when it cannot be chosen.
  • cargo-package-names — Return the names of the packages in the workspace, in cargo’s order.
  • cargo-package-version — Return the version cargo reports for PACKAGE, or for the only package.
  • cargo-publish — Publish the package with cargo, passing ARGUMENTS.
  • cargo-run — Run the binary with cargo; put the program’s own words after "–".
  • cargo-target-directory — Return the directory cargo writes its artefacts into.
  • cargo-test — Run the tests with cargo, passing ARGUMENTS.
  • cargo-update — Update the dependencies with cargo, passing ARGUMENTS.
  • cat — Print FILE to standard output.
  • cd — Change the process working directory to DIR and return it.
  • chmod-file — Change the permissions of FILE to MODE, an octal string such as 755.
  • command-exists? — Return #t when COMMAND can be found on ‘PATH’.
  • command-on-path? — Return #t when COMMAND is an executable in one of the directories in PATH.
  • compile — Compile SOURCE to OUTPUT, or to SOURCE’s ‘.o’ beside it.
  • compile-argv — Return the argv that compiles SOURCE to OUTPUT, without running it.
  • compile-objects — Compile every SOURCE to its object under DIRECTORY, up to JOBS at once.
  • compiler-for — Return the compiler for LANGUAGE as a list of words.
  • compose-argv — Return the argv that runs Compose with ARGUMENTS.
  • compose-available? — Return #t when the Compose PROGRAM can be found on PATH.
  • compose-build — Build SERVICES with Compose; see ‘compose-build-argv‘.
  • compose-build-argv — Return the argv that builds SERVICES, or every service when it is empty.
  • compose-config — Render the Compose configuration; see ‘compose-config-argv‘.
  • compose-config-argv — Return the argv that renders the resolved Compose configuration.
  • compose-down — Stop and remove SERVICES with Compose; see ‘compose-down-argv‘.
  • compose-down-argv — Return the argv that stops and removes SERVICES, or the whole project.
  • compose-exec — Run COMMAND in SERVICE with Compose; see ‘compose-exec-argv‘.
  • compose-exec-argv — Return the argv that runs COMMAND in SERVICE.
  • compose-logs — Print the logs of SERVICES with Compose; see ‘compose-logs-argv‘.
  • compose-logs-argv — Return the argv that prints the logs of SERVICES, or of the whole project.
  • compose-output — Run Compose with ARGUMENTS and return its output as a string.
  • compose-ps — List the containers of SERVICES with Compose; see ‘compose-ps-argv‘.
  • compose-ps-argv — Return the argv that lists the containers of SERVICES, or of the project.
  • compose-pull — Pull the images of SERVICES with Compose; see ‘compose-pull-argv‘.
  • compose-pull-argv — Return the argv that pulls the images of SERVICES.
  • compose-restart — Restart SERVICES with Compose; see ‘compose-restart-argv‘.
  • compose-restart-argv — Return the argv that restarts SERVICES.
  • compose-run — Run COMMAND in a one-off container for SERVICE; see ‘compose-run-argv‘.
  • compose-run-argv — Return the argv that runs COMMAND in a one-off container for SERVICE.
  • compose-up — Start SERVICES with Compose; see ‘compose-up-argv‘.
  • compose-up-argv — Return the argv that starts SERVICES, or every service when it is empty.
  • container — Run ENGINE with ARGUMENTS, a list of strings.
  • container-argv — Return the argv that runs ENGINE with ARGUMENTS.
  • container-available? — Return #t when ENGINE can be found on PATH.
  • container-build — Build the image described by CONTEXT; see ‘container-build-argv‘.
  • container-build-argv — Return the argv that builds the image described by CONTEXT.
  • container-exec — Run COMMAND in the container NAME; see ‘container-exec-argv‘.
  • container-exec-argv — Return the argv that runs COMMAND in the container NAME.
  • container-images — List images; see ‘container-images-argv‘.
  • container-images-argv — Return the argv that lists images, with any extra ARGUMENTS.
  • container-inspect — Inspect NAMES; see ‘container-inspect-argv‘.
  • container-inspect-argv — Return the argv that inspects NAMES.
  • container-logs — Print the logs of the container NAME; see ‘container-logs-argv‘.
  • container-logs-argv — Return the argv that prints the logs of the container NAME.
  • container-output — Run ENGINE with ARGUMENTS and return its output as a string.
  • container-ps — List containers; see ‘container-ps-argv‘.
  • container-ps-argv — Return the argv that lists containers, including stopped ones with ALL?.
  • container-pull — Pull IMAGE; see ‘container-pull-argv‘.
  • container-pull-argv — Return the argv that pulls IMAGE.
  • container-push — Push IMAGE; see ‘container-push-argv‘.
  • container-push-argv — Return the argv that pushes IMAGE.
  • container-rm — Remove the containers NAMES; see ‘container-rm-argv‘.
  • container-rm-argv — Return the argv that removes the containers NAMES.
  • container-run — Run IMAGE as a container; see ‘container-run-argv‘ for the options.
  • container-run-argv — Return the argv that runs IMAGE as a container.
  • container-stop — Stop the containers NAMES, a list of strings.
  • container-stop-argv — Return the argv that stops the containers NAMES.
  • container-tag — Tag SOURCE as TARGET; see ‘container-tag-argv‘.
  • container-tag-argv — Return the argv that gives SOURCE the additional name TARGET.
  • cp — Copy a file or directory from X to Y.
  • curl — Run curl with ARGUMENTS, a list of strings; see ‘curl-argv’.
  • curl-argv — Return the argv that runs curl with ARGUMENTS.
  • curl-download — Download URL with curl; see ‘curl-download-argv’.
  • curl-download-argv — Return the argv that downloads URL to OUTPUT.
  • curl-get — Fetch URL with curl; see ‘curl-get-argv’ for the options.
  • curl-get-argv — Return the argv that fetches URL with curl.
  • curl-head — Ask for URL’s headers with curl; see ‘curl-head-argv’.
  • curl-head-argv — Return the argv that asks for URL’s headers with a HEAD request.
  • curl-output — Run curl with ARGUMENTS and return what it printed.
  • curl-post — Send a POST request to URL; see ‘curl-post-argv’.
  • curl-post-argv — Return the argv that sends a POST request to URL.
  • curl-status — Return URL’s HTTP status code as a number.
  • curl-status-argv — Return the argv that prints URL’s HTTP status code.
  • curl-text — Fetch URL with curl and return the body as a string.
  • curl-text-argv — Return the argv that fetches URL’s body for a task to read.
  • curl-upload — Upload FILE to URL with curl; see ‘curl-upload-argv’.
  • curl-upload-argv — Return the argv that uploads FILE to URL with curl.
  • decorate-command — Return CMD with the decorations a task asked for, applied in a fixed order.
  • dedent-string — Remove the common leading indentation from a multiline STR.
  • delete-file-recursively — Delete a directory and all its contents recursively.
  • detect-compose-command — Return the words that run Compose, as a list.
  • detect-container-engine — Return the container engine maak should use.
  • detect-elevation-command — Return the command maak should use to run something as root.
  • detect-fetch-command — Return the download program ‘download’ should use.
  • detect-package-manager — Return the package manager DIRECTORY pins, named as its program is.
  • download — Download URL with the detected downloader.
  • elisp-byte-compile — Byte-compile FILES in batch, with LOAD-PATHS on the load path.
  • elisp-checkdoc — Run ‘checkdoc’ on FILES in batch, with LOAD-PATHS on the load path.
  • elisp-ert — Load TEST-FILES and run the ERT tests matching SELECTOR in batch.
  • elisp-feature — Return the first feature PATH provides, or #f.
  • elisp-files — Return every ‘.el’ file under DIRECTORY, recursively, sorted.
  • elisp-footer? — Return #t when PATH carries its ‘;;; FILE ends here’ footer.
  • elisp-header — Return the value of the ‘;; FIELD:’ header in PATH, or #f.
  • elisp-lexical-binding? — Return #t when PATH sets lexical-binding on its first line.
  • elisp-package-requires — Return the ‘;; Package-Requires:’ header of PATH as it is written, or #f.
  • elisp-package-version — Return the ‘;; Version:’ header of PATH, or #f.
  • elisp-practices — Return the conventions PATH is missing, as a list of sentences.
  • elisp-practices-ok? — Return #t when PATH keeps every convention ‘elisp-practices’ checks.
  • elisp-provides — Return the features PATH provides, as written by ‘(provide ...)’.
  • elisp-quote — Return TEXT as an Emacs Lisp string literal.
  • elisp-version — Return the Emacs version the configured program reports.
  • emacs-batch — Run Emacs in batch, forwarding OPTIONS to ‘emacs-batch-argv’.
  • emacs-batch-argv — Return the argv that runs Emacs in batch, without running it.
  • emacs-capture — Run Emacs in batch with OPTIONS and return its standard output.
  • emacs-output — Run the Emacs batch ARGV and return its standard output.
  • env-file-entries — Return the ‘(NAME .
  • env-get — Return the value of environment variable NAME, or DEFAULT when unset.
  • env-set! — Set environment variable NAME to VALUE and return VALUE.
  • env-unset! — Remove environment variable NAME.
  • environment-assignments — Return ENV as a list of ‘KEY=VALUE’ strings.
  • environment-flags — Return the whitespace-separated words of environment variable NAME.
  • environment-load-paths — Return the directories named by ‘MAAK_LOAD_PATH’.
  • exception->message — Return a one-line human message for a caught error.
  • fetch-available? — Return #t when COMMAND, the downloader ‘download’ would use, is on PATH.
  • format-task-doc — Return the lines that describe task NAME, given its docstring DOC.
  • frontend — Run the package manager with WORDS, forwarding OPTIONS to ‘frontend-argv’.
  • frontend-add — Add PACKAGES as dependencies, from the registry or the file system.
  • frontend-argv — Return the argv that runs WORDS with the project’s package manager.
  • frontend-build — Run the ‘build’ script, passing ARGUMENTS to it.
  • frontend-check — Run the ‘lint’, ‘test’ and ‘build’ scripts, in that order.
  • frontend-ci — Install the dependencies exactly as the lock file records them.
  • frontend-exec — Run COMMAND from ‘node_modules/.bin’, passing ARGUMENTS to it.
  • frontend-format — Run the ‘format’ script, passing ARGUMENTS to it.
  • frontend-install — Install the project’s dependencies, passing ARGUMENTS to the manager.
  • frontend-lint — Run the ‘lint’ script, passing ARGUMENTS to it.
  • frontend-output — Run the frontend ARGV and return its standard output as a string.
  • frontend-publish — Publish the package, passing ARGUMENTS to the manager.
  • frontend-remove — Remove PACKAGES from the dependencies.
  • frontend-run — Run the package.json SCRIPT, passing ARGUMENTS to it.
  • frontend-test — Run the ‘test’ script, passing ARGUMENTS to it.
  • git — Run git with ARGUMENTS, a list of strings, in DIRECTORY.
  • git-add — Stage PATHS, or every change in the tree when none is named.
  • git-archive — Write REVISION as OUTPUT with git archive, under PREFIX, in FORMAT.
  • git-archive-tar — Write REVISION as the gzipped tarball OUTPUT, under PREFIX.
  • git-archive-zip — Write REVISION as the zip OUTPUT, under PREFIX.
  • git-argv — Return the argv that runs git with ARGUMENTS in DIRECTORY.
  • git-branch — List the branches, or create the branches NAMES name.
  • git-checkout — Run git checkout with ARGUMENTS.
  • git-cherry-pick — Cherry-pick with any arguments git cherry-pick takes.
  • git-clean — Remove untracked files with any arguments git clean takes.
  • git-clone — Clone URL into DIRECTORY, with BRANCH, DEPTH or BARE? when given.
  • git-commit — Commit with MESSAGE, every tracked change by default.
  • git-config — Read or write configuration with any arguments git config takes.
  • git-current-branch — Return the branch the checkout in DIRECTORY is on.
  • git-current-revision — Return the full hash of the commit checked out in DIRECTORY.
  • git-describe — Describe a commit, with any arguments git describe takes.
  • git-describe-tag — Return the most recent tag reachable from HEAD in DIRECTORY.
  • git-diff — Show the changes between the working tree and the index, or as ARGUMENTS say.
  • git-dirty? — Return #t when the checkout in DIRECTORY has anything uncommitted.
  • git-fetch — Fetch from the remote, with any arguments git fetch takes.
  • git-init — Initialise a git repository here, with any arguments git init takes.
  • git-log — Show the history as a decorated one-line graph, twenty commits by default.
  • git-merge — Merge with any arguments git merge takes.
  • git-output — Run git with ARGUMENTS in DIRECTORY and return what it printed.
  • git-pull — Pull from the upstream branch, with any arguments git pull takes.
  • git-push — Push the current branch, with any arguments git push takes.
  • git-rebase — Rebase with any arguments git rebase takes.
  • git-remote — Manage remotes with any arguments git remote takes.
  • git-remote-url — Return the URL configured for remote NAME in DIRECTORY.
  • git-remotes — Return the names of the remotes configured in DIRECTORY, sorted.
  • git-reset — Reset with any arguments git reset takes.
  • git-restore — Restore paths with any arguments git restore takes.
  • git-rev-parse — Ask git about revisions, with any arguments git rev-parse takes.
  • git-revert — Revert with any arguments git revert takes.
  • git-show — Show a commit, tag or other object, with any arguments git show takes.
  • git-stash — Stash with any arguments git stash takes.
  • git-status — Show the current branch and a short status of the working tree.
  • git-submodule — Manage submodules with any arguments git submodule takes.
  • git-switch — Switch to BRANCH, creating it with CREATE? or discarding local changes with
  • git-tag — Tag the current commit as NAME, without an annotation unless MESSAGE is given.
  • git-tags — Return the names of the tags in DIRECTORY, sorted.
  • gradle — Run the Gradle TASKS, forwarding OPTIONS to ‘gradle-argv’.
  • gradle-argv — Return the argv that runs the Gradle TASKS, without running it.
  • gradle-assemble — Assemble the project’s artefacts, passing ARGUMENTS.
  • gradle-build — Run the full build, passing ARGUMENTS.
  • gradle-check — Run the checks, passing ARGUMENTS.
  • gradle-clean — Remove the build output, passing ARGUMENTS.
  • gradle-dependencies — Print the dependency report, passing ARGUMENTS.
  • gradle-output — Run the Gradle ARGV and return its standard output.
  • gradle-projects — List the project’s modules, passing ARGUMENTS.
  • gradle-publish — Publish the artefacts, passing ARGUMENTS.
  • gradle-run — Run the application task, passing ARGUMENTS.
  • gradle-tasks — List the project’s tasks, passing ARGUMENTS.
  • gradle-test — Run the tests, passing ARGUMENTS.
  • gradle-wrapper-command — Return the Gradle command to use in DIRECTORY.
  • gradle-wrapper? — Return #t when DIRECTORY holds an executable Gradle wrapper.
  • guix-available? — Return #t when a ‘guix’ program is on ‘PATH’.
  • guix-build — Build PACKAGE as CHANNELS pins it and return its output path.
  • guix-build-at — Build PACKAGE at Guix REVISION and return its output path.
  • guix-channels — Return the channel pins FILE names, as an alist of name and commit.
  • guix-container — Run CMD-PARTS in a Guix container defined by MANIFEST.
  • guix-derivation — Return the derivation file name of PACKAGE as CHANNELS pins it.
  • guix-derivation-at — Return the derivation file name of PACKAGE at Guix REVISION.
  • guix-pack — Build a ‘guix pack’ of the program in FILE.
  • guix-program — Run a program from PACKAGE as CHANNELS pins it.
  • guix-program-at — Run a program from PACKAGE, built by Guix REVISION, with ARGS.
  • guix-shell — Run CMD-PARTS inside a Guix shell made of PACKAGES.
  • home-dir — Return the current user’s home directory, or the empty string when unset.
  • i18n-compile — Compile LANGUAGE’s .po file into the .mo catalogue the program loads.
  • i18n-compile-all — Run ‘i18n-compile’ for every language of LANGUAGES, skipping missing files.
  • i18n-extract — Extract translatable strings from source files into the .pot template.
  • i18n-init — Create LANGUAGE’s .po file from the .pot template.
  • i18n-init-all — Run ‘i18n-init’ for every language of LANGUAGES.
  • i18n-language — Return the language the process should translate into.
  • i18n-locale-dir — Return the catalogue directory of LANGUAGE inside DIR.
  • i18n-merge — Fold the current .pot template into LANGUAGE’s .po file, in place.
  • i18n-merge-all — Run ‘i18n-merge’ for every language of LANGUAGES, skipping missing files.
  • i18n-mo-file — Return the path of LANGUAGE’s compiled machine object file (the one the program loads).
  • i18n-po-file — Return the path of LANGUAGE’s portable object file (the one a translator edits).
  • i18n-pot-file — Return the path of the template TEXTDOMAIN.pot inside DIR.
  • i18n-refresh — Do the whole gettext cycle: extract, merge, then compile.
  • i18n-source-globs — Return the file patterns of DIRECTORIES that ‘xgettext’ should read.
  • i18n-translator — Install the catalogue in DIR for TEXTDOMAIN and return a translate procedure.
  • indent-string — Indent every line of STR by BY spaces.
  • install-directory — Create DIRECTORY and its parents with MODE.
  • install-file — Install SOURCE at DESTINATION with MODE, creating parent directories.
  • job-done? — Return #t when JOB has finished, without waiting for it.
  • job-exit-code — Wait for JOB when needed and return its exit code.
  • link — Link OBJECTS into OUTPUT.
  • link-argv — Return the argv that links OBJECTS into OUTPUT, without running it.
  • list-tasks — List documentation for every maak task in the loaded file.
  • ln-s — Create a symbolic link LINK-NAME pointing at TARGET.
  • load-env-file — Read the ‘NAME=VALUE’ assignments of PATH into the environment.
  • log-error — An undocumented procedure.
  • log-info — An undocumented procedure.
  • log-message — An undocumented procedure.
  • log-separator — An undocumented procedure.
  • maak-error-hint — An undocumented procedure.
  • maak-error-message — An undocumented procedure.
  • maak-error? — An undocumented procedure.
  • maak-proc? — Predicate that indicates whether a procedure is a valid maak proc.
  • maak-task? — Predicate that indicates whether it is a valid maak task.
  • maak-version-string — Return the one-line version banner printed by ‘maak –version’.
  • make-maak-error — An undocumented procedure.
  • manifest-shell — Execute a command inside a Guix shell defined by a manifest file.
  • maven — Run the Maven GOALS, forwarding OPTIONS to ‘maven-argv’.
  • maven-argv — Return the argv that runs the Maven GOALS, without running it.
  • maven-clean — Remove the build output with ‘mvn clean’, passing ARGUMENTS.
  • maven-compile — Compile the sources with ‘mvn compile’, passing ARGUMENTS.
  • maven-dependency-tree — Print the dependency tree with ‘mvn dependency:tree’, passing ARGUMENTS.
  • maven-deploy — Deploy the artefact with ‘mvn deploy’, passing ARGUMENTS.
  • maven-effective-pom — Print the effective POM with ‘mvn help:effective-pom’, passing ARGUMENTS.
  • maven-install — Install the artefact into the local repository, passing ARGUMENTS.
  • maven-output — Run the Maven ARGV and return its standard output.
  • maven-package — Package the artefact with ‘mvn package’, passing ARGUMENTS.
  • maven-site — Build the project site with ‘mvn site’, passing ARGUMENTS.
  • maven-test — Run the tests with ‘mvn test’, passing ARGUMENTS.
  • maven-validate — Validate the project with ‘mvn validate’, passing ARGUMENTS.
  • maven-verify — Run the verification phase with ‘mvn verify’, passing ARGUMENTS.
  • maven-wrapper-command — Return the Maven command to use in DIRECTORY.
  • maven-wrapper? — Return #t when DIRECTORY holds an executable Maven wrapper.
  • mkdir-p — Create a directory and all necessary parent directories.
  • mv — Move or rename a file or directory.
  • niri — Send ARGUMENTS to ‘niri msg’.
  • niri-action — Perform an action with ARGUMENTS, through ‘niri msg action’.
  • niri-action-argv — Return the argv that performs an action with its ARGUMENTS.
  • niri-argv — Return the argv that sends ARGUMENTS to ‘niri msg‘.
  • niri-available? — Return #t when the niri program can be found on PATH.
  • niri-capture — Send ARGUMENTS to ‘niri msg’ and return what it printed.
  • niri-casts — List the screencasts.
  • niri-close-window — Close the focused window.
  • niri-focus-column — Focus the column at INDEX.
  • niri-focus-monitor — Focus the monitor NAME.
  • niri-focus-window — Focus the window with ID.
  • niri-focus-window-previous — Focus the previously focused window.
  • niri-focus-workspace — Focus the workspace REFERENCE, an index or a name.
  • niri-focus-workspace-previous — Focus the previous workspace.
  • niri-focused-output — Print information about the focused output.
  • niri-focused-window — Print information about the focused window.
  • niri-fullscreen-window — Toggle fullscreen on the focused window.
  • niri-keyboard-layouts — Print the configured keyboard layouts.
  • niri-layers — List the open layer-shell surfaces.
  • niri-move-column-to-monitor — Move the focused column to the monitor NAME.
  • niri-move-column-to-workspace — Move the focused column to the workspace REFERENCE.
  • niri-move-window-to-monitor — Move the focused window to the monitor NAME.
  • niri-move-window-to-workspace — Move the focused window, or WINDOW-ID, to the workspace REFERENCE.
  • niri-output — Change OUTPUT with ACTION and ARGUMENTS; see ‘niri-output-argv’.
  • niri-output-argv — Return the argv that changes OUTPUT with ACTION and ARGUMENTS.
  • niri-output-mode — Set OUTPUT’s mode, such as 1920x1080@60.
  • niri-output-off — Turn OUTPUT off.
  • niri-output-on — Turn OUTPUT on.
  • niri-output-position — Set OUTPUT’s position on the desktop to X and Y.
  • niri-output-scale — Set OUTPUT’s scale, such as 1.5.
  • niri-output-transform — Set OUTPUT’s transform, such as 90 or flipped-180.
  • niri-outputs — List the connected outputs.
  • niri-overview-state — Print the overview state.
  • niri-pick-color — Pick a color from the screen with the mouse.
  • niri-pick-window — Pick a window with the mouse and print information about it.
  • niri-power-off-monitors — Power off all monitors via DPMS.
  • niri-power-on-monitors — Power on all monitors via DPMS.
  • niri-quit — Exit niri.
  • niri-request-error — Ask niri to return an error, which is useful for checking a client’s
  • niri-screenshot — Open the screenshot UI.
  • niri-screenshot-screen — Screenshot the focused screen.
  • niri-screenshot-window — Screenshot the focused window.
  • niri-set-column-width — Change the width of the focused column by CHANGE.
  • niri-set-window-width — Change the width of the focused window, or of window ID, by CHANGE.
  • niri-set-workspace-name — Set the name of the focused workspace to NAME.
  • niri-spawn — Spawn COMMAND, a list of strings, without a shell.
  • niri-spawn-sh — Spawn COMMAND through the shell.
  • niri-toggle-overview — Toggle the overview.
  • niri-toggle-windowed-fullscreen — Toggle windowed (fake) fullscreen on the focused window.
  • niri-unset-workspace-name — Unset the name of the focused workspace.
  • niri-version — Print the version of the running niri instance.
  • niri-windows — List the open windows.
  • niri-workspaces — List the workspaces.
  • nix-build — Build the derivation in FILE with the classic ‘nix-build’.
  • nix-develop — Run CMD-PARTS inside the development shell of the flake FLAKE.
  • nix-flake-build — Build the flake FLAKE, optionally selecting the output ATTR.
  • nix-flake-check — Check every output of the flake FLAKE, as ‘nix flake check’ does.
  • nix-run — Run the application APP of the flake FLAKE with CMD-PARTS as its arguments.
  • nix-shell — Run CMD-PARTS inside a Nix shell.
  • object-file — Return the object file a SOURCE compiles to.
  • package-dependencies — Return the dependencies package.json declares, with the ranges it gives them.
  • package-dev-dependencies — Return the development dependencies package.json declares.
  • package-json — Return PATH read as JSON, a string-keyed alist, in file order.
  • package-manager-kind — Return the package manager MANAGER runs, as one of ‘npm’, ‘pnpm’ or ‘yarn’.
  • package-name — Return the name package.json gives the package.
  • package-scripts — Return the names of the scripts package.json defines, in file order.
  • package-version — Return the version package.json gives the package.
  • pipeline-ok? — Return #t when every stage of the pipeline that produced RESULT succeeded.
  • pkg-config — Run pkg-config for PACKAGES and return its output as a string.
  • pkg-config-argv — Return the argv that asks pkg-config for PACKAGES, without running it.
  • pkg-config-cflags — Return the compiler flags pkg-config names for PACKAGES, as a list.
  • pkg-config-exists? — Return #t when pkg-config knows every one of PACKAGES.
  • pkg-config-libs — Return the linker flags pkg-config names for PACKAGES, as a list.
  • pkg-config-version — Return the version pkg-config reports for PACKAGE.
  • print-version — Print the version banner, and the program’s homepage, to PORT.
  • program-shell — Execute a command inside a Guix shell defined by a program file.
  • pyproject-data — Return PATH read as TOML, a string-keyed alist, in file order.
  • python — Run the Python interpreter, forwarding OPTIONS to ‘python-argv’.
  • python-argv — Return the argv that runs the Python interpreter, without running it.
  • python-build-backend — Return the build backend of the project, or #f when it names none.
  • python-check — Run the lint, the type check and the tests, in that order.
  • python-format — Format with ruff, over ARGUMENTS or over the whole project.
  • python-lint — Lint with ruff, over ARGUMENTS or over the whole project.
  • python-module — Run MODULE with the interpreter, passing ARGUMENTS.
  • python-output — Run the interpreter ARGV and return its standard output as a string.
  • python-project — Return the ‘[project]’ table of PATH, or raise when there is none.
  • python-project-name — Return the name the ‘[project]’ table gives the package.
  • python-project-scripts — Return the names of the console scripts the project defines.
  • python-project-version — Return the version the ‘[project]’ table gives the package.
  • python-requires-python — Return the interpreter constraint of the project, or #f when it sets none.
  • python-test — Run the tests with pytest, passing ARGUMENTS to it.
  • python-type-check — Type-check with mypy, over ARGUMENTS or over the whole project.
  • python-version — Return the version line the installed interpreter prints, trimmed.
  • raise-maak-error — Raise a ‘&maak-error’ with MESSAGE and an optional HINT.
  • read-file — Return the contents of FILE as a string.
  • remkdir-p — Remove a directory if it exists, then recreate it.
  • require-command — Return the path of COMMAND, raising a maak error when it is missing.
  • resolve-maak-tasks — Return the runnable tasks of MODULE-NAME as ‘(NAME .
  • rm-rf — Delete PATH recursively, forcefully and verbosely.
  • run — Run a program and its arguments without a shell.
  • run-compose — Run Compose with ARGUMENTS, a list of strings.
  • run-pipeline — Run a pipeline of programs without a shell.
  • run-task — Run TASK, a single Maak task, logging its documentation first.
  • run-tasks — Run TASKS sequentially, in the order given.
  • run-tasks-parallel — Run TASKS concurrently and print their output in the order they were given.
  • rustup — Run rustup with ARGUMENTS.
  • rustup-active-toolchain — Return the toolchain rustup would use here, as its name.
  • rustup-argv — Return the argv that runs rustup with ARGUMENTS.
  • rustup-component-add — Add COMPONENT, for example "rustfmt" or "clippy", to the active toolchain.
  • rustup-install — Install TOOLCHAIN, for example "nightly".
  • rustup-output — Run rustup with ARGUMENTS and return its standard output.
  • rustup-target-add — Add the compilation TARGET to the active toolchain.
  • rustup-toolchains — Return the names of the installed toolchains.
  • shell-quote — Return STR quoted so that a shell reads it as one literal word.
  • sift — Run sift SUBCOMMAND over FILES, raising when it exits non-zero.
  • sift-argv — Return the argv that runs sift SUBCOMMAND over FILES, without running it.
  • sift-check — Ask whether FILES are formatted, failing the task when one is not.
  • sift-ci — Ask the formatting question and the lint question in one pass.
  • sift-exit-meaning — Return what sift’s exit CODE means: ‘clean’, ‘findings’ or ‘error’.
  • sift-files — Return the Lisp files under DIRECTORY, sorted, skipping EXCLUDE directories.
  • sift-format — Format FILES, rewriting them with WRITE? and printing them otherwise.
  • sift-lint — Lint FILES, failing the task when a rule at SEVERITY or above fires.
  • sift-status — Run the sift ARGV and return its exit status: 0, 1 or 2.
  • split-load-path — Split a ‘PATH’-style colon separated STR into a list of directories.
  • stage — Describe one stage of a pipeline, with the options ‘run’ takes.
  • static-library — Write OBJECTS into the static library OUTPUT.
  • static-library-argv — Return the argv that writes OBJECTS into a static library OUTPUT.
  • string-lines — Split STR on newlines into a list of lines.
  • syscall — Executes a shell command and checks its exit code.
  • tar-compression-option — Return the tar flags that select COMPRESSION, as a list.
  • tar-create — Write FILES as the tarball OUTPUT.
  • tar-create-argv — Return the argv that writes FILES as the tarball OUTPUT.
  • tar-extract — Unpack ARCHIVE, into DIRECTORY when one is named.
  • tar-extract-argv — Return the argv that unpacks ARCHIVE.
  • tar-list — Print the names of the files in ARCHIVE, without unpacking it.
  • tar-list-argv — Return the argv that prints the names of the files in ARCHIVE.
  • task-depends — Return the names of the tasks TASK needs to have finished first, in order.
  • task-error — Raise a user-facing error from a task.
  • task-example — Return the invocation TASK holds up as an example, or the empty string.
  • task-hidden? — Return #t when TASK asks the listings to leave it out.
  • task-meta — Return what TASK declares about itself, or #f when it declares nothing.
  • task-metadata! — Record what TASK declares about itself.
  • task-order — Return TASKS as the list to run, with each task’s dependencies before it.
  • tasks-table — Return TASKS as the aligned listing ‘maak –list’ prints.
  • time-machine — Execute a command using a pinned Guix revision via ‘guix time-machine‘.
  • time-machine-manifest-shell — Execute a command inside a Guix shell defined by a manifest file,
  • time-machine-program-shell — Execute a command inside a Guix shell defined by a program file,
  • tmp-dir — Return the directory for temporary files, honouring ‘TMPDIR’.
  • touch — Create FILE if it does not exist, or update its timestamp.
  • unknown-task-error — Raise a maak error saying TASK is not runnable, listing the tasks that are.
  • unlines — Join LINES with newlines, adding no trailing newline.
  • unwords — Join WORDS with single spaces.
  • up-to-date? — Return #t when OUTPUT exists and is not older than any of INPUTS.
  • uv — Run uv SUBCOMMAND, forwarding OPTIONS to ‘uv-argv’.
  • uv-add — Add a dependency to the project, passing ARGUMENTS.
  • uv-argv — Return the argv that runs uv SUBCOMMAND, without running it.
  • uv-build — Build the source and wheel distributions into ‘dist/’, passing ARGUMENTS.
  • uv-export — Export the lock file to another format, passing ARGUMENTS.
  • uv-init — Create a new project with ‘uv init’, passing ARGUMENTS.
  • uv-lock — Update the lock file, passing ARGUMENTS.
  • uv-output — Run the uv ARGV and return its standard output as a string.
  • uv-pip — Run a ‘uv pip’ command, passing ARGUMENTS.
  • uv-publish — Publish the built distributions, passing ARGUMENTS.
  • uv-python — Manage the interpreters uv installs, passing ARGUMENTS.
  • uv-remove — Remove a dependency from the project, passing ARGUMENTS.
  • uv-run — Run a command in the project’s environment, passing ARGUMENTS.
  • uv-sync — Synchronise the environment with the lock file, passing ARGUMENTS.
  • uv-tree — Print the dependency tree, passing ARGUMENTS.
  • uv-venv — Create the virtual environment, passing ARGUMENTS.
  • uv-version — Return the version line the installed uv prints, trimmed.
  • uvx — Run a tool installed in a temporary environment, as ‘uvx ruff’ does.
  • uvx-argv — Return the argv that runs uvx with ARGUMENTS.
  • veritas-env — Return the VERITAS_* assignments the runner reads, as NAME=VALUE strings.
  • veritas-shell-command — Return the same words with EXPRESSION quoted for a shell.
  • veritas-test — Run the Veritas suite and fail the task when it does not pass.
  • veritas-test-argv — Return the argv that runs the Veritas suite, without running it.
  • wait-job — Wait for JOB to finish and return #t when it exited with code 0.
  • watch-changed? — Return #t when the two snapshots describe a different tree.
  • watch-files — Return the files a watch of ROOT follows, as absolute paths.
  • watch-interval — Return the watch interval in seconds.
  • watch-relist — Re-run a task listing now, and again whenever ROOT changes.
  • watch-snapshot — Return FILES as a sorted list of ‘(PATH MTIME .
  • watch-tree — Run THUNK now, then again whenever the tree under ROOT changes.
  • wget — Run wget with ARGUMENTS, a list of strings; see ‘wget-argv’.
  • wget-argv — Return the argv that runs wget with ARGUMENTS.
  • wget-download — Download URL with wget; see ‘wget-download-argv’.
  • wget-download-argv — Return the argv that downloads URL with wget.
  • wget-mirror — Mirror the site at URL with wget; see ‘wget-mirror-argv’.
  • wget-mirror-argv — Return the argv that mirrors the site at URL with wget.
  • wget-output — Run wget with ARGUMENTS and return what it printed.
  • wget-text — Fetch URL with wget and return the body as a string.
  • wget-text-argv — Return the argv that fetches URL’s body for a task to read.
  • which — Return the absolute path of COMMAND on ‘PATH’, or #f when it is missing.
  • with-directory — Call THUNK with the process working directory changed to DIR.
  • with-env — Call THUNK with environment variable NAME set to VALUE.
  • with-env-vars — Call THUNK with every NAME and VALUE pair of VARIABLES set.
  • with-load-path — Call THUNK with DIRS added to the load path, restoring it afterwards.
  • write-file — Write CONTENT to FILE, creating its directory first when needed.
  • zip-create — Write FILES as the zip archive OUTPUT.
  • zip-create-argv — Return the argv that writes FILES as the zip archive OUTPUT.
  • zip-extract — Unpack ARCHIVE, into DIRECTORY when one is named.
  • zip-extract-argv — Return the argv that unpacks ARCHIVE.
  • zip-list — Print a listing of the files in ARCHIVE, without unpacking it.
  • zip-list-argv — Return the argv that lists the contents of ARCHIVE.
  • ~ — A utility function to format a string (interpolation).
  • &maak-error — A record type.
  • maak-homepage — A variable.
  • maak-license — A variable.
  • maak-version — A variable.
  • veritas-expression — A variable.

1.16.2 Macros

Macro: get-module-var x

Get a variable from the currently loaded maak file module.

Macro: job-command x

Undocumented macro.

Macro: job-pid x

Undocumented macro.

Macro: job? x

Undocumented macro.

Macro: pipeline-errors x

Undocumented macro.

Macro: pipeline-outputs x

Undocumented macro.

Macro: pipeline-result? x

Undocumented macro.

Macro: stage? x

Undocumented macro.

Macro: text x

Undocumented macro.

1.16.3 Parameters

Parameter: ar-command

Default value:

"ar"
Parameter: banner?

Default value:

#t
Parameter: c-compiler

Default value:

"cc"
Parameter: cargo-command

Default value:

"cargo"
Parameter: container-compose-command

Default value:

("podman-compose")
Parameter: container-engine

Default value:

"podman"
Parameter: cxx-compiler

Default value:

"c++"
Parameter: dry-run?

Default value:

#f
Parameter: elevation-command

Default value:

"sudo"
Parameter: emacs-command

Default value:

"emacs"
Parameter: fetch-command

Default value:

"curl"
Parameter: gradle-command

Default value:

"gradle"
Parameter: maak-load-path

Default value:

()
Parameter: maven-command

Default value:

"mvn"
Parameter: package-json-file

Default value:

"package.json"
Parameter: package-manager

Default value:

"npm"
Parameter: pkg-config-command

Default value:

"pkg-config"
Parameter: pyproject-file

Default value:

"pyproject.toml"
Parameter: python-command

Default value:

"python3"
Parameter: quiet?

Default value:

#f
Parameter: rustup-command

Default value:

"rustup"
Parameter: sift-command

Default value:

"sift"
Parameter: uv-command

Default value:

"uv"
Parameter: uvx-command

Default value:

"uvx"

1.16.4 Procedures

Procedure: $ cmd-parts KEY: #:verbose? #:join #:env #:sudo? #:dev-null? #:allow-failure? #:async?

Executes a shell command constructed from a list of strings.

($ '("echo -n" "hello-world"))

;; as root, in the background, quietly, and without caring whether it fails
($ '("systemctl daemon-reload")
   #:sudo? #t #:async? #t #:dev-null? #t #:allow-failure? #t)

ARGUMENTS:

  • cmd-parts (list): A list of strings that will be joined to form the command.
  • #:verbose? (boolean, default #f): If #t, logs the generated command before executing it.
  • #:join (string, default " "): A string to use as a separator when joining the command parts.
  • #:env (alist, list of strings, or string, default ’()): Environment variables to set for this command only, given as an alist ((("CI" . "1"))), as "KEY=VALUE" strings, or as one such string. They are passed through env and reach the command itself.
  • #:sudo? (boolean, default #f): If #t, the command runs through the configured privilege escalation command – doas when it is installed, sudo otherwise, or whatever MAAK_ELEVATE names. See elevation-command.
  • #:dev-null? (boolean, default #f): If #t, both standard output and standard error are discarded to /dev/null.
  • #:allow-failure? (boolean, default #f): If #t, a non-zero exit code does not raise: #f is returned instead, so a task can decide what a failure means. The command line itself is left alone, which is what lets the task be told the command failed.
  • #:async? (boolean, default #f): If #t, the command is started in the background and a job record is returned (see run), instead of a boolean.

RETURNS: The result of the syscall function: #t if the command completes with an exit code of 0, #f if it failed and #:allow-failure? was given, and a job record when #:async? was given.

Procedure: add-load-path! dir

Prepend DIR to Guile’s load path and record it as a maak load path.

Returns the canonical name of the directory that was added, which makes it usable in a ‘let’ when a task wants to report what it did. This is a procedure rather than the ‘add-to-load-path’ syntax because a task computes the directory at run time.

Procedure: add-load-paths! dirs

Prepend every directory of DIRS to the load path, in order.

Returns the list of directories that were added.

Procedure: available-task-names

Return the names of the tasks maak can currently run, sorted.

Procedure: bold-output x

Return X emphasised for a terminal, or X unchanged when styling is off.

See ‘color?’: ‘NO_COLOR’ turns the escapes off for a whole run.

Procedure: bundle KEY: #:name #:format #:output #:maak-file #:maak-package #:packages #:home-page #:description #:load? #:verbose?

Build a self-contained bundle of NAME’s automation and return its path.

The bundle is a Guix pack of a generated package that installs MAK-FILE and a launcher, and carries maak, Guile and PACKAGES with it, so it runs on a machine with none of them. FORMAT is a ‘guix pack’ format: "tarball" (made relocatable, so it extracts anywhere), "squashfs" or "docker". OUTPUT names the file; by default it is NAME-bundle with an extension for FORMAT.

With LOAD? a docker pack is loaded into the container engine afterwards, using the ‘(maak container)’ helper, so the image is ready to run as well as written.

(bundle #:name "site" #:maak-file "maak.scm"
        #:packages '("git" "curl") #:format "tarball")
Procedure: bundle-file-name name pack-format

Return the file name a bundle of NAME in PACK-FORMAT is written to.

Procedure: bundle-script KEY: #:name #:maak-file #:maak-package #:packages #:home-page #:description

Return the Guix package file that defines a bundle for NAME.

MAK-FILE is the Maak file to ship; MAK-PACKAGE is a Scheme expression that evaluates to the maak package, and PACKAGES are the extra package names the automation needs. The expression is inserted as written, so it is trusted input: it is how a project points at its own build of maak.

The package installs the Maak file under ‘share/NAME’ and a launcher in ‘bin/NAME’, and propagates maak, Guile and the packages, so ‘guix pack -S /bin=bin’ gives a pack whose ‘bin’ holds all of them.

Procedure: capture command KEY: #:error? #:allow-failure?

Run COMMAND and return its standard output as a string.

With ERROR? true the command’s standard error is captured too.

A command that exits non-zero raises a maak error naming its exit code, rather than returning the empty or partial output it managed to produce: a caller that reads ‘""’ cannot tell a command that printed nothing from one that failed. With ALLOW-FAILURE? true the output is returned anyway, and the caller decides what the failure means.

In dry-run mode the command is only printed and the empty string is returned. Use ‘$’ when a failing command must stop the task without its output, and ‘run’ when the command takes arguments that a shell must not split.

(string-trim (capture describe-tags-command))
Procedure: cargo subcommand KEY: #:arguments #:verbose?

Run cargo SUBCOMMAND with ARGUMENTS, as separate words.

This is the short form: the words after SUBCOMMAND are arguments, so ‘(cargo-build "–release")’ passes cargo’s own ‘–release’. Use ‘cargo-argv’ when the structured options are wanted, and ‘run’ to execute what it returns.

(cargo "test" #:arguments '("--workspace" "--all-features"))
Procedure: cargo-argv subcommand KEY: #:arguments #:manifest-path #:package #:features #:no-default-features? #:all-features? #:target #:release? #:profile #:jobs #:offline? #:locked? #:frozen? #:quiet? #:verbose #:color #:message-format #:timings?

Return the argv that runs cargo SUBCOMMAND, without running it.

Global options are placed before SUBCOMMAND and the command’s own options after it, which is the grammar cargo accepts for every subcommand. ARGUMENTS are appended as they are, so an option this builder does not name, or the words a ‘cargo run’ passes to the program after ‘–’, still reach cargo.

FEATURES takes a string or a list and is joined with commas, the way ‘–features’ spells it. VERBOSE is #t for one ‘-v’ or a positive number for that many. RELEASE? and PROFILE cannot both be given: cargo spells the release profile both ways, and asking for two profiles is a question with no answer.

(cargo-argv "build" #:release? #t #:features '("openssl" "serde"))
⇒ ("cargo" "build" "--features" "openssl,serde" "--release")

(cargo-argv "run" #:arguments '("--" "--help"))
⇒ ("cargo" "run" "--" "--help")
Procedure: cargo-artifact-path name KEY: #:profile #:release? #:triple #:manifest-path

Return where cargo writes the artefact called NAME.

PROFILE is the cargo profile, ‘debug’ by default; RELEASE? is the shorthand for ‘release’. TRIPLE names a cross-compilation target’s directory. The path is composed from ‘cargo metadata”s target directory, so a workspace with ‘CARGO_TARGET_DIR’ set answers with the directory cargo will really use.

Procedure: cargo-bench . arguments

Run the benchmarks with cargo, passing ARGUMENTS.

Procedure: cargo-binaries KEY: #:package #:manifest-path

Return the names of the binary targets of PACKAGE, or of the only package.

Procedure: cargo-build . arguments

Build the package with cargo, passing ARGUMENTS.

Procedure: cargo-check . arguments

Type-check the package with cargo, passing ARGUMENTS.

Procedure: cargo-clean . arguments

Remove the build artefacts with cargo, passing ARGUMENTS.

Procedure: cargo-clippy . arguments

Lint the package with ‘cargo clippy’, passing ARGUMENTS.

Procedure: cargo-doc . arguments

Build the documentation with cargo, passing ARGUMENTS.

Procedure: cargo-fetch . arguments

Fetch the dependencies with cargo, passing ARGUMENTS.

Procedure: cargo-fmt . arguments

Format the sources with ‘cargo fmt’, passing ARGUMENTS.

Procedure: cargo-install . arguments

Install a cargo binary, passing ARGUMENTS.

Procedure: cargo-metadata KEY: #:manifest-path #:no-deps? #:offline? #:locked?

Return ‘cargo metadata’ as parsed JSON, a string-keyed alist.

This is how a task learns the workspace’s members, a package’s version and where its artefacts land, without guessing at a path or re-reading Cargo.toml. The query runs even in a dry run.

Procedure: cargo-output argv KEY: #:allow-failure?

Run the cargo ARGV and return its standard output as a string.

The query runs even in a dry run: it reads the project rather than changing it, and a plan that left out what ‘cargo metadata’ says would be a plan of a different project. A failure raises a maak error naming the command, or comes back as #f when the caller asked for the exit status instead.

Procedure: cargo-package KEY: #:name #:manifest-path

Return the metadata of one package, or raise when it cannot be chosen.

Without NAME the answer is the only package in the workspace; a workspace with several packages needs one named, because picking the first would silently describe the wrong crate.

Procedure: cargo-package-names KEY: #:manifest-path

Return the names of the packages in the workspace, in cargo’s order.

Procedure: cargo-package-version KEY: #:package #:manifest-path

Return the version cargo reports for PACKAGE, or for the only package.

Procedure: cargo-publish . arguments

Publish the package with cargo, passing ARGUMENTS.

A dry run of the release is ‘(cargo-publish "–dry-run")’, and cargo’s own flag is what makes it one: maak’s dry run prints the command instead.

Procedure: cargo-run . arguments

Run the binary with cargo; put the program’s own words after "–".

Procedure: cargo-target-directory KEY: #:manifest-path

Return the directory cargo writes its artefacts into.

Procedure: cargo-test . arguments

Run the tests with cargo, passing ARGUMENTS.

Procedure: cargo-update . arguments

Update the dependencies with cargo, passing ARGUMENTS.

Procedure: cat file KEY: #:verbose? #:expand?

Print FILE to standard output.

Procedure: cd dir

Change the process working directory to DIR and return it.

Unlike ‘with-directory’ the change lasts for the rest of the run, which is what a task that only ever works from one place wants.

Procedure: chmod-file mode file KEY: #:recursive? #:verbose? #:expand?

Change the permissions of FILE to MODE, an octal string such as 755.

With EXPAND? #t the shell expands FILE, so a wildcard names every file whose permissions are to change.

Procedure: command-exists? command

Return #t when COMMAND can be found on ‘PATH’.

Procedure: command-on-path? command path

Return #t when COMMAND is an executable in one of the directories in PATH.

Procedure: compile source KEY: #:output #:includes #:defines #:flags #:language #:compiler #:standard #:pic? #:depfile? #:verbose?

Compile SOURCE to OUTPUT, or to SOURCE’s ‘.o’ beside it.

The keywords are ‘compile-argv”s. The command goes through ‘run’, so a dry run prints it, a plan records it, and a failure names the compiler and the source.

(compile "src/a.c" #:output "build/a.o" #:includes '("include"))
Procedure: compile-argv source KEY: #:output #:includes #:defines #:flags #:language #:compiler #:standard #:pic? #:depfile?

Return the argv that compiles SOURCE to OUTPUT, without running it.

INCLUDES become ‘-I’ arguments, DEFINES ‘-D’ arguments, and FLAGS are inserted verbatim. STANDARD becomes ‘-std=STANDARD’. PIC? adds ‘-fPIC’, and DEPFILE? adds ‘-MMD -MP’, so the compiler writes the dependency file beside the object; maak does not read that file, and ‘up-to-date?’ is how a task uses it.

(compile-argv "src/a.c" #:output "build/a.o"
              #:includes '("include") #:defines '("NDEBUG")
              #:flags '("-O2" "-Wall") #:standard "c11")
Procedure: compile-objects sources KEY: #:directory #:jobs #:incremental? #:includes #:defines #:flags #:language #:compiler #:standard #:pic? #:depfile? #:verbose?

Compile every SOURCE to its object under DIRECTORY, up to JOBS at once.

Each object is named with ‘object-file’, so ‘src/a.c’ in DIRECTORY ‘build’ becomes ‘build/a.o’. With INCREMENTAL? #t an object newer than its source is left alone; without it every object is compiled, which is what a clean build wants. JOBS above one starts that many compilers at once, each a process of its own; a failure is reported with how many of them failed, and the compilers’ own messages are above it.

(compile-objects '("src/a.c" "src/b.c")
                 #:directory "build" #:jobs 4 #:incremental? #t
                 #:includes '("include") #:depfile? #t)
Procedure: compiler-for language OPT: compiler

Return the compiler for LANGUAGE as a list of words.

LANGUAGE is ‘c’, ‘c++’, ‘"c’ or ‘"c++’". COMPILER, when given, overrides the ‘c-compiler’ or ‘cxx-compiler’ parameter. A compiler value with flags is split into words, so ‘MAAK_CC="ccache gcc"’ works.

Procedure: compose-argv arguments KEY: #:program #:file #:project #:env-files #:profiles

Return the argv that runs Compose with ARGUMENTS.

FILE is –file, PROJECT is –project-name, ENV-FILES are passed as –env-file, and PROFILES as –profile. They come before the subcommand, which is where both Docker Compose and podman-compose expect them.

Procedure: compose-available? KEY: #:program

Return #t when the Compose PROGRAM can be found on PATH.

PROGRAM is the list of words container-compose-command returns; its first word is what is looked for.

Procedure: compose-build services KEY: #:program #:file #:project #:env-files #:profiles #:no-cache? #:pull? #:allow-failure? #:verbose?

Build SERVICES with Compose; see ‘compose-build-argv‘.

Procedure: compose-build-argv services KEY: #:program #:file #:project #:env-files #:profiles #:no-cache? #:pull?

Return the argv that builds SERVICES, or every service when it is empty.

Procedure: compose-config services KEY: #:program #:file #:project #:env-files #:profiles #:quiet? #:services? #:allow-failure? #:verbose?

Render the Compose configuration; see ‘compose-config-argv‘.

Procedure: compose-config-argv services KEY: #:program #:file #:project #:env-files #:profiles #:quiet? #:services?

Return the argv that renders the resolved Compose configuration.

QUIET? asks Compose to validate without printing; SERVICES? asks for only the service definitions, and the service names are passed as arguments when given. The quiet flag is spelled -q because that is the form both Compose implementations accept.

Procedure: compose-down services KEY: #:program #:file #:project #:env-files #:profiles #:volumes? #:remove-orphans? #:rmi #:timeout #:allow-failure? #:verbose?

Stop and remove SERVICES with Compose; see ‘compose-down-argv‘.

Procedure: compose-down-argv services KEY: #:program #:file #:project #:env-files #:profiles #:volumes? #:remove-orphans? #:rmi #:timeout

Return the argv that stops and removes SERVICES, or the whole project.

VOLUMES? also removes named volumes, which is what makes a test environment return to a clean state; it is off by default because the data is otherwise kept between runs.

Procedure: compose-exec service command KEY: #:program #:file #:project #:env-files #:profiles #:tty? #:user #:workdir #:index #:no-tty? #:allow-failure? #:verbose?

Run COMMAND in SERVICE with Compose; see ‘compose-exec-argv‘.

Procedure: compose-exec-argv service command KEY: #:program #:file #:project #:env-files #:profiles #:tty? #:user #:workdir #:index #:no-tty?

Return the argv that runs COMMAND in SERVICE.

NO-TTY? (the default) passes -T, which both Docker Compose and podman-compose spell the same way. A task needs it: without it Compose tries to allocate a terminal, and a command run from a pipeline or a CI job does not have one. TTY? asks for a terminal instead, and wins over the default: the two flags contradict each other, so only one is ever emitted. Pass #:no-tty? #f for an interactive shell that should not be told what to do either way.

Procedure: compose-logs services KEY: #:program #:file #:project #:env-files #:profiles #:follow? #:tail #:no-color? #:allow-failure?

Print the logs of SERVICES with Compose; see ‘compose-logs-argv‘.

Procedure: compose-logs-argv services KEY: #:program #:file #:project #:env-files #:profiles #:follow? #:tail #:no-color?

Return the argv that prints the logs of SERVICES, or of the whole project.

Procedure: compose-output arguments KEY: #:program #:file #:project #:env-files #:profiles #:allow-failure?

Run Compose with ARGUMENTS and return its output as a string.

Procedure: compose-ps services KEY: #:program #:file #:project #:env-files #:profiles #:all? #:format #:allow-failure?

List the containers of SERVICES with Compose; see ‘compose-ps-argv‘.

Procedure: compose-ps-argv services KEY: #:program #:file #:project #:env-files #:profiles #:all? #:format

Return the argv that lists the containers of SERVICES, or of the project.

ALL? is Docker Compose’s –all; podman-compose has no equivalent flag and lists the project’s containers already, so leave it off with that program.

Procedure: compose-pull services KEY: #:program #:file #:project #:env-files #:profiles #:ignore-pull-failures? #:allow-failure? #:verbose?

Pull the images of SERVICES with Compose; see ‘compose-pull-argv‘.

Procedure: compose-pull-argv services KEY: #:program #:file #:project #:env-files #:profiles #:ignore-pull-failures?

Return the argv that pulls the images of SERVICES.

IGNORE-PULL-FAILURES? is Docker Compose’s flag; podman-compose does not accept it, so leave it off with that program.

Procedure: compose-restart services KEY: #:program #:file #:project #:env-files #:profiles #:timeout #:allow-failure? #:verbose?

Restart SERVICES with Compose; see ‘compose-restart-argv‘.

Procedure: compose-restart-argv services KEY: #:program #:file #:project #:env-files #:profiles #:timeout

Return the argv that restarts SERVICES.

Procedure: compose-run service command KEY: #:program #:file #:project #:env-files #:profiles #:remove? #:no-deps? #:user #:workdir #:allow-failure? #:verbose?

Run COMMAND in a one-off container for SERVICE; see ‘compose-run-argv‘.

Procedure: compose-run-argv service command KEY: #:program #:file #:project #:env-files #:profiles #:remove? #:no-deps? #:user #:workdir

Return the argv that runs COMMAND in a one-off container for SERVICE.

REMOVE? (the default) passes –rm; NO-DEPS? keeps Compose from starting the service’s dependencies.

Procedure: compose-up services KEY: #:program #:file #:project #:env-files #:profiles #:detach? #:build? #:force-recreate? #:remove-orphans? #:no-start? #:wait? #:allow-failure? #:verbose?

Start SERVICES with Compose; see ‘compose-up-argv‘.

Procedure: compose-up-argv services KEY: #:program #:file #:project #:env-files #:profiles #:detach? #:build? #:force-recreate? #:remove-orphans? #:no-start? #:wait?

Return the argv that starts SERVICES, or every service when it is empty.

DETACH? (the default) is –detach, because a task that starts a stack wants its shell back. BUILD? rebuilds images, FORCE-RECREATE? replaces the containers, REMOVE-ORPHANS? is on by default, and WAIT? waits for the services to be healthy before returning.

Procedure: container arguments KEY: #:engine #:allow-failure? #:verbose?

Run ENGINE with ARGUMENTS, a list of strings.

The escape hatch for subcommands without a wrapper, such as ‘volume ls‘. Nothing is handed to a shell, so a label or a path with a space in it stays one argument.

Procedure: container-argv arguments KEY: #:engine

Return the argv that runs ENGINE with ARGUMENTS.

This is the shared shape of every helper below: the engine first, then the subcommand and its flags. It is exported because a subcommand without a wrapper is still a subcommand – pass ‘(list "volume" "ls")‘ and it works.

Procedure: container-available? KEY: #:engine

Return #t when ENGINE can be found on PATH.

Procedure: container-build context KEY: #:engine #:tag #:file #:target #:build-args #:labels #:no-cache? #:pull? #:platform #:network #:quiet? #:allow-failure? #:verbose?

Build the image described by CONTEXT; see ‘container-build-argv‘.

Procedure: container-build-argv context KEY: #:engine #:tag #:file #:target #:build-args #:labels #:no-cache? #:pull? #:platform #:network #:quiet?

Return the argv that builds the image described by CONTEXT.

TAG is –tag, FILE is –file, TARGET is –target, and BUILD-ARGS and LABELS are lists of strings. CONTEXT is the directory sent to the engine, normally the last argument.

Procedure: container-exec name command KEY: #:engine #:interactive? #:tty? #:env #:workdir #:user #:allow-failure? #:verbose?

Run COMMAND in the container NAME; see ‘container-exec-argv‘.

Procedure: container-exec-argv name command KEY: #:engine #:interactive? #:tty? #:env #:workdir #:user

Return the argv that runs COMMAND in the container NAME.

COMMAND is a list of strings. INTERACTIVE? and TTY? are the usual -i and -t; a non-interactive command needs neither, which is what a build step wants.

Procedure: container-images KEY: #:engine #:arguments #:allow-failure?

List images; see ‘container-images-argv‘.

Procedure: container-images-argv KEY: #:engine #:arguments

Return the argv that lists images, with any extra ARGUMENTS.

Procedure: container-inspect names KEY: #:engine #:format #:type #:allow-failure?

Inspect NAMES; see ‘container-inspect-argv‘.

Procedure: container-inspect-argv names KEY: #:engine #:format #:type

Return the argv that inspects NAMES.

FORMAT is passed as –format, which is how a task reads a field rather than the whole JSON document. TYPE is –type for engines that accept it.

Procedure: container-logs name KEY: #:engine #:follow? #:tail #:since #:allow-failure?

Print the logs of the container NAME; see ‘container-logs-argv‘.

Procedure: container-logs-argv name KEY: #:engine #:follow? #:tail #:since

Return the argv that prints the logs of the container NAME.

FOLLOW? is –follow; TAIL is a number or the word all, passed as –tail; SINCE is passed as –since.

Procedure: container-output arguments KEY: #:engine #:allow-failure?

Run ENGINE with ARGUMENTS and return its output as a string.

This is the reading counterpart of ‘container‘: the output is a value a task can trim and compare rather than a line on the terminal. In dry-run mode nothing runs, the command is printed, and the empty string comes back.

Procedure: container-ps KEY: #:engine #:all? #:allow-failure?

List containers; see ‘container-ps-argv‘.

Procedure: container-ps-argv KEY: #:engine #:all?

Return the argv that lists containers, including stopped ones with ALL?.

Procedure: container-pull image KEY: #:engine #:allow-failure?

Pull IMAGE; see ‘container-pull-argv‘.

Procedure: container-pull-argv image KEY: #:engine

Return the argv that pulls IMAGE.

Procedure: container-push image KEY: #:engine #:allow-failure?

Push IMAGE; see ‘container-push-argv‘.

Procedure: container-push-argv image KEY: #:engine

Return the argv that pushes IMAGE.

Procedure: container-rm names KEY: #:engine #:force? #:volumes? #:allow-failure?

Remove the containers NAMES; see ‘container-rm-argv‘.

Procedure: container-rm-argv names KEY: #:engine #:force? #:volumes?

Return the argv that removes the containers NAMES.

FORCE? is the default because a task that removes a container means it, and a running container would otherwise fail the whole task.

Procedure: container-run image KEY: #:engine #:command #:name #:detach? #:remove? #:interactive? #:tty? #:env #:publish #:volume #:mount #:workdir #:entrypoint #:network #:user #:platform #:pull #:labels #:privileged? #:allow-failure? #:verbose?

Run IMAGE as a container; see ‘container-run-argv‘ for the options.

Procedure: container-run-argv image KEY: #:engine #:command #:name #:detach? #:remove? #:interactive? #:tty? #:env #:publish #:volume #:mount #:workdir #:entrypoint #:network #:user #:platform #:pull #:labels #:privileged?

Return the argv that runs IMAGE as a container.

COMMAND is the list of arguments passed to the image, after its name. The defaults are the ones an unattended task wants: REMOVE? is #t, so a finished container leaves nothing behind, and nothing is attached to the terminal unless INTERACTIVE? or TTY? asks for it. ENV, PUBLISH, VOLUME, MOUNT and LABELS are lists of strings, each passed with its flag.

Procedure: container-stop names KEY: #:engine #:allow-failure?

Stop the containers NAMES, a list of strings.

Procedure: container-stop-argv names KEY: #:engine

Return the argv that stops the containers NAMES.

Procedure: container-tag source target KEY: #:engine #:allow-failure?

Tag SOURCE as TARGET; see ‘container-tag-argv‘.

Procedure: container-tag-argv source target KEY: #:engine

Return the argv that gives SOURCE the additional name TARGET.

Procedure: cp x y KEY: #:recursive? #:force? #:verbose? #:verbose-copy? #:expand?

Copy a file or directory from X to Y.

ARGUMENTS: x: Source file or directory. y: Destination path.

recursive?: If #t, copy directories recursively (‘-r‘). Defaults to #t. force?: If #t, overwrite existing files without prompting (‘-f‘). Defaults to #f. verbose?: If #t, logs the final shell command before execution. Defaults to #f. verbose-copy?: If #t, enables verbose output from ‘cp‘ (‘-v‘). Defaults to #t. expand?: If #t, the shell expands X and Y, so a wildcard names the files it matches. Defaults to #f, which passes both as one argument each.

Constructs and executes a command of the form:

cp [OPTIONS] X Y

through ‘run‘, so X and Y reach ‘cp‘ as one argument each and a path with a space in it is copied rather than split.

RETURNS: #t if the copy succeeds.

ERRORS: Signals an error if the underlying ‘cp‘ command exits with a non-zero status.

Procedure: curl arguments KEY: #:allow-failure? #:verbose?

Run curl with ARGUMENTS, a list of strings; see ‘curl-argv’.

Procedure: curl-argv arguments

Return the argv that runs curl with ARGUMENTS.

The escape hatch for a flag no helper models; nothing is handed to a shell, so an argument with a space in it stays one argument.

Procedure: curl-download url KEY: #:output #:directory #:create-dirs? #:resume? #:headers #:follow? #:fail? #:silent? #:show-error? #:compressed? #:timeout #:retry #:user #:user-agent #:insecure? #:cookie #:cookie-jar #:extra #:allow-failure? #:verbose?

Download URL with curl; see ‘curl-download-argv’.

Procedure: curl-download-argv url KEY: #:output #:directory #:create-dirs? #:resume? #:headers #:follow? #:fail? #:silent? #:show-error? #:compressed? #:timeout #:retry #:user #:user-agent #:insecure? #:cookie #:cookie-jar #:extra

Return the argv that downloads URL to OUTPUT.

Without OUTPUT curl keeps the remote name, which is what –remote-name means. DIRECTORY is curl’s –output-dir, and CREATE-DIRS? makes the parents of the destination. RESUME? continues a partial download.

Procedure: curl-get url KEY: #:output #:output-dir #:create-dirs? #:resume? #:headers #:follow? #:fail? #:silent? #:show-error? #:compressed? #:timeout #:retry #:user #:user-agent #:insecure? #:cookie #:cookie-jar #:extra #:allow-failure? #:verbose?

Fetch URL with curl; see ‘curl-get-argv’ for the options.

Procedure: curl-get-argv url KEY: #:output #:output-dir #:create-dirs? #:resume? #:headers #:follow? #:fail? #:silent? #:show-error? #:compressed? #:timeout #:retry #:user #:user-agent #:insecure? #:cookie #:cookie-jar #:extra

Return the argv that fetches URL with curl.

The defaults are the ones a task wants: redirects are followed, an HTTP error is a failure, and the progress meter is replaced by silence plus real errors. OUTPUT writes the body to a file, OUTPUT-DIR names the directory for it, and CREATE-DIRS? creates the parents. RESUME? continues a partial file.

Procedure: curl-head url KEY: #:headers #:follow? #:fail? #:silent? #:show-error? #:timeout #:retry #:user #:user-agent #:insecure? #:cookie #:extra #:allow-failure? #:verbose?

Ask for URL’s headers with curl; see ‘curl-head-argv’.

Procedure: curl-head-argv url KEY: #:headers #:follow? #:fail? #:silent? #:show-error? #:timeout #:retry #:user #:user-agent #:insecure? #:cookie #:extra

Return the argv that asks for URL’s headers with a HEAD request.

Procedure: curl-output arguments KEY: #:allow-failure?

Run curl with ARGUMENTS and return what it printed.

This is the reading counterpart of ‘curl’: the body is a value a task can trim, split or parse. In dry-run mode nothing runs, the command is printed, and the empty string comes back.

Procedure: curl-post url KEY: #:data #:json #:data-file #:form #:method #:headers #:follow? #:fail? #:silent? #:show-error? #:compressed? #:timeout #:retry #:user #:user-agent #:insecure? #:cookie #:cookie-jar #:extra #:allow-failure? #:verbose?

Send a POST request to URL; see ‘curl-post-argv’.

Procedure: curl-post-argv url KEY: #:data #:json #:data-file #:form #:method #:headers #:follow? #:fail? #:silent? #:show-error? #:compressed? #:timeout #:retry #:user #:user-agent #:insecure? #:cookie #:cookie-jar #:extra

Return the argv that sends a POST request to URL.

DATA is a body string, JSON is a JSON body sent with curl’s –json (which also sets the content type and Accept header), DATA-FILE is a file whose bytes are the body, and FORM is a list of –form fields. At least one of them must be given. METHOD defaults to POST; pass another method for an API that spells its update differently.

Procedure: curl-status url KEY: #:headers #:follow? #:timeout #:retry #:user #:user-agent #:insecure? #:cookie #:extra #:allow-failure?

Return URL’s HTTP status code as a number.

A transport failure raises unless ALLOW-FAILURE? is #t, in which case #f is returned when curl prints no code. An HTTP error is still a status: 404 comes back as 404.

Procedure: curl-status-argv url KEY: #:headers #:follow? #:timeout #:retry #:user #:user-agent #:insecure? #:cookie #:extra

Return the argv that prints URL’s HTTP status code.

The body is discarded and –fail is deliberately left off, so a 404 is reported as 404 rather than as a failed download.

Procedure: curl-text url KEY: #:headers #:follow? #:fail? #:timeout #:retry #:user #:user-agent #:insecure? #:cookie #:extra #:allow-failure?

Fetch URL with curl and return the body as a string.

Use this instead of ‘curl-get’ when the task needs the response, not a line on the terminal. A non-zero curl exits non-zero and raises, unless ALLOW-FAILURE? is #t.

Procedure: curl-text-argv url KEY: #:headers #:follow? #:fail? #:timeout #:retry #:user #:user-agent #:insecure? #:cookie #:extra

Return the argv that fetches URL’s body for a task to read.

Procedure: curl-upload url file KEY: #:method #:headers #:follow? #:fail? #:silent? #:show-error? #:compressed? #:timeout #:retry #:user #:user-agent #:insecure? #:cookie #:cookie-jar #:extra #:allow-failure? #:verbose?

Upload FILE to URL with curl; see ‘curl-upload-argv’.

Procedure: curl-upload-argv url file KEY: #:method #:headers #:follow? #:fail? #:silent? #:show-error? #:compressed? #:timeout #:retry #:user #:user-agent #:insecure? #:cookie #:cookie-jar #:extra

Return the argv that uploads FILE to URL with curl.

METHOD defaults to PUT, which is what an object store usually expects; pass POST for an API that takes the file as a form upload.

Procedure: decorate-command cmd KEY: #:env #:sudo? #:dev-null?

Return CMD with the decorations a task asked for, applied in a fixed order.

The environment comes first and goes through ‘env’ rather than as a ‘KEY=VALUE’ prefix, because everything after a ‘guix shell –’ is executed directly: a prefix there would be looked up as a program name and fail with 127.

Whether a failure is allowed is not a decoration of the command line at all; ‘syscall’ reads the exit code, which a ‘|| true’ in the line would have hidden. Backgrounding is not one either: a trailing ‘&’ leaves nothing to wait on, so ‘#:async?’ forks instead and hands back a job (see ‘run’).

Procedure: dedent-string str

Remove the common leading indentation from a multiline STR.

Tabs are expanded to four spaces, leading and trailing blank lines are removed, and the smallest indentation shared by the remaining lines is stripped from all of them. Blank lines in the middle are preserved as empty lines.

(dedent-string "   hello world")
⇒ "hello world"
Procedure: delete-file-recursively dir KEY: #:verbose? #:expand?

Delete a directory and all its contents recursively. Runs ‘rm -rfv DIR‘ through ‘run‘, so DIR reaches ‘rm‘ as one argument however it is spelled. The deletion is recursive, forced and verbose.

With EXPAND? #t the shell expands DIR, so ‘build/*.o’ names every matching file; the same opt-in applies to the other file helpers via ‘run’.

ARGUMENTS:

  • dir (string): The path of the directory (or file) to delete.
  • #:verbose? (boolean, default #f): If #t, logs the generated command before executing it.

RETURNS: #t if the command succeeded.

ERRORS: Signals an error if the underlying shell command exits with a non-zero status.

Procedure: detect-compose-command KEY: #:engine #:path #:preferred

Return the words that run Compose, as a list.

PREFERRED, when non-empty, is split on whitespace and used as it stands. For Podman, the standalone ‘podman-compose‘ is preferred when it is installed, and ‘podman compose‘ is used otherwise; Docker always answers ‘docker compose‘. The engine is passed in rather than read from the parameter, so the result is a pure function of its arguments.

Procedure: detect-container-engine KEY: #:path #:preferred

Return the container engine maak should use.

PREFERRED, when non-empty, wins unchanged. Otherwise Podman is chosen when it is on PATH, then Docker. The fallback is Podman even when neither is installed, so a missing engine is reported as a missing program rather than silently replaced by another one.

PATH is the search path, PATH itself by default, so the choice can be tested without changing the process environment.

(detect-container-engine #:path search-path)
(detect-container-engine #:preferred engine-name)
Procedure: detect-elevation-command KEY: #:path #:preferred

Return the command maak should use to run something as root.

PREFERRED, when non-empty, wins unchanged, which is how ‘MAAK_ELEVATE’ lets a user name an escalation program maak has never heard of. Otherwise ‘doas’ is chosen when it is on PATH, and ‘sudo’ when it is not: ‘doas’ is the smaller tool and the one a machine that has it usually means, while ‘sudo’ remains the fallback every other system understands.

PATH is the search path, ‘PATH’ itself by default, so the function can be tested without changing the process environment.

(detect-elevation-command #:path "/usr/bin:/bin")     ;; => "sudo"
(detect-elevation-command #:preferred "doas -n")      ;; => "doas -n"
Procedure: detect-fetch-command KEY: #:path #:preferred

Return the download program ‘download’ should use.

PREFERRED, when non-empty, wins unchanged. Otherwise curl is chosen when it is on PATH, then wget. The fallback is curl even when neither is installed, so a missing program is reported as a missing program rather than silently replaced by the other one.

PATH is the search path, PATH itself by default, so the choice can be tested without changing the process environment.

(detect-fetch-command #:path search-path)
(detect-fetch-command #:preferred "wget")
Procedure: detect-package-manager KEY: #:directory

Return the package manager DIRECTORY pins, named as its program is.

The lock file is the answer because it is the file the manager itself wrote: ‘package-lock.json’ is npm’s, ‘pnpm-lock.yaml’ is pnpm’s and ‘yarn.lock’ is yarn’s. A checkout with none of them answers ‘npm’, the manager every machine with Node already has.

DIRECTORY is the project’s root, the current directory by default, so the function can be tested without changing where the process runs.

Procedure: download url KEY: #:output #:directory #:continue? #:headers #:user #:password #:user-agent #:timeout #:retries #:quiet? #:tool #:allow-failure? #:verbose?

Download URL with the detected downloader.

TOOL is curl or wget; the default comes from ‘fetch-command’, which is curl when it is installed, wget otherwise, or whatever MAAK_FETCH names. OUTPUT is the destination file (the remote name when it is #f), DIRECTORY is the directory it belongs in, and CONTINUE? resumes a partial file. HEADERS, USER-AGENT, TIMEOUT and RETRIES are passed to either program; USER and PASSWORD become curl’s –user or wget’s –user/–password.

(download "https://example.org/release.tar.gz"
          #:output "release.tar.gz"
          #:continue? #t)
(parameterize ((fetch-command "wget"))
  (download "https://example.org/" #:output "index.html"))
Procedure: elisp-byte-compile files KEY: #:load-paths #:warnings-as-errors?

Byte-compile FILES in batch, with LOAD-PATHS on the load path.

With WARNINGS-AS-ERRORS? a warning from the compiler fails the command, which is what a CI gate wants; the default reports the warnings and succeeds.

Procedure: elisp-checkdoc files KEY: #:load-paths

Run ‘checkdoc’ on FILES in batch, with LOAD-PATHS on the load path.

checkdoc reports; it does not fail the command. A gate that has to fail is ‘elisp-byte-compile’ with ‘#:warnings-as-errors? #t’.

Procedure: elisp-ert test-files KEY: #:load-paths #:selector

Load TEST-FILES and run the ERT tests matching SELECTOR in batch.

SELECTOR is ERT’s selector as an Emacs Lisp expression, ‘t‘ by default, so every test runs. A string selector is written quoted for Lisp – ‘"\"foo\""‘ – and a tag selector as the form it is, ‘"(tag smoke)"‘. The expression is inserted as written, which is safe because it comes from the Maak file rather than from a report. Emacs exits non-zero when a test fails.

Procedure: elisp-feature path

Return the first feature PATH provides, or #f.

Procedure: elisp-files OPT: directory

Return every ‘.el’ file under DIRECTORY, recursively, sorted.

Hidden directories and their contents are skipped, which leaves a checkout’s ‘.git’ and an editor’s cache out of the list.

Procedure: elisp-footer? path

Return #t when PATH carries its ‘;;; FILE ends here’ footer.

Procedure: elisp-header path field

Return the value of the ‘;; FIELD:’ header in PATH, or #f.

This is how a package’s version and requirements are written in the file itself, above the commentary.

Procedure: elisp-lexical-binding? path

Return #t when PATH sets lexical-binding on its first line.

Procedure: elisp-package-requires path

Return the ‘;; Package-Requires:’ header of PATH as it is written, or #f.

Procedure: elisp-package-version path

Return the ‘;; Version:’ header of PATH, or #f.

Procedure: elisp-practices path

Return the conventions PATH is missing, as a list of sentences.

The list is empty when the file keeps them all. The checks are the parts of the Emacs Lisp packaging conventions that a reader can see without running anything: lexical binding, the version header, the commentary and code sections, the feature it provides, and the footer.

Procedure: elisp-practices-ok? path

Return #t when PATH keeps every convention ‘elisp-practices’ checks.

Procedure: elisp-provides path

Return the features PATH provides, as written by ‘(provide ...)’.

Procedure: elisp-quote text

Return TEXT as an Emacs Lisp string literal.

The quotes and backslashes are escaped, so a selector or a path reaches the ‘–eval’ expression as data rather than as more Lisp.

Procedure: elisp-version

Return the Emacs version the configured program reports.

Procedure: emacs-batch . options

Run Emacs in batch, forwarding OPTIONS to ‘emacs-batch-argv’.

(emacs-batch #:functions '("batch-byte-compile")
             #:arguments '("foo.el"))
Procedure: emacs-batch-argv KEY: #:quick? #:load-paths #:load-files #:evals #:functions #:arguments

Return the argv that runs Emacs in batch, without running it.

QUICK? adds ‘-Q’, which keeps the site file and the init file out of the run; it is on by default because a package’s CI should not depend on the machine’s configuration. LOAD-PATHS become ‘-L’ words and LOAD-FILES ‘-l’ words; EVALS become ‘–eval’ and FUNCTIONS ‘-f’. ARGUMENTS are appended last, where a function such as ‘batch-byte-compile’ reads the files it was given.

(emacs-batch-argv #:load-paths '(".") #:evals '("(princ emacs-version)"))
⇒ ("emacs" "--batch" "-Q" "-L" "." "--eval" "(princ emacs-version)")
Procedure: emacs-capture . options

Run Emacs in batch with OPTIONS and return its standard output.

This is the keyword form of ‘emacs-output’: ‘(emacs-capture #:evals ’("(princ emacs-version)"))’.

Procedure: emacs-output argv KEY: #:allow-failure?

Run the Emacs batch ARGV and return its standard output.

A query runs even in a dry run, because it reads the project rather than changing it. An expression that prints with ‘princ’ is what puts a value on this output; ‘message’ writes to standard error.

Procedure: env-file-entries path

Return the ‘(NAME . VALUE)’ assignments in the environment file PATH.

Blank lines and lines whose first non-blank character is ‘#’ are skipped, as are lines without an ‘=’. A leading ‘export ’ is accepted so a file that is valid for a POSIX shell is valid here too. The name and the value are trimmed, and a value wrapped in matching single or double quotes is unwrapped.

(env-file-entries ".env")
⇒ (("CI" . "1") ("DATABASE_URL" . "postgres://localhost/dev"))
Procedure: env-get name OPT: default

Return the value of environment variable NAME, or DEFAULT when unset.

Procedure: env-set! name value

Set environment variable NAME to VALUE and return VALUE.

Procedure: env-unset! name

Remove environment variable NAME.

Procedure: environment-assignments env

Return ENV as a list of ‘KEY=VALUE’ strings.

ENV may be #f, a single string, a list of strings, or an alist of pairs, so a caller can pass whatever shape it already has. An entry that is not a pair is used as it stands, which is what makes the plain string list useful when a value cannot be written as a literal.

Procedure: environment-flags name OPT: default

Return the whitespace-separated words of environment variable NAME.

This is how a migrated task reads ‘CFLAGS’, ‘CPPFLAGS’, ‘LDFLAGS’ or ‘LDLIBS’ when it decides to honour them. Nothing is read automatically: the task says which variable reaches which command.

(compile "src/a.c" #:flags (environment-flags "CFLAGS"))
Procedure: environment-load-paths

Return the directories named by ‘MAAK_LOAD_PATH’.

‘GUILE_LOAD_PATH’ is already honoured by Guile itself and is deliberately not merged here; this is the maak-specific extra so a task can add paths without clobbering the user’s global setting.

Procedure: exception->message key vals

Return a one-line human message for a caught error.

It prefers an attached exception message, then the message among the raising values, and only then falls back to the raw key. Guile raises many errors with a format *template* (for example ‘no code for module ~S’) plus the arguments; those are filled in here so the user never sees a bare ‘~S’.

Procedure: fetch-available? KEY: #:command

Return #t when COMMAND, the downloader ‘download’ would use, is on PATH.

Procedure: format-task-doc name doc KEY: #:needs

Return the lines that describe task NAME, given its docstring DOC.

A docstring that is one paragraph starts inline after the name, and every continuation line aligns under the first word of the documentation, so a docstring wrapped over several lines reads as one block:

build: Compile the project.
       The result lands in ./target.

A docstring with a blank line in it is a set of paragraphs, and running text would flatten that shape away, so it prints as a block instead: the name on its own line and every line indented to the same column, with the blank lines left blank.

Common leading indentation is removed first with ‘dedent-string’, so a docstring written inside an indented function still reads flush left.

NEEDS names the tasks this one requires to have finished first, and is printed under the documentation as a line of its own, aligned to the same margin; a task that needs nothing prints nothing extra.

Procedure: frontend words . options

Run the package manager with WORDS, forwarding OPTIONS to ‘frontend-argv’.

(frontend '("run" "build"))
Procedure: frontend-add packages KEY: #:dev? #:arguments

Add PACKAGES as dependencies, from the registry or the file system.

PACKAGES is one name or a list of them. DEV? asks for a development dependency, which npm and pnpm spell ‘–save-dev’ and yarn spells ‘–dev’. ARGUMENTS are the manager’s own words, appended last.

Procedure: frontend-argv words KEY: #:arguments #:directory

Return the argv that runs WORDS with the project’s package manager.

WORDS is the command and its words – ‘’("run" "build")’ for a script, or ‘’("install")’. The manager’s program comes first, then the flag that points it at DIRECTORY when one is given, then WORDS, then ARGUMENTS as they are, so an option this module does not name still reaches the manager.

(frontend-argv '("run" "build"))
⇒ ("npm" "run" "build")

(frontend-argv '("install") #:directory "web")
⇒ ("npm" "--prefix" "web" "install")
Procedure: frontend-build . arguments

Run the ‘build’ script, passing ARGUMENTS to it.

Procedure: frontend-check

Run the ‘lint’, ‘test’ and ‘build’ scripts, in that order.

The three are the scripts a web build usually has; a project that names them otherwise writes the three ‘frontend-run’ calls itself. The order is the cheap failure first, so a lint error stops the run before the bundle is built.

Procedure: frontend-ci . arguments

Install the dependencies exactly as the lock file records them.

This is what a CI run wants and what a developer’s ‘frontend-install’ must not be: it refuses to update the lock file, so a build that would have changed it fails instead. The words are the manager’s own – ‘npm ci’, ‘pnpm install –frozen-lockfile’, ‘yarn install –immutable’ (or ‘–frozen-lockfile’ on Yarn 1).

Procedure: frontend-exec command . arguments

Run COMMAND from ‘node_modules/.bin’, passing ARGUMENTS to it.

This is how a task runs a tool the project installed without knowing whether the manager needs ‘–’ between its own words and the tool’s.

Procedure: frontend-format . arguments

Run the ‘format’ script, passing ARGUMENTS to it.

Procedure: frontend-install . arguments

Install the project’s dependencies, passing ARGUMENTS to the manager.

Procedure: frontend-lint . arguments

Run the ‘lint’ script, passing ARGUMENTS to it.

Procedure: frontend-output argv KEY: #:allow-failure?

Run the frontend ARGV and return its standard output as a string.

A query runs even in a dry run: it reads the project rather than changing it – ‘npm pkg get version’ is the usual one. A failure raises a maak error naming the command, or comes back as #f when the caller asked for the exit status.

Procedure: frontend-publish . arguments

Publish the package, passing ARGUMENTS to the manager.

A dry run of the release is ‘(frontend-publish "–dry-run")’: npm’s own flag is what makes it one, while maak’s dry run prints the command instead.

Procedure: frontend-remove packages KEY: #:arguments

Remove PACKAGES from the dependencies.

PACKAGES is one name or a list of them; ARGUMENTS are the manager’s own words.

Procedure: frontend-run script . arguments

Run the package.json SCRIPT, passing ARGUMENTS to it.

‘run’ is the one verb all three managers spell the same way, so this is the wrapper a task reads best with. The words after SCRIPT go to the script, so a task that forwards a flag writes them after it:

(frontend-run "build")
(frontend-run "test" "--" "--watch")
Procedure: frontend-test . arguments

Run the ‘test’ script, passing ARGUMENTS to it.

Procedure: git arguments KEY: #:directory #:allow-failure? #:verbose?

Run git with ARGUMENTS, a list of strings, in DIRECTORY.

This is what every wrapper below is made of, and the way to reach a command that has no wrapper – git fetch, git reset, a subcommand added tomorrow. Nothing is handed to a shell, so a value with spaces in it stays one argument.

(git (list "fetch" "--all"))
(git (list "log" "--oneline" "-3") #:directory "/path/to/checkout")

A command that exits non-zero raises a maak error naming it, unless ALLOW-FAILURE? is #t, in which case the call answers #f.

Procedure: git-add . paths

Stage PATHS, or every change in the tree when none is named.

Procedure: git-archive output KEY: #:format #:prefix #:revision #:directory

Write REVISION as OUTPUT with git archive, under PREFIX, in FORMAT.

FORMAT is one git archive understands, tar.gz and zip being the usual ones. PREFIX is the directory the archive unpacks into, and it carries its own trailing slash. DIRECTORY is the checkout to read from.

(git-archive "maak-1.0.tar.gz" #:prefix "maak-1.0/")
Procedure: git-archive-tar output KEY: #:prefix #:revision #:directory

Write REVISION as the gzipped tarball OUTPUT, under PREFIX.

Procedure: git-archive-zip output KEY: #:prefix #:revision #:directory

Write REVISION as the zip OUTPUT, under PREFIX.

Procedure: git-argv arguments KEY: #:directory

Return the argv that runs git with ARGUMENTS in DIRECTORY.

The checkout is named with -C rather than by changing maak’s working directory, so a task can read another checkout without disturbing its own. Exposed because the argument list is the interface every wrapper shares: a test can assert it, and a caller can log or extend it without running git.

Procedure: git-branch . names

List the branches, or create the branches NAMES name.

Procedure: git-checkout . arguments

Run git checkout with ARGUMENTS.

For a branch, git-switch says what it means; this wrapper is for the rest of git checkout – restoring paths, detached commits, --orphan.

Procedure: git-cherry-pick . arguments

Cherry-pick with any arguments git cherry-pick takes.

Procedure: git-clean . arguments

Remove untracked files with any arguments git clean takes.

git clean does nothing without -f; pass it, and -d for directories, because there is no safer default that would still be useful.

Procedure: git-clone url KEY: #:directory #:branch #:depth #:bare? #:verbose?

Clone URL into DIRECTORY, with BRANCH, DEPTH or BARE? when given.

git clone is the one command that cannot be pointed at a checkout with -C, because the checkout it makes is the destination; the destination is therefore the final argument rather than a decoration. Without DIRECTORY git names the directory after the repository, exactly as it does on the command line.

(git-clone "https://example.org/project.git" #:depth 1)
(git-clone "../other" #:directory "vendor/other" #:branch "trunk")
Procedure: git-commit message KEY: #:all? #:amend? #:allow-empty? #:sign?

Commit with MESSAGE, every tracked change by default.

ALL? is the -a that stages modified and deleted tracked files without a separate git add; it is #t for the common case of committing the working tree. AMEND? replaces the last commit, ALLOW-EMPTY? makes a commit with no changes, and SIGN? signs it with the configured GPG key.

(git-commit "fix: keep the config when it is missing")
(git-commit "docs: typo" #:all? #f)     ;; commit only what is staged
Procedure: git-config . arguments

Read or write configuration with any arguments git config takes.

Procedure: git-current-branch KEY: #:directory

Return the branch the checkout in DIRECTORY is on.

A detached HEAD answers with the revision rather than the word HEAD, so a task that tags a release from CI still gets something it can record.

Procedure: git-current-revision KEY: #:directory

Return the full hash of the commit checked out in DIRECTORY.

Procedure: git-describe . arguments

Describe a commit, with any arguments git describe takes.

Procedure: git-describe-tag KEY: #:directory

Return the most recent tag reachable from HEAD in DIRECTORY.

(git-describe-tag)   ;; => v0.10.0
Procedure: git-diff . arguments

Show the changes between the working tree and the index, or as ARGUMENTS say.

Use --cached to compare the index with the last commit, or name two revisions to compare them with each other.

Procedure: git-dirty? KEY: #:directory

Return #t when the checkout in DIRECTORY has anything uncommitted.

Both staged and unstaged changes count, as do untracked files: this is the question git status --porcelain answers, rather than the narrower one git diff --quiet answers.

Procedure: git-fetch . arguments

Fetch from the remote, with any arguments git fetch takes.

Procedure: git-init . arguments

Initialise a git repository here, with any arguments git init takes.

Procedure: git-log . arguments

Show the history as a decorated one-line graph, twenty commits by default.

Procedure: git-merge . arguments

Merge with any arguments git merge takes.

Procedure: git-output arguments KEY: #:directory #:allow-failure?

Run git with ARGUMENTS in DIRECTORY and return what it printed.

This is the reading half of git: the output is a string the task can trim, split and compare, not a line on the terminal. A command that exits non-zero raises, unless ALLOW-FAILURE? is #t, in which case the partial output is returned – the same contract as capture. In dry-run mode nothing runs, the command is printed, and the empty string comes back.

(string-trim (git-output (list "rev-parse" "--abbrev-ref" "HEAD")))
Procedure: git-pull . arguments

Pull from the upstream branch, with any arguments git pull takes.

Procedure: git-push . arguments

Push the current branch, with any arguments git push takes.

A bare push does not send tags that are not annotated; (git-push "--tags") sends them too.

Procedure: git-rebase . arguments

Rebase with any arguments git rebase takes.

Procedure: git-remote . arguments

Manage remotes with any arguments git remote takes.

(git-remote (list "add" "origin" "https://example.org/project.git"))
(git-remote (list "-v"))
Procedure: git-remote-url name KEY: #:directory

Return the URL configured for remote NAME in DIRECTORY.

Procedure: git-remotes KEY: #:directory

Return the names of the remotes configured in DIRECTORY, sorted.

Procedure: git-reset . arguments

Reset with any arguments git reset takes.

--soft and --mixed keep the changes; --hard throws them away, which is what makes this wrapper worth naming explicitly in a task.

Procedure: git-restore . arguments

Restore paths with any arguments git restore takes.

Procedure: git-rev-parse . arguments

Ask git about revisions, with any arguments git rev-parse takes.

Procedure: git-revert . arguments

Revert with any arguments git revert takes.

Procedure: git-show . arguments

Show a commit, tag or other object, with any arguments git show takes.

Procedure: git-stash . arguments

Stash with any arguments git stash takes.

The bare call saves the working tree; pass pop to bring it back, or list to see what is saved.

Procedure: git-status

Show the current branch and a short status of the working tree.

Procedure: git-submodule . arguments

Manage submodules with any arguments git submodule takes.

Procedure: git-switch branch KEY: #:create? #:force?

Switch to BRANCH, creating it with CREATE? or discarding local changes with FORCE? when asked.

git switch is the modern spelling of the checkout half of git checkout: it changes branches and nothing else, which is why it is the default here.

Procedure: git-tag name KEY: #:message #:force?

Tag the current commit as NAME, without an annotation unless MESSAGE is given.

An annotated tag is what git push --follow-tags and most release tooling expects, so passing MESSAGE is the usual choice for a release; a lightweight tag is the default because it changes nothing in the history.

(git-tag "v1.2.0" #:message "maak 1.2.0")
Procedure: git-tags KEY: #:directory

Return the names of the tags in DIRECTORY, sorted.

Procedure: gradle tasks . options

Run the Gradle TASKS, forwarding OPTIONS to ‘gradle-argv’.

(gradle "test" #:arguments '("--tests" "*Integration*"))
Procedure: gradle-argv tasks KEY: #:arguments #:project-dir #:build-file #:properties #:exclude-tasks #:offline? #:refresh-dependencies? #:no-daemon? #:parallel? #:build-cache? #:rerun-tasks? #:continue? #:stacktrace? #:full-stacktrace? #:warning-mode #:console #:quiet? #:info? #:debug? #:max-workers

Return the argv that runs the Gradle TASKS, without running it.

TASKS is a task name or a list of them, as Gradle spells them (‘:module:task‘ included). PROJECT-DIR and BUILD-FILE choose the build; PROPERTIES become ‘-P’ words; EXCLUDE-TASKS become ‘-x’ words. The daemon, cache, parallel and rerun flags are keywords, because they decide how a machine runs the build. ARGUMENTS are appended as they are.

(gradle-argv '("clean" "build")
             #:project-dir "service"
             #:properties '(("version" . "1.2.3"))
             #:no-daemon? #t)
⇒ ("gradle" "--project-dir" "service" "-Pversion=1.2.3"
           "--no-daemon" "clean" "build")
Procedure: gradle-assemble . arguments

Assemble the project’s artefacts, passing ARGUMENTS.

Procedure: gradle-build . arguments

Run the full build, passing ARGUMENTS.

Procedure: gradle-check . arguments

Run the checks, passing ARGUMENTS.

Procedure: gradle-clean . arguments

Remove the build output, passing ARGUMENTS.

Procedure: gradle-dependencies . arguments

Print the dependency report, passing ARGUMENTS.

Procedure: gradle-output argv KEY: #:allow-failure?

Run the Gradle ARGV and return its standard output.

A query runs even in a dry run, because it reads the project rather than changing it.

Procedure: gradle-projects . arguments

List the project’s modules, passing ARGUMENTS.

Procedure: gradle-publish . arguments

Publish the artefacts, passing ARGUMENTS.

Procedure: gradle-run . arguments

Run the application task, passing ARGUMENTS.

Procedure: gradle-tasks . arguments

List the project’s tasks, passing ARGUMENTS.

Procedure: gradle-test . arguments

Run the tests, passing ARGUMENTS.

Procedure: gradle-wrapper-command OPT: directory

Return the Gradle command to use in DIRECTORY.

A checkout with an executable ‘gradlew’ answers with it, because that is the Gradle version the project pins; otherwise the answer is ‘gradle-command’.

Procedure: gradle-wrapper? OPT: directory

Return #t when DIRECTORY holds an executable Gradle wrapper.

Procedure: guix-available?

Return #t when a ‘guix’ program is on ‘PATH’.

Procedure: guix-build package KEY: #:channels #:system

Build PACKAGE as CHANNELS pins it and return its output path.

Building is what makes the answer usable: the output path is the directory the package installed into, with its ‘bin’, ‘lib’ and ‘share’ underneath.

(guix-build "hello")
⇒ "/gnu/store/…-hello-2.12.3"

Guix’s own build log goes to standard error as it does for ‘guix build’, so a long build still shows its progress.

Procedure: guix-build-at revision package KEY: #:url #:system

Build PACKAGE at Guix REVISION and return its output path.

The pinned form of ‘guix-build’: REVISION is a commit of the Guix repository at URL, and no channels file is read.

Procedure: guix-channels KEY: #:file

Return the channel pins FILE names, as an alist of name and commit.

(guix-channels)
⇒ (("guix" . "0fb918d61609f3aadc2d8ecc212926b3bdfabb4c"))

The file is a normal ‘channels.scm’, the one ‘guix describe -f channels’ writes; the answer names every channel it lists, in the order they appear. This is the pin the ‘-at’ helpers replace, and the one ‘guix time-machine’ would read.

Procedure: guix-container cmd-parts KEY: #:manifest #:pure? #:network? #:share #:expose #:join #:verbose? #:env #:sudo? #:dev-null? #:allow-failure? #:async?

Run CMD-PARTS in a Guix container defined by MANIFEST.

A container isolates the process from the host: no network unless NETWORK? is #t, no access to the home directory unless it is SHARE’d. SHARE and EXPOSE are lists of ‘HOST=DEST’ (or ‘HOST’) strings passed through as ‘-S’ and ‘-E’.

(guix-container '("maak test")
                #:manifest "manifest.scm"
                #:share '("/home/joe"))
Procedure: guix-derivation package KEY: #:channels #:system

Return the derivation file name of PACKAGE as CHANNELS pins it.

PACKAGE is a package name, looked up in the Guix that CHANNELS names rather than in the one running. SYSTEM is the target system, or #f for this machine’s. Nothing is built: the derivation is the recipe, and its file name is enough for ‘guix build’ or for a later ‘build-derivations’.

(guix-derivation "hello")
⇒ "/gnu/store/…-hello-2.12.3.drv"

A channels file that has never been fetched is fetched here, with the network and the time that takes; afterwards Guix’s channel cache answers at once.

Procedure: guix-derivation-at revision package KEY: #:url #:system

Return the derivation file name of PACKAGE at Guix REVISION.

REVISION is a commit of the Guix repository at URL, which defaults to the canonical one. This is the ‘guix time-machine –commit=REVISION’ question asked as a value: which Guix is not the one running, and no channels file has to exist for it.

(guix-derivation-at "0fb918d61609f3aadc2d8ecc212926b3bdfabb4c" "hello")
Procedure: guix-pack cmd-parts KEY: #:file #:format #:image-tag #:output #:relocatable? #:symlinks #:extra-packages #:join #:verbose? #:env #:sudo? #:dev-null? #:allow-failure? #:async?

Build a ‘guix pack’ of the program in FILE.

FORMAT is any ‘guix pack –format’ value ("docker", "squashfs", "tarball"). IMAGE-TAG names a docker image, OUTPUT names the file to write instead of letting ‘guix pack’ choose one, SYMLINKS are ‘TARGET=SOURCE’ entries for ‘-S’, and EXTRA-PACKAGES are appended to the pack. With RELOCATABLE? a tarball is made relocatable, so it can be extracted anywhere rather than at ‘/’.

(guix-pack '() #:format "docker" #:image-tag "maak"
           #:symlinks '("/bin=bin") #:extra-packages '("bash"))
Procedure: guix-program package args KEY: #:program #:channels #:system #:verbose? #:env #:sudo? #:dev-null? #:allow-failure? #:async?

Run a program from PACKAGE as CHANNELS pins it.

ARGS are the arguments the program gets, each a string. PROGRAM names the program inside the package’s output and defaults to the package’s own name: a bare name is looked for in ‘bin’, and a name with a slash in it is taken as a path from the output’s root. The package is built first, so the program that runs is the one that pin names and not whatever the machine happens to have installed.

(guix-program "hello" '("--version"))
(guix-program "coreutils" '("-l" "/gnu/store") #:program "ls")
(guix-program "diffutils" (list "-u" a b) #:program "diff" #:async? #t)

The decorations are ‘run”s: ‘#:env’, ‘#:sudo?’, ‘#:dev-null?’, ‘#:allow-failure?’ and ‘#:async?’, so the program can be a job like any other.

In a dry run the store query is printed instead of the program line, because the path is only known once Guix has answered; #t is returned.

Procedure: guix-program-at revision package args KEY: #:program #:url #:system #:verbose? #:env #:sudo? #:dev-null? #:allow-failure? #:async?

Run a program from PACKAGE, built by Guix REVISION, with ARGS.

The pinned form of ‘guix-program’: the package comes from the Guix at REVISION of URL rather than from the pinned channels file, which is what a task wants when it has to run one old tool for one step. PROGRAM and the decorations are ‘guix-program”s.

(guix-program-at "0fb918d61609f3aadc2d8ecc212926b3bdfabb4c"
                 "hello" '(--version))
Procedure: guix-shell cmd-parts KEY: #:packages #:pure? #:manifest #:file #:join #:verbose? #:env #:sudo? #:dev-null? #:allow-failure? #:async?

Run CMD-PARTS inside a Guix shell made of PACKAGES.

This is the package-list sibling of ‘manifest-shell’ and ‘program-shell’: the environment is described inline rather than in a manifest or a ‘guix.scm’. PACKAGES may be a list of strings ("guile", "coreutils") or a single string, which is used as-is.

(guix-shell '("guile -c '(+ 1 2)'") #:packages '("guile"))
Procedure: home-dir

Return the current user’s home directory, or the empty string when unset.

Procedure: i18n-compile language KEY: #:dir #:textdomain #:verbose?

Compile LANGUAGE’s .po file into the .mo catalogue the program loads.

Procedure: i18n-compile-all languages KEY: #:dir #:textdomain #:verbose?

Run ‘i18n-compile’ for every language of LANGUAGES, skipping missing files.

Procedure: i18n-extract KEY: #:dir #:textdomain #:directories #:extensions #:keywords #:copyright-holders #:package-name #:from-code #:update? #:verbose?

Extract translatable strings from source files into the .pot template.

DIRECTIONS is the list of directories to scan, EXTENSIONS the file types in them, and KEYWORDS the function names xgettext should treat as translatable (‘G_’ by default). With UPDATE? the strings are joined into an existing template instead of starting a fresh one, which keeps translator comments and previous line references.

(i18n-extract #:directories '("lib" "app/views"))
Procedure: i18n-init language KEY: #:dir #:textdomain #:verbose?

Create LANGUAGE’s .po file from the .pot template.

The language directory is created when missing, so a new translation starts with one call. LANGUAGE is a locale name such as nl_NL.

Procedure: i18n-init-all languages KEY: #:dir #:textdomain #:only-missing? #:verbose?

Run ‘i18n-init’ for every language of LANGUAGES.

With ONLY-MISSING? (the default) a language whose .po already exists is skipped, so the call can live in a task that is run repeatedly without clobbering translators’ work with a fresh template.

Procedure: i18n-language

Return the language the process should translate into.

The first of ‘LANGUAGE’, ‘LC_ALL’, ‘LC_MESSAGES’ and ‘LANG’ that is set, with its character encoding and any modifier stripped; when none is set, ‘en_US’ is assumed.

Procedure: i18n-locale-dir language KEY: #:dir

Return the catalogue directory of LANGUAGE inside DIR.

(i18n-locale-dir "nl_NL")
⇒ "po/nl_NL/LC_MESSAGES"
Procedure: i18n-merge language KEY: #:dir #:textdomain #:verbose?

Fold the current .pot template into LANGUAGE’s .po file, in place.

Procedure: i18n-merge-all languages KEY: #:dir #:textdomain #:verbose?

Run ‘i18n-merge’ for every language of LANGUAGES, skipping missing files.

Procedure: i18n-mo-file language KEY: #:dir #:textdomain

Return the path of LANGUAGE’s compiled machine object file (the one the program loads).

Procedure: i18n-po-file language KEY: #:dir #:textdomain

Return the path of LANGUAGE’s portable object file (the one a translator edits).

Procedure: i18n-pot-file KEY: #:dir #:textdomain

Return the path of the template TEXTDOMAIN.pot inside DIR.

Procedure: i18n-refresh languages KEY: #:dir #:textdomain #:directories #:extensions #:keywords #:copyright-holders #:package-name #:verbose?

Do the whole gettext cycle: extract, merge, then compile.

This is the one call a project normally puts in its maak file; the individual steps stay available for anything more unusual.

Procedure: i18n-source-globs directories KEY: #:extensions

Return the file patterns of DIRECTORIES that ‘xgettext’ should read.

A glob that matches nothing is handed to xgettext as itself, and xgettext refuses the whole invocation over the missing file – writing no template at all rather than the strings it did find. Only directories that exist are therefore asked for, so adding or removing a source tree is all a refresh ever needs.

(i18n-source-globs '("lib" "app/views"))
Procedure: i18n-translator KEY: #:dir #:textdomain #:language

Install the catalogue in DIR for TEXTDOMAIN and return a translate procedure.

The returned procedure takes one message and returns its translation, falling back to the original when the catalogue has no entry. LANGUAGE defaults to ‘i18n-language’.

(define G_ (i18n-translator #:dir "po" #:textdomain "maak"))
(G_ "Hello")
Procedure: indent-string str KEY: #:by #:first?

Indent every line of STR by BY spaces.

When FIRST? is #f the first line is left flush, which is what aligning a continuation underneath an existing prefix needs.

Procedure: install-directory directory KEY: #:mode #:verbose? #:expand?

Create DIRECTORY and its parents with MODE.

The directory counterpart of ‘install-file’: one ‘install -d’ that sets the mode of the directory it creates, which is what a Makefile’s ‘$(MKDIR_P) $(DESTDIR)$(datadir)/app’ does.

Procedure: install-file source destination KEY: #:mode #:verbose? #:expand?

Install SOURCE at DESTINATION with MODE, creating parent directories.

This is the ‘install‘ a Makefile’s ‘install‘ target reaches for, with the destination named in full. MODE is an octal string such as "755" for a program or "644" for data. The parent directories are made with ‘mkdir-p’ first, because ‘install -D’ is a GNU extension and this works wherever ‘install’ does. A ‘DESTDIR’ staging prefix is the caller’s to compose; a task migrates a Makefile’s ‘$(DESTDIR)$(bindir)’ by concatenating it into DESTINATION.

(install-file "build/app" "/usr/local/bin/app" #:mode "755")
Procedure: job-done? job

Return #t when JOB has finished, without waiting for it.

A finished job is reaped here, so a background process that a task never waits for does not stay a zombie for the rest of the run.

Procedure: job-exit-code job

Wait for JOB when needed and return its exit code.

Returns #f when the process was terminated by a signal, which is also what ‘status:exit-val’ says about such a status.

Link OBJECTS into OUTPUT.

The keywords are ‘link-argv”s, plus VERBOSE? for the command line. Use ‘#:flags’ for ‘LDFLAGS’ (before the objects) and ‘#:link-flags’ for ‘LDLIBS’ and pkg-config’s libs (after them).

Return the argv that links OBJECTS into OUTPUT, without running it.

LIBRARIES become ‘-l’ arguments and LIBRARY-PATHS ‘-L’ arguments. FLAGS are inserted before the objects, which is where ‘LDFLAGS’ goes; LINK-FLAGS are inserted after the objects and the libraries, which is where ‘LDLIBS’ and the pre-formed flags pkg-config returns go. SHARED? adds ‘-shared’, STATIC? adds ‘-static’, and SONAME adds ‘-Wl,-soname,SONAME’, which is the usual three things a libtool link line was doing.

(link-argv '("build/a.o" "build/b.o")
           #:output "build/app" #:libraries '("m")
           #:library-paths '("build") #:flags '("-pthread")
           #:link-flags (pkg-config-libs '("zlib")))
Procedure: list-tasks KEY: #:as-is? #:style #:width #:file

List documentation for every maak task in the loaded file.

Tasks are sorted by name unless AS-IS? is #t.

STYLE is how the listing is laid out: ‘table’ aligns every documentation line on one column and is what ‘maak –list’ prints, ‘names’ prints one task name per line for a script or a picker, ‘long’ is the table with each task’s example under it, and ‘plain’ is the ‘name: documentation’ block the listing printed before the table, kept for a reader that has the shape in a script already. WIDTH, when given, is the widest line the listing may produce, which is what folds a long docstring. FILE, when given, is named in the heading.

A task that needs others to have finished first says so under its documentation, and a task that asked to be left out of the listings with ‘task-metadata!’ is left out of all of them.

Procedure: ln-s target link-name KEY: #:force? #:verbose? #:expand?

Create a symbolic link LINK-NAME pointing at TARGET.

With FORCE? (the default) an existing link is replaced, which is what ‘ln -sf’ does. With EXPAND? #t the shell expands the two paths as words.

Procedure: load-env-file path KEY: #:override?

Read the ‘NAME=VALUE’ assignments of PATH into the environment.

Returns the list of variables that were actually set. A name that is already in the environment keeps its value unless OVERRIDE? is #t: the environment a process was started with has the last word over a file next to the code, which is the precedence ‘dotenv’ established and the one that makes ‘CI=1 maak test’ behave as asked. Pass ‘#:override? #t’ when the file is meant to win.

A missing PATH is not an error – the file is optional by definition – and returns the empty list.

(load-env-file ".env")
(load-env-file ".env.local" #:override? #t)
Procedure: log-error msg . args

Undocumented procedure.

Procedure: log-info msg . args

Undocumented procedure.

Procedure: log-message msg

Undocumented procedure.

Procedure: log-separator

Undocumented procedure.

Procedure: maak-error-hint obj

Undocumented procedure.

Procedure: maak-error-message obj

Undocumented procedure.

Procedure: maak-error? obj

Undocumented procedure.

Procedure: maak-proc? x

Predicate that indicates whether a procedure is a valid maak proc.

A parameter is a procedure too – ‘(define build-args (make-parameter ’()))’ returns one – and it is a value a task reads rather than a task, so it is not a maak proc even though it can be called.

Procedure: maak-task? x

Predicate that indicates whether it is a valid maak task.

Procedure: maak-version-string

Return the one-line version banner printed by ‘maak –version’.

Procedure: make-maak-error a b

Undocumented procedure.

Procedure: manifest-shell cmd-parts KEY: #:verbose? #:pure? #:join #:manifest #:env #:sudo? #:dev-null? #:allow-failure? #:async?

Execute a command inside a Guix shell defined by a manifest file.

ARGUMENTS:

cmd-parts: A list of strings representing the command to run inside the Guix shell environment.

#:verbose?: If #t, logs the fully constructed command before execution. Defaults to #f. #:pure?: If #t, it will run in a pure isolated shell (clean). Defaults to #f. #:join: The string separator used when joining command segments. Defaults to a single space. #:manifest: Path to the manifest file (in Scheme) describing the package environment. Defaults to "manifest.scm".

Constructs and executes a command of the form:

    guix shell -m MANIFEST -- <cmd ...>

using the ‘$‘ wrapper to enforce proper execution and error handling.

RETURNS: #t if the command succeeds.

ERRORS: Signals an error if the underlying shell command exits with a non-zero status.

Procedure: maven goals . options

Run the Maven GOALS, forwarding OPTIONS to ‘maven-argv’.

(maven "package" #:arguments '("-DskipTests"))
Procedure: maven-argv goals KEY: #:arguments #:file #:settings #:profiles #:properties #:offline? #:update-snapshots? #:quiet? #:errors? #:debug? #:threads #:batch-mode? #:no-transfer-progress? #:fail-at-end? #:also-make? #:also-make-dependents? #:projects #:resume-from

Return the argv that runs the Maven GOALS, without running it.

GOALS is a goal or phase name, or a list of them. FILE names a POM or a project directory with ‘-f’; SETTINGS a settings file with ‘-s’. PROFILES and PROJECTS become ‘-P’ and ‘-pl’ lists. PROPERTIES become ‘-D’ words. THREADS is a positive number or a string such as ‘"1C"’. ARGUMENTS are appended as they are, so a plugin option this builder does not name still reaches Maven.

(maven-argv '("clean" "package")
            #:properties '(("skipTests" . "true"))
            #:profiles '("release"))
⇒ ("mvn" "-P" "release" "-DskipTests=true" "clean" "package")
Procedure: maven-clean . arguments

Remove the build output with ‘mvn clean’, passing ARGUMENTS.

Procedure: maven-compile . arguments

Compile the sources with ‘mvn compile’, passing ARGUMENTS.

Procedure: maven-dependency-tree . arguments

Print the dependency tree with ‘mvn dependency:tree’, passing ARGUMENTS.

Procedure: maven-deploy . arguments

Deploy the artefact with ‘mvn deploy’, passing ARGUMENTS.

Procedure: maven-effective-pom . arguments

Print the effective POM with ‘mvn help:effective-pom’, passing ARGUMENTS.

Procedure: maven-install . arguments

Install the artefact into the local repository, passing ARGUMENTS.

Procedure: maven-output argv KEY: #:allow-failure?

Run the Maven ARGV and return its standard output.

A query runs even in a dry run, because it reads the project rather than changing it; ‘maven help:evaluate’ is the usual one.

Procedure: maven-package . arguments

Package the artefact with ‘mvn package’, passing ARGUMENTS.

Procedure: maven-site . arguments

Build the project site with ‘mvn site’, passing ARGUMENTS.

Procedure: maven-test . arguments

Run the tests with ‘mvn test’, passing ARGUMENTS.

Procedure: maven-validate . arguments

Validate the project with ‘mvn validate’, passing ARGUMENTS.

Procedure: maven-verify . arguments

Run the verification phase with ‘mvn verify’, passing ARGUMENTS.

Procedure: maven-wrapper-command OPT: directory

Return the Maven command to use in DIRECTORY.

A checkout with an executable ‘mvnw’ answers with it, because that is the Maven version the project pins; otherwise the answer is ‘maven-command’.

Procedure: maven-wrapper? OPT: directory

Return #t when DIRECTORY holds an executable Maven wrapper.

Procedure: mkdir-p dir KEY: #:verbose? #:expand?

Create a directory and all necessary parent directories. Executes ‘mkdir -pv DIR‘ through ‘run‘. Parent directories are created as needed and each created directory is printed. A DIR that contains spaces is one directory, not several.

ARGUMENTS:

  • dir: The path of the directory to create.
  • #:verbose? (boolean, default #f): If #t, logs the generated command before executing it.

RETURNS: #t if the command completed successfully.

ERRORS: Signals an error if the underlying shell command exits with a non-zero code.

Procedure: mv x y KEY: #:verbose? #:expand?

Move or rename a file or directory. Executes ‘mv -v X Y‘ through ‘run‘, so X and Y reach ‘mv‘ as one argument each. The ‘-v‘ flag prints each move operation performed.

ARGUMENTS:

  • x (string): The source file or directory.
  • y (string): The destination path.
  • #:verbose? (boolean, default #f): If #t, logs the generated command before executing it.

RETURNS: #t if the command succeeds.

ERRORS: Signals an error if the underlying shell command returns a non-zero exit code.

Procedure: niri arguments KEY: #:json? #:allow-failure? #:verbose?

Send ARGUMENTS to ‘niri msg’.

This is the escape hatch for subcommands and flags without a wrapper. Nothing is handed to a shell, so a program name or a workspace name with a space in it reaches niri as one argument.

A command that exits non-zero raises a maak error, unless ALLOW-FAILURE? is #t, in which case the call answers #f – the usual ‘run’ contract.

Procedure: niri-action arguments KEY: #:json? #:allow-failure? #:verbose?

Perform an action with ARGUMENTS, through ‘niri msg action’.

A bare action name is enough for the ones that take no argument, such as close-window; the others take their reference after it.

(niri-action (list "focus-workspace" "2"))
(niri-action (list "spawn" "--" "foot" "-e" "htop"))
Procedure: niri-action-argv arguments KEY: #:json?

Return the argv that performs an action with its ARGUMENTS.

The action name comes first and its own flags follow, so ("focus-workspace" "2") is the argv for ‘focus-workspace 2’.

Procedure: niri-argv arguments KEY: #:json?

Return the argv that sends ARGUMENTS to ‘niri msg‘.

With JSON? the global --json flag is inserted before the subcommand, which is where niri expects it. ARGUMENTS is the subcommand and its flags: ("outputs"), ("action" "close-window"), and so on.

Procedure: niri-available?

Return #t when the niri program can be found on PATH.

Procedure: niri-capture arguments KEY: #:json? #:allow-failure?

Send ARGUMENTS to ‘niri msg’ and return what it printed.

This is the query form: the output is a string a task can trim, split or hand to a JSON parser, rather than a line on the terminal. In dry-run mode nothing runs, the command is printed, and the empty string comes back.

Procedure: niri-casts KEY: #:json? #:allow-failure?

List the screencasts.

Procedure: niri-close-window KEY: #:json? #:allow-failure?

Close the focused window.

Procedure: niri-focus-column index KEY: #:json? #:allow-failure?

Focus the column at INDEX.

Procedure: niri-focus-monitor name KEY: #:json? #:allow-failure?

Focus the monitor NAME.

Procedure: niri-focus-window id KEY: #:json? #:allow-failure?

Focus the window with ID.

Procedure: niri-focus-window-previous KEY: #:json? #:allow-failure?

Focus the previously focused window.

Procedure: niri-focus-workspace reference KEY: #:json? #:allow-failure?

Focus the workspace REFERENCE, an index or a name.

Procedure: niri-focus-workspace-previous KEY: #:json? #:allow-failure?

Focus the previous workspace.

Procedure: niri-focused-output KEY: #:json? #:allow-failure?

Print information about the focused output.

Procedure: niri-focused-window KEY: #:json? #:allow-failure?

Print information about the focused window.

Procedure: niri-fullscreen-window KEY: #:json? #:allow-failure?

Toggle fullscreen on the focused window.

Procedure: niri-keyboard-layouts KEY: #:json? #:allow-failure?

Print the configured keyboard layouts.

Procedure: niri-layers KEY: #:json? #:allow-failure?

List the open layer-shell surfaces.

Procedure: niri-move-column-to-monitor name KEY: #:json? #:allow-failure?

Move the focused column to the monitor NAME.

Procedure: niri-move-column-to-workspace reference KEY: #:json? #:allow-failure?

Move the focused column to the workspace REFERENCE.

Procedure: niri-move-window-to-monitor name KEY: #:json? #:allow-failure?

Move the focused window to the monitor NAME.

Procedure: niri-move-window-to-workspace reference KEY: #:window-id #:focus #:json? #:allow-failure?

Move the focused window, or WINDOW-ID, to the workspace REFERENCE.

FOCUS is default unless given: with #t the focus follows the window, and with #f it stays on the original workspace, which niri spells as --focus true and --focus false.

Procedure: niri-output output action . arguments

Change OUTPUT with ACTION and ARGUMENTS; see ‘niri-output-argv’.

The change is temporary and is not written to niri’s configuration file.

Procedure: niri-output-argv output action . arguments

Return the argv that changes OUTPUT with ACTION and ARGUMENTS.

The output name comes first and the action after it, which is the order ‘niri msg output’ requires: niri msg output DP-1 mode 1920x1080@60.

(niri-output-argv "DP-1" "scale" "1.5")
Procedure: niri-output-mode output mode KEY: #:allow-failure?

Set OUTPUT’s mode, such as 1920x1080@60.

Procedure: niri-output-off output KEY: #:allow-failure?

Turn OUTPUT off.

Procedure: niri-output-on output KEY: #:allow-failure?

Turn OUTPUT on.

Procedure: niri-output-position output x y KEY: #:allow-failure?

Set OUTPUT’s position on the desktop to X and Y.

Procedure: niri-output-scale output scale KEY: #:allow-failure?

Set OUTPUT’s scale, such as 1.5.

Procedure: niri-output-transform output transform KEY: #:allow-failure?

Set OUTPUT’s transform, such as 90 or flipped-180.

Procedure: niri-outputs KEY: #:json? #:allow-failure?

List the connected outputs.

Procedure: niri-overview-state KEY: #:json? #:allow-failure?

Print the overview state.

Procedure: niri-pick-color KEY: #:json? #:allow-failure?

Pick a color from the screen with the mouse.

Procedure: niri-pick-window KEY: #:json? #:allow-failure?

Pick a window with the mouse and print information about it.

Procedure: niri-power-off-monitors KEY: #:json? #:allow-failure?

Power off all monitors via DPMS.

Procedure: niri-power-on-monitors KEY: #:json? #:allow-failure?

Power on all monitors via DPMS.

Procedure: niri-quit KEY: #:skip-confirmation? #:json? #:allow-failure?

Exit niri.

SKIP-CONFIRMATION? is the default because a task that asks niri to quit is not sitting at a keyboard to press Enter.

Procedure: niri-request-error KEY: #:json? #:allow-failure?

Ask niri to return an error, which is useful for checking a client’s error handling against a live compositor.

Procedure: niri-screenshot KEY: #:json? #:allow-failure?

Open the screenshot UI.

Procedure: niri-screenshot-screen KEY: #:json? #:allow-failure?

Screenshot the focused screen.

Procedure: niri-screenshot-window KEY: #:json? #:allow-failure?

Screenshot the focused window.

Procedure: niri-set-column-width change KEY: #:json? #:allow-failure?

Change the width of the focused column by CHANGE.

Procedure: niri-set-window-width change KEY: #:id #:json? #:allow-failure?

Change the width of the focused window, or of window ID, by CHANGE.

CHANGE is a string such as +10% or 500, exactly as niri’s command line takes it.

Procedure: niri-set-workspace-name name KEY: #:json? #:allow-failure?

Set the name of the focused workspace to NAME.

Procedure: niri-spawn command KEY: #:json? #:allow-failure?

Spawn COMMAND, a list of strings, without a shell.

The -- that separates niri’s own flags from the program is added here, so a program with a flag that looks like niri’s is still passed through.

Procedure: niri-spawn-sh command KEY: #:json? #:allow-failure?

Spawn COMMAND through the shell.

Use ‘niri-spawn’ when the program and its arguments are already separate strings; this one is for a line that needs a shell.

Procedure: niri-toggle-overview KEY: #:json? #:allow-failure?

Toggle the overview.

Procedure: niri-toggle-windowed-fullscreen KEY: #:json? #:allow-failure?

Toggle windowed (fake) fullscreen on the focused window.

Procedure: niri-unset-workspace-name KEY: #:json? #:allow-failure?

Unset the name of the focused workspace.

Procedure: niri-version KEY: #:json? #:allow-failure?

Print the version of the running niri instance.

Procedure: niri-windows KEY: #:json? #:allow-failure?

List the open windows.

Procedure: niri-workspaces KEY: #:json? #:allow-failure?

List the workspaces.

Procedure: nix-build KEY: #:file #:arguments #:out-link #:verbose? #:env #:sudo? #:dev-null? #:allow-failure? #:async?

Build the derivation in FILE with the classic ‘nix-build’.

ARGUMENTS are extra words passed through verbatim, for example ‘–argstr system x86_64-linux’. OUT-LINK names the result symlink (‘–out-link’), defaulting to Nix’s own ‘result’.

Procedure: nix-develop cmd-parts KEY: #:flake #:impure? #:join #:verbose? #:env #:sudo? #:dev-null? #:allow-failure? #:async?

Run CMD-PARTS inside the development shell of the flake FLAKE.

FLAKE is a path or flake reference such as ‘.‘ or ‘github:owner/repo’. With IMPURE? the shell inherits the host environment (‘–impure’), which some tools that read environment variables need.

(nix-develop '("make test") #:flake ".")
Procedure: nix-flake-build KEY: #:flake #:attr #:verbose? #:env #:sudo? #:dev-null? #:allow-failure? #:async?

Build the flake FLAKE, optionally selecting the output ATTR.

(nix-flake-build #:flake "." #:attr "packages.x86_64-linux.maak")
Procedure: nix-flake-check KEY: #:flake #:all-systems? #:verbose? #:env #:sudo? #:dev-null? #:allow-failure? #:async?

Check every output of the flake FLAKE, as ‘nix flake check’ does.

With ALL-SYSTEMS? the check runs for all systems the flake declares rather than just the current one.

Procedure: nix-run cmd-parts KEY: #:flake #:app #:join #:verbose? #:env #:sudo? #:dev-null? #:allow-failure? #:async?

Run the application APP of the flake FLAKE with CMD-PARTS as its arguments.

(nix-run '("--version") #:flake "." #:app "maak")
Procedure: nix-shell cmd-parts KEY: #:file #:pure? #:packages #:join #:verbose? #:env #:sudo? #:dev-null? #:allow-failure? #:async?

Run CMD-PARTS inside a Nix shell.

With FILE the shell is described by that file (typically ‘shell.nix’); without it, Nix looks for ‘shell.nix’ or ‘default.nix’ in the current directory. Each of PACKAGES is added with ‘-p’, and PURE? passes ‘–pure’ so the host environment is hidden.

The command is handed to Nix’s own ‘–run’, so it executes inside the shell rather than after it.

(nix-shell '("python -c 'print(1)'") #:packages '("python3"))
Procedure: object-file source OPT: directory

Return the object file a SOURCE compiles to.

The source’s extension is replaced with ‘.o’ and its directory is kept, or DIRECTORY is used instead. ‘src/a.c’ becomes ‘src/a.o’; with DIRECTORY ‘build’, it becomes ‘build/a.o’. Only the file name is used for DIRECTORY, so two sources with the same base name collide there; give them different directories or different names.

Procedure: package-dependencies

Return the dependencies package.json declares, with the ranges it gives them.

Procedure: package-dev-dependencies

Return the development dependencies package.json declares.

Procedure: package-json OPT: path

Return PATH read as JSON, a string-keyed alist, in file order.

The file is read even in a dry run, like pkg-config: it describes the project rather than changing it, and the version a publish would use is in it.

Procedure: package-manager-kind OPT: manager

Return the package manager MANAGER runs, as one of ‘npm’, ‘pnpm’ or ‘yarn’.

MANAGER is the program, so a wrapper is read from its last word: ‘"corepack pnpm"’ is pnpm. A name this module has no spelling for is a maak error rather than a guess, because the verbs differ and a wrong one would install something the project did not ask for.

Procedure: package-name

Return the name package.json gives the package.

Procedure: package-scripts

Return the names of the scripts package.json defines, in file order.

Procedure: package-version

Return the version package.json gives the package.

Procedure: pipeline-ok? result

Return #t when every stage of the pipeline that produced RESULT succeeded.

RESULT is what ‘run-pipeline’ returns when asked to capture the output, whether or not failures were allowed.

Procedure: pkg-config packages KEY: #:mode #:static?

Run pkg-config for PACKAGES and return its output as a string.

MODE and STATIC? are ‘pkg-config-argv”s. The query runs even in a dry run, because it reads the system: ‘maak –plan’ then shows the flags a compile would really use.

(pkg-config '("gtk+-3.0"))              ;; => "-I... -pthread ..."
(pkg-config '("zlib") #:mode 'libs)     ;; => "-lz"
Procedure: pkg-config-argv packages KEY: #:mode #:static?

Return the argv that asks pkg-config for PACKAGES, without running it.

MODE is ‘cflags’, ‘libs’, ‘modversion’ or ‘exists’. With MODE ‘libs’ and STATIC? the ‘–static’ flag is added, so pkg-config names the libraries a static link needs.

(pkg-config-argv '("gtk+-3.0") #:mode 'cflags)
⇒ ("pkg-config" "--cflags" "gtk+-3.0")
Procedure: pkg-config-cflags packages

Return the compiler flags pkg-config names for PACKAGES, as a list.

(pkg-config-cflags '("gtk+-3.0"))
⇒ ("-I/gnu/store/.../include/gtk-3.0" ...)
Procedure: pkg-config-exists? packages

Return #t when pkg-config knows every one of PACKAGES.

(pkg-config-exists? '("zlib" "openssl"))
Procedure: pkg-config-libs packages KEY: #:static?

Return the linker flags pkg-config names for PACKAGES, as a list.

With STATIC? #t the ‘–static’ answer is used, which names the transitive libraries a static link needs.

Procedure: pkg-config-version package

Return the version pkg-config reports for PACKAGE.

(pkg-config-version "zlib")
⇒ "1.3.1"
Procedure: print-version OPT: port

Print the version banner, and the program’s homepage, to PORT.

Procedure: program-shell cmd-parts KEY: #:verbose? #:pure? #:join #:file #:env #:sudo? #:dev-null? #:allow-failure? #:async?

Execute a command inside a Guix shell defined by a program file.

ARGUMENTS: cmd-parts: A list of strings representing the command to run inside the Guix shell environment.

#:verbose?: If #t, logs the full constructed command before execution. Defaults to #f.

#:join: String used to join command segments. Defaults to a single space. #:file: Path to the Guix program or manifest file defining the shell environment. Defaults to "guix.scm".

Constructs and executes a command of the form:

    guix shell -f FILE -- <cmd ...>

using the ‘$‘ wrapper to safely run the command and check for errors.

RETURNS: #t if the command succeeds.

ERRORS: Signals an error if the underlying shell command exits with a non-zero status.

Procedure: pyproject-data OPT: path

Return PATH read as TOML, a string-keyed alist, in file order.

The file is read even in a dry run, like pkg-config: it describes the project rather than changing it, and a plan that left out the version a publish would use would be a plan of a different release.

Procedure: python . options

Run the Python interpreter, forwarding OPTIONS to ‘python-argv’.

Procedure: python-argv KEY: #:arguments #:module #:isolated?

Return the argv that runs the Python interpreter, without running it.

MODULE runs the module of that name with ‘-m’, which is how a runner that is installed but not on ‘PATH’ is meant to be started. ISOLATED? adds ‘-I’, so the interpreter ignores ‘PYTHONPATH’ and the user’s site directory – what a task wants when it reads a value rather than a local experiment. ARGUMENTS are the words the interpreter or the module is given.

(python-argv #:module "pytest" #:arguments '("-q"))
⇒ ("python3" "-m" "pytest" "-q")
Procedure: python-build-backend OPT: path

Return the build backend of the project, or #f when it names none.

Procedure: python-check

Run the lint, the type check and the tests, in that order.

The order is the cheap failures first: a lint error is a second, a failing test is a minute. Each of the three is its own task as well, so a run that wants one of them names it.

Procedure: python-format . arguments

Format with ruff, over ARGUMENTS or over the whole project.

Procedure: python-lint . arguments

Lint with ruff, over ARGUMENTS or over the whole project.

The default is the project directory, so a check task reads ‘(python-lint)’; the words a caller gives replace it rather than adding to it, because a path and a default path are two answers to the same question.

Procedure: python-module module . arguments

Run MODULE with the interpreter, passing ARGUMENTS.

Procedure: python-output argv KEY: #:allow-failure?

Run the interpreter ARGV and return its standard output as a string.

See ‘uv-output’ for what a query does in a dry run and on failure.

Procedure: python-project OPT: path

Return the ‘[project]’ table of PATH, or raise when there is none.

Procedure: python-project-name OPT: path

Return the name the ‘[project]’ table gives the package.

Procedure: python-project-scripts OPT: path

Return the names of the console scripts the project defines.

Procedure: python-project-version OPT: path

Return the version the ‘[project]’ table gives the package.

A project that lists "version" in ‘dynamic’ has no version in the file: it is computed by the build backend, and this raises rather than guessing at what the backend would answer.

Procedure: python-requires-python OPT: path

Return the interpreter constraint of the project, or #f when it sets none.

Procedure: python-test . arguments

Run the tests with pytest, passing ARGUMENTS to it.

(python-test)
(python-test "-k" "release" "-x")
Procedure: python-type-check . arguments

Type-check with mypy, over ARGUMENTS or over the whole project.

Procedure: python-version

Return the version line the installed interpreter prints, trimmed.

Procedure: raise-maak-error message KEY: #:hint

Raise a ‘&maak-error’ with MESSAGE and an optional HINT.

MESSAGE is the single line the user reads; HINT, when given, is printed underneath as a suggestion for what to do next. Prefer this over ‘error’ in library code so the CLI can keep the report short.

Procedure: read-file file KEY: #:default

Return the contents of FILE as a string.

When the file does not exist, DEFAULT is returned instead of raising; this keeps a task from having to guard every optional file with ‘file-exists?’.

Procedure: remkdir-p dir KEY: #:verbose? #:expand?

Remove a directory if it exists, then recreate it. This results in an empty directory, regardless of its previous state. Calls ‘delete-file-recursively‘ then ‘mkdir-p‘ on DIR.

ARGUMENTS:

  • dir: The path of the directory to recreate.
  • #:verbose? (boolean, default #f): If #t, logs the generated command before executing it.

RETURNS: #t if the operations succeed.

ERRORS: Signals an error if any underlying shell command fails.

Procedure: require-command command KEY: #:hint

Return the path of COMMAND, raising a maak error when it is missing.

Use this at the top of a task that depends on an external program so the user learns about the missing tool in one line instead of from a failing shell command.

(require-command guile #:hint "Install Guile 3.")
Procedure: resolve-maak-tasks KEY: #:module-name

Return the runnable tasks of MODULE-NAME as ‘(NAME . VARIABLE)’ pairs.

When the module declares exports, only those are considered; otherwise every procedure the module defines counts as a task. See the export rules in the Tasks page of the documentation, docs/tasks.org.

Procedure: rm-rf path KEY: #:verbose? #:expand?

Delete PATH recursively, forcefully and verbosely.

A short spelling of delete-file-recursively, for the times a task says rm -rfv build in the shell. It is an alias rather than a second implementation, so it takes the same #:verbose? and #:expand? keywords and behaves the same way.

(rm-rf "build")
(rm-rf "build/*.o" #:expand? #t)
Procedure: run argv KEY: #:verbose? #:env #:sudo? #:dev-null? #:allow-failure? #:async? #:expand?

Run a program and its arguments without a shell.

ARGV is a list of strings: the program to run, followed by one string per argument. Nothing is split or interpolated, so a path with a space in it stays one argument. This is the default way to run a program; ‘$’ is for the lines that genuinely need a shell – pipes, redirections, globs, ‘$(...)’ and ‘VAR=value’ prefixes.

With #:expand? #t the arguments are joined with spaces and handed to the shell, so wildcards, ‘~’ and ‘$VAR’ are expanded the way a shell expands them. That is opt-in because the shell sees words rather than arguments: a path with a space in it becomes several words again, which is exactly what a caller asking for a pattern wants and exactly what the default prevents.

(run (list "mkdir" "-p" build-dir))
(run (list "git" "commit" "-m" message))

;; start a server in the background and wait for it later
(let ((server (run (list "guix" "shell" "--" "run-server")
                   #:async? #t)))
  (log-info "server started as ~a
" (job-pid server))
  (wait-job server))

ARGUMENTS:

  • argv (list): The program and its arguments, each a string.
  • #:verbose? (boolean, default #f): If #t, logs the command before running it.
  • #:env (alist, list of strings, or string, default ’()): Environment variables for this program only, in the shapes ‘$’ accepts.
  • #:sudo? (boolean, default #f): If #t, the program runs through the configured privilege escalation command – doas when it is installed, sudo otherwise, or whatever MAAK_ELEVATE names. See elevation-command.
  • #:dev-null? (boolean, default #f): If #t, standard output and standard error are connected to /dev/null.
  • #:allow-failure? (boolean, default #f): If #t, a non-zero exit code does not raise: #f is returned instead.
  • #:async? (boolean, default #f): If #t, the program is started in the background and a job record is returned.
  • #:expand? (boolean, default #f): If #t, ARGV is joined into one shell line and the shell expands wildcards, ‘~’ and ‘$VAR’ in it. The arguments are then words rather than literals.

RETURNS: #t if the program exits with code 0, #f if it failed and failures were allowed, and a job record when #:async? was given.

ERRORS: Signals a maak error when the program exits non-zero and failures are not allowed.

Procedure: run-compose arguments KEY: #:program #:file #:project #:env-files #:profiles #:allow-failure? #:verbose?

Run Compose with ARGUMENTS, a list of strings.

The escape hatch for subcommands without a wrapper, such as ‘top‘. FILE, PROJECT, ENV-FILES and PROFILES are passed before the subcommand, the way both Compose implementations expect.

Procedure: run-pipeline stages KEY: #:verbose? #:allow-failure? #:env #:async? #:capture?

Run a pipeline of programs without a shell.

STAGES is a non-empty list of stages. A stage is an argument list shaped like the ARGV of ‘run’ – the program first, then one string per argument – or a stage form, which adds the options ‘run’ takes for that stage alone. The standard output of each stage is the standard input of the next, and the whole pipeline is done when every stage has finished.

(run-pipeline (list (list "cat" file)
                    (list "grep" "-v" "^#")
                    (list "sort" "-u")))

;; a stage with an environment and a file of its own, and one that needs root
(run-pipeline (list (stage (list "sort" "-u")
                           #:env '("LC_ALL=C")
                           #:tee "sorted.txt")
                    (stage (list "tee" log) #:sudo? #t)))

;; keep what every stage wrote for the task to look at
(define result (run-pipeline (list (list "git" "diff" "--cached")
                                   (list "grep" "^+"))
                             #:capture? #t
                             #:allow-failure? #t))
(pipeline-outputs result)   ;; one string per stage, in order
(pipeline-ok? result)       ;; #f when a stage failed

Unlike a shell’s ‘|’, which reports the exit status of the last stage alone, a pipeline that fails anywhere reports the stages that failed and raises; pass #:allow-failure? #t to get #f instead and decide in the task. This is the pipefail behaviour, and it is the one that does not let a failing producer hide behind a successful consumer.

A pipeline’s output can be looked at afterwards in two ways. A stage with #:tee keeps a copy of what it wrote in a file the task names, and the stage after it reads the same bytes while it runs: nothing is held back until the pipeline ends. #:capture? #t records every stage the same way, in temporary files, and hands the bytes back in the result instead of printing them; the last stage’s output is then the last entry of pipeline-outputs. Capturing is the way to make a decision from what a pipeline produced – a count of changed files, the list a ‘grep’ matched – without running the pipeline twice.

ARGUMENTS:

  • stages (list): The stages to run, each an argument list or a stage.
  • #:verbose? (boolean, default #f): If #t, logs the pipeline, decorations included, before running it.
  • #:allow-failure? (boolean, default #f): If #t, a failing stage does not raise: #f is returned instead (or the result, when the output was captured), so the task can decide what it means.
  • #:env (alist, list of strings, or string, default ’()): Environment variables for every stage of the pipeline, in the shapes ‘$’ accepts. A stage’s own #:env is added to these, later names winning.
  • #:capture? (boolean, default #f): If #t, every stage’s standard output is recorded and returned in a <pipeline-result>, and the pipeline prints nothing itself. The result’s pipeline-outputs holds one string per stage, in stage order, and pipeline-ok? says whether every stage succeeded. A stage that also has #:tee records into that file, which is left in place.
  • #:async? (boolean, default #f): If #t, the whole pipeline is started in the background and a job record is returned. It is the pipeline that becomes a job, not a stage: a stage cannot finish before the stage after it has read what it wrote. The job’s exit code is 0 when every stage succeeded and 1 otherwise, whatever #:allow-failure? said. An asynchronous pipeline cannot capture its output, because the bytes would be read in the background process; give the stage a #:tee file instead.

RETURNS: #t when every stage exits with code 0, #f when a stage failed and failures were allowed, a <pipeline-result> when #:capture? was given, and a job record when #:async? was given.

ERRORS: Signals a maak error naming the failing stage or stages when a pipeline fails and failures are not allowed, and when #:capture? and #:async? are asked for together.

Procedure: run-task task KEY: #:task-args

Run TASK, a single Maak task, logging its documentation first.

Args: task: a symbol naming the task to run. task-args: the arguments to pass to the task procedure.

Returns the value of the task procedure. Raises a maak error when TASK does not name a runnable task, either because it is missing or because it exists but is not visible as a task (see the export rules in the Tasks page, docs/tasks.org).

Procedure: run-tasks tasks KEY: #:task-args #:keep-going? #:on-failure

Run TASKS sequentially, in the order given.

The tasks run in the order ‘task-order’ settles: a task that declares dependencies with ‘task-metadata!’ runs after them, and a task named twice runs once. Every task must name a procedure the loaded Maak file makes visible; otherwise a maak error lists the tasks that do exist. TASK-ARGS are passed to each task. Returns the names of the tasks that failed, in the order they were run – the empty list when everything succeeded.

With KEEP-GOING? a task that fails stops nothing: the tasks after it still run. ON-FAILURE is then called with the task name and the exception it raised, as ‘(ON-FAILURE TASK KEY VALUE ...)’, so the caller can report the failure where it happened and decide what a run full of them means. Without KEEP-GOING? the first failure is raised as it always was, backtrace and all.

Procedure: run-tasks-parallel tasks KEY: #:task-args #:jobs

Run TASKS concurrently and print their output in the order they were given.

TASKS is a list of symbols; TASK-ARGS are passed to each, as ‘run-tasks’ does. JOBS limits how many run at once: a positive number runs that many, and 0 (the default) starts them all.

Each task runs in a forked worker, so a task sees the Maak file as it was loaded and cannot change the environment of the tasks beside it. A worker’s standard output and standard error, including the output of every command it runs, go to a log of its own; the logs are printed as blocks, in the order ‘task-order’ settled, as soon as the next task in that order has finished. That is what keeps a parallel run readable: no two tasks interleave their lines.

A worker whose task declared dependencies starts only once they have finished, so a run of ‘-j’ still puts a task after the ones it needs; the tasks beside it are unaffected, and a failure does not stop the run – every task that can start does. A task named twice is started once, because ‘task-order’ names it once.

Returns the names of the tasks that failed, in the order they were run. A task that cannot be found, or a dependency that names none, is an error before any worker starts, so a mistyped name cannot leave half a run behind.

Procedure: rustup . arguments

Run rustup with ARGUMENTS.

Procedure: rustup-active-toolchain

Return the toolchain rustup would use here, as its name.

Procedure: rustup-argv . arguments

Return the argv that runs rustup with ARGUMENTS.

Procedure: rustup-component-add component

Add COMPONENT, for example "rustfmt" or "clippy", to the active toolchain.

Procedure: rustup-install toolchain

Install TOOLCHAIN, for example "nightly".

Procedure: rustup-output arguments KEY: #:allow-failure?

Run rustup with ARGUMENTS and return its standard output.

Procedure: rustup-target-add target

Add the compilation TARGET to the active toolchain.

Procedure: rustup-toolchains

Return the names of the installed toolchains.

Procedure: shell-quote str

Return STR quoted so that a shell reads it as one literal word.

The POSIX recipe: wrap the value in single quotes and turn every embedded single quote into the four characters backslash-quote-quote-quote. Unlike ‘~s’, this is safe for spaces, tabs, ‘$’, backticks and newlines.

Procedure: sift subcommand files KEY: #:arguments #:verbose?

Run sift SUBCOMMAND over FILES, raising when it exits non-zero.

This is the short form: ‘(sift "lint" "src")’. Use ‘sift-argv’ for the structured options, and one of the gates below when a finding of status 1 should be a task failure with an explanation rather than a bare non-zero exit.

(sift "explain" '() #:arguments '("SIFT012"))
Procedure: sift-argv subcommand files KEY: #:program #:arguments #:dialect #:style #:brackets #:blank-lines #:line-length #:indent #:comment-align? #:sort? #:write? #:check? #:diff? #:fix? #:stdin? #:stdout? #:label #:severity #:output-format #:checkers #:exclude-checkers #:file-filters #:config #:trust-config? #:watch? #:quiet? #:verbose? #:force? #:no-color?

Return the argv that runs sift SUBCOMMAND over FILES, without running it.

FILES is a string or a list of strings, and a directory means every Lisp file below it, which is sift’s own reading of an operand. ARGUMENTS are appended after the files as they are, so an option this builder does not name still reaches sift.

The combinations sift refuses are refused here as well, before anything runs: ‘–write’ with ‘–stdout’, ‘–sort’ without ‘–write’, and ‘ci’ with ‘–fix’.

(sift-argv "check" "src" #:dialect "scheme" #:style "community")
⇒ ("sift" "check" "--dialect" "scheme" "--style" "community" "src")

(sift-argv "lint" '("src" "tests") #:severity "warning"
           #:output-format "github")
Procedure: sift-check files KEY: #:dialect #:style #:arguments #:verbose?

Ask whether FILES are formatted, failing the task when one is not.

This is ‘sift check’: it prints the patch it would make and exits 1, and that 1 becomes a maak error here, so a task named ‘check’ fails the pipeline without a shell ‘|| exit 1’ to remember.

Procedure: sift-ci files KEY: #:dialect #:style #:severity #:output-format #:arguments #:verbose?

Ask the formatting question and the lint question in one pass.

This is the pipeline’s command: ‘sift ci’ writes nothing, reports both kinds of finding, and exits 1 if either answers badly. OUTPUT-FORMAT ‘github’ turns each finding into a workflow annotation, and ‘sarif’ writes one document for a code-scanning service.

Procedure: sift-exit-meaning code

Return what sift’s exit CODE means: ‘clean’, ‘findings’ or ‘error’.

Zero is ‘clean’. One is ‘findings’, which is what the tree answered badly. Anything else is ‘error’, which for sift is a usage error, an unreadable file or a file that cannot be parsed. The decision lives in one place so a gate, a caller reading a status and this module’s test all agree on it.

Procedure: sift-files directory KEY: #:extensions #:exclude

Return the Lisp files under DIRECTORY, sorted, skipping EXCLUDE directories.

sift walks a directory operand itself, so this is for the list a task means rather than a different walk: a project whose fixtures are deliberately unformatted passes ‘#:exclude ’("fixtures")’, which is the ‘find ... -not -path’ the Maak files spell out today, and a project with a second dialect in a corner passes ‘#:extensions’.

EXCLUDE names directories to prune at any depth; the directories that never hold source (‘node_modules‘, ‘.git‘ and the like) are pruned already, by the same walk and the same list ‘(maak watch)’ uses.

(sift-ci (sift-files "src"))
(sift-check (append (sift-files "src")
                    (sift-files "tests" #:exclude '("fixtures"))))
Procedure: sift-format files KEY: #:write? #:check? #:diff? #:style #:dialect #:arguments #:verbose?

Format FILES, rewriting them with WRITE? and printing them otherwise.

This does not fail on a reformatted file, because reformatting is the job. With CHECK? nothing is written and a file that would change is a failure, and with DIFF? the patch is printed instead: the two shapes a CI job wants, and neither of them touches the tree.

Procedure: sift-lint files KEY: #:severity #:output-format #:arguments #:verbose?

Lint FILES, failing the task when a rule at SEVERITY or above fires.

SEVERITY is ‘error’, ‘warning’ or ‘info’ – the smallest one to report, ‘info’ unless given. OUTPUT-FORMAT is ‘human’, ‘json’, ‘null’, ‘github’ or ‘sarif’, and it changes what is printed rather than what is found.

Procedure: sift-status argv KEY: #:verbose?

Run the sift ARGV and return its exit status: 0, 1 or 2.

sift’s output goes to the terminal as it is written, because the findings are the answer and capturing them would leave the user with a status to look up. A dry run runs nothing and answers 0 after recording the command in the plan, which is what keeps a gate safe to try before it is trusted.

Procedure: split-load-path str

Split a ‘PATH’-style colon separated STR into a list of directories.

An empty entry is dropped, so a trailing or doubled colon does not add the current directory twice.

Procedure: stage argv KEY: #:env #:sudo? #:tee

Describe one stage of a pipeline, with the options ‘run’ takes.

ARGV is a program and its arguments, in the shape ‘run’ takes them. ENV sets names for this stage alone, in the shapes ‘$’ accepts; they are added to the pipeline’s own environment, later names winning. With SUDO? the stage runs through the configured privilege escalation command (see ‘elevation-command’). TEE names a file that the stage’s standard output is also written to, the way ‘tee’ does it: the stage after this one reads the same bytes, and the file keeps them for the task to look at once the pipeline is done.

(run-pipeline (list (stage (list "grep" "-v" "^#")
                           #:env '("LC_ALL=C")
                           #:tee "clean.txt")
                    (stage (list "sort" "-u"))))

A stage is a description only; ‘run-pipeline’ starts it.

Procedure: static-library output objects KEY: #:archiver #:verbose?

Write OBJECTS into the static library OUTPUT.

(static-library "build/libfoo.a" (map (lambda (source) (object-file source "build"))
                                       '("src/a.c" "src/b.c")))
Procedure: static-library-argv output objects KEY: #:archiver

Return the argv that writes OBJECTS into a static library OUTPUT.

The archiver is ‘ar rcs’, which creates the archive, inserts the objects and writes the index; ARCHIVER overrides the ‘ar-command’ parameter.

(static-library-argv "build/libfoo.a" '("build/a.o" "build/b.o"))
Procedure: string-lines str

Split STR on newlines into a list of lines.

Procedure: syscall cmd KEY: #:allow-failure? #:async?

Executes a shell command and checks its exit code.

ARGUMENTS:

  • cmd (string): The shell command to be executed.
  • #:allow-failure? (boolean, default #f): If #t, a non-zero exit code or a signal does not raise: it comes back as #f, the way ‘cmd || true’ would keep a shell going, except that the task also learns that the command failed.
  • #:async? (boolean, default #f): If #t, the command is started in the background and a job record is returned instead of a boolean. The command still runs through a shell, so pipes and redirections keep working, but the fork is maak’s: ‘job-pid’, ‘job-done?’, ‘wait-job’ and ‘job-exit-code’ can read the process.

RETURNS: #t if the command completes with an exit code of 0, #f if it failed and failures are allowed, and a job record when #:async? was given.

ERRORS: Signals an error if the command returns a non-zero exit code or is terminated by a signal. The message names the command, and the exit code when there is one.

Procedure: tar-compression-option compression

Return the tar flags that select COMPRESSION, as a list.

The names accepted are the ones a release actually uses: none, gz, bz2, xz and zstd. gzip, bzip2 and zst are accepted as aliases, so a caller can spell the compressor rather than its extension. A name that is not one of these raises a maak error instead of producing an archive tar would refuse to read.

Procedure: tar-create output files KEY: #:directory #:compression #:exclude #:verbose? #:allow-failure?

Write FILES as the tarball OUTPUT.

FILES is a list of paths relative to DIRECTORY, which defaults to the current directory. The compressor follows the output’s extension unless COMPRESSION names one, and EXCLUDE is a list of patterns to leave out.

OUTPUT is written in the directory the task started in, not in DIRECTORY, so packing the current directory does not put the growing tarball into the tree tar is reading. Passing an absolute OUTPUT that points inside the packed tree does, and tar then fails with "file changed as we read it".

(tar-create "maak-1.0.tar.gz" (list "src" "README.org" "LICENSE")
            #:exclude (list "*.o" "*.go"))
(tar-create "maak-1.0.tar.xz" (list ".") #:compression "xz")
Procedure: tar-create-argv output files KEY: #:directory #:compression #:exclude #:verbose?

Return the argv that writes FILES as the tarball OUTPUT.

FILES is a list of paths relative to DIRECTORY. With COMPRESSION auto, the output’s extension names the compressor (see tar-infer-compression); any other value is passed to tar-compression-option. EXCLUDE is a list of patterns, each passed as --exclude=PATTERN. With VERBOSE? the argv includes -v, so tar prints every file it adds.

Procedure: tar-extract archive KEY: #:directory #:strip-components #:verbose? #:allow-failure?

Unpack ARCHIVE, into DIRECTORY when one is named.

STRIP-COMPONENTS drops leading path components as the files are written; use 1 for the usual release tarball that wraps everything in one directory.

(tar-extract "maak-1.0.tar.gz" #:directory "build" #:strip-components 1)
Procedure: tar-extract-argv archive KEY: #:directory #:strip-components #:verbose?

Return the argv that unpacks ARCHIVE.

The compressor is detected from the archive itself, which is why no compression flag is needed here. DIRECTORY is where the files are written, and STRIP-COMPONENTS drops that many leading path components, which is how a release tarball with a single top-level directory is unpacked into the current one.

(tar-extract-argv "project-1.0.tar.gz" #:directory "build" #:strip-components 1)
Procedure: tar-list archive KEY: #:verbose? #:allow-failure?

Print the names of the files in ARCHIVE, without unpacking it.

With VERBOSE? tar prints the long listing instead of bare names.

Procedure: tar-list-argv archive KEY: #:verbose?

Return the argv that prints the names of the files in ARCHIVE.

Procedure: task-depends task

Return the names of the tasks TASK needs to have finished first, in order.

Procedure: task-error message KEY: #:hint #:args

Raise a user-facing error from a task.

This is what a task calls when it cannot do its job: the message is printed as one line, the hint (when given) underneath it, and no Guile backtrace follows. ARGS, when given, are handed to ‘format’ to build the message, so a task can report the value that made it give up.

(task-error "no compiled artefact for ~a" #:args (list host))
(task-error "the deploy key is missing"
            #:hint "Set DEPLOY_KEY, or run maak deploy --dry-run.")
Procedure: task-example task

Return the invocation TASK holds up as an example, or the empty string.

Procedure: task-hidden? task

Return #t when TASK asks the listings to leave it out.

Procedure: task-meta task

Return what TASK declares about itself, or #f when it declares nothing.

Procedure: task-metadata! task KEY: #:depends #:hidden? #:example

Record what TASK declares about itself.

TASK is the procedure the task is defined as, so this call goes after the definition, where the name is bound:

(define (deploy) "Ship it." (run (list "rsync" ...)))
(task-metadata! deploy
                #:depends '(build test)
                #:example "maak deploy prod.example.com")

DEPENDS names the tasks that must have finished before this one starts, as a list of symbols or strings; a dependency says *when* a task may run, never whether it does, because maak has no notion of up to date. HIDDEN? keeps the task out of the listings – the human one and the machine-readable one an editor reads – while still letting it be run by name and needed by another task. EXAMPLE is an invocation to show a reader, prose rather than a value.

The call returns TASK, so a file may write it inline. A declaration that cannot be honoured – a dependency that is not a name, an example that is not a string, metadata for something that is not a task – is a maak error where it is written, rather than a task that runs in the wrong order later.

Procedure: task-order tasks KEY: #:known

Return TASKS as the list to run, with each task’s dependencies before it.

A task named twice appears once, and a dependency that two tasks share runs once before the first of them. The order the tasks were given is kept otherwise, so a run of several tasks still reads in the order it was written.

KNOWN is the ‘(NAME . VARIABLE)’ alist the order is resolved against, ‘resolve-maak-tasks’ by default. A dependency that names no task of the file, and a dependency cycle, are maak errors: both leave a run that cannot honour what the file says, and a silently shortened run is the kind of thing that only shows up as a deploy that shipped half.

Procedure: tasks-table tasks KEY: #:width #:long? #:file

Return TASKS as the aligned listing ‘maak –list’ prints.

TASKS is the ‘(NAME . VARIABLE)’ alist ‘resolve-maak-tasks’ returns, so the listing is read from the loaded file: its docstrings, what each task declares and whether it asked to be left out. WIDTH is the widest line the table may produce, and FILE, when given, is named in the heading.

Procedure: time-machine cmd-parts KEY: #:verbose? #:join #:channels #:env #:sudo? #:dev-null? #:allow-failure? #:async?

Execute a command using a pinned Guix revision via ‘guix time-machine‘.

ARGUMENTS: cmd-parts: A list of strings representing the command to run after the ‘guix time-machine‘ invocation.

#:verbose?: If #t, logs the final constructed command before running it. Defaults to #f. #:join: The string used to join command segments when constructing the final command. Defaults to a single space. #:channels: Path to the channels file used to pin the Guix revision. Defaults to "channels.scm".

Constructs and executes a command of the form:

    guix time-machine --channels=CHANNELS -- <cmd ...>

using the ‘$‘ wrapper to run the resulting shell command safely.

RETURNS: #t if the command succeeds.

ERRORS: Signals an error if the underlying command exits with a non-zero status.

Procedure: time-machine-manifest-shell cmd-parts KEY: #:verbose? #:pure? #:join #:channels #:manifest #:env #:sudo? #:dev-null? #:allow-failure? #:async?

Execute a command inside a Guix shell defined by a manifest file, using a pinned Guix revision via ‘guix time-machine‘.

ARGUMENTS: cmd-parts: A list of strings representing the command to run inside the pinned Guix shell environment.

#:verbose?: If #t, logs the composed command before execution. Defaults to #f. #:pure?: If #t, it will run in a pure isolated shell (clean). Defaults to #f. join: String used to join command segments. Defaults to a single space. #:channels: Path to the channels file used to pin the Guix revision. Defaults to "channels.scm". #:manifest: Path to the manifest file describing the package environment. Defaults to "manifest.scm".

Constructs and executes a command of the form:

    guix time-machine --channels=CHANNELS -- shell -m MANIFEST -- <cmd ...>

This provides a reproducible shell environment defined by the manifest file and pinned to the Guix revision specified in the channels file.

RETURNS: #t if the command succeeds.

ERRORS: Signals an error if any underlying shell command exits with a non-zero status.

Procedure: time-machine-program-shell cmd-parts KEY: #:verbose? #:pure? #:join #:channels #:file #:env #:sudo? #:dev-null? #:allow-failure? #:async?

Execute a command inside a Guix shell defined by a program file, using a pinned Guix revision via ‘guix time-machine‘.

ARGUMENTS: cmd-parts: A list of strings representing the command to run inside the pinned Guix shell environment.

#:verbose?: If #t, logs the composed command before execution. Defaults to #f. #:pure?: If #t, it will run in a pure isolated shell (clean). Defaults to #f. #:join: String used to join command segments. Defaults to a single space. #:channels: Path to the channels file used to pin the Guix revision. Defaults to "channels.scm". #:file: Path to the Guix program file (e.g. guix.scm) defining the environment. Defaults to "guix.scm".

Constructs and executes a command of the form:

    guix time-machine --channels=CHANNELS -- shell -f FILE -- <cmd ...>

This provides a reproducible development environment defined by the program file and pinned to the Guix revision specified in the channels file.

RETURNS: #t if the command succeeds.

ERRORS: Signals an error if any underlying shell command exits with a non-zero status.

Procedure: tmp-dir

Return the directory for temporary files, honouring ‘TMPDIR’.

Procedure: touch file KEY: #:verbose? #:expand?

Create FILE if it does not exist, or update its timestamp.

With EXPAND? #t the shell expands FILE, so a wildcard touches every name it matches; see ‘run’ for what the opt-in does to the other helpers.

Procedure: unknown-task-error task

Raise a maak error saying TASK is not runnable, listing the tasks that are.

Procedure: unlines lines

Join LINES with newlines, adding no trailing newline.

Procedure: unwords words

Join WORDS with single spaces.

Procedure: up-to-date? output inputs

Return #t when OUTPUT exists and is not older than any of INPUTS.

A missing output or a missing input is not up to date. This is the explicit check a task uses to skip a compile; maak never applies it on its own, because a dependency that decides whether a task runs is the thing maak was written to leave to the task.

(unless (up-to-date? "build/a.o" '("src/a.c" "include/a.h"))
  (compile "src/a.c" #:output "build/a.o"))
Procedure: uv subcommand . options

Run uv SUBCOMMAND, forwarding OPTIONS to ‘uv-argv’.

(uv "run" #:arguments '("pytest" "-q"))
Procedure: uv-add . arguments

Add a dependency to the project, passing ARGUMENTS.

Procedure: uv-argv subcommand KEY: #:arguments #:project #:directory #:cache-dir #:offline? #:no-cache? #:no-progress? #:refresh? #:verbose #:quiet? #:color #:frozen? #:locked? #:no-sync? #:env-file #:python

Return the argv that runs uv SUBCOMMAND, without running it.

The options uv documents for the program as a whole – PROJECT, DIRECTORY, CACHE-DIR, OFFLINE?, NO-CACHE?, NO-PROGRESS?, REFRESH?, the verbosity and COLOR – come before SUBCOMMAND. The ones uv documents for the commands that read the project – FROZEN?, LOCKED?, NO-SYNC?, ENV-FILE and PYTHON – come after it, which is where uv accepts them. ARGUMENTS are appended as they are, so an option this builder does not name, or the words ‘uv run’ passes to the program, still reach uv.

VERBOSE is #t for one ‘-v’ or a positive number for that many.

(uv-argv "sync" #:frozen? #t #:python "3.12")
⇒ ("uv" "sync" "--frozen" "--python" "3.12")

(uv-argv "run" #:arguments '("pytest" "-q"))
⇒ ("uv" "run" "pytest" "-q")
Procedure: uv-build . arguments

Build the source and wheel distributions into ‘dist/’, passing ARGUMENTS.

Procedure: uv-export . arguments

Export the lock file to another format, passing ARGUMENTS.

Procedure: uv-init . arguments

Create a new project with ‘uv init’, passing ARGUMENTS.

Procedure: uv-lock . arguments

Update the lock file, passing ARGUMENTS.

Procedure: uv-output argv KEY: #:allow-failure?

Run the uv ARGV and return its standard output as a string.

A query runs even in a dry run: it reads the project rather than changing it. A failure raises a maak error naming the command, or comes back as #f when the caller asked for the exit status instead.

Procedure: uv-pip . arguments

Run a ‘uv pip’ command, passing ARGUMENTS.

Procedure: uv-publish . arguments

Publish the built distributions, passing ARGUMENTS.

A dry run of the release is ‘(uv-publish "–dry-run")’: uv’s own flag is what makes it one, while maak’s dry run prints the command instead.

Procedure: uv-python . arguments

Manage the interpreters uv installs, passing ARGUMENTS.

Procedure: uv-remove . arguments

Remove a dependency from the project, passing ARGUMENTS.

Procedure: uv-run . arguments

Run a command in the project’s environment, passing ARGUMENTS.

The words after ‘uv run’ are the program and its own arguments, so ‘(uv-run "pytest" "-q")’ runs pytest quietly.

(uv-run "pytest" "-k" "release")
(uv-run "python" "-c" "import example; print(example.__version__)")
Procedure: uv-sync . arguments

Synchronise the environment with the lock file, passing ARGUMENTS.

Procedure: uv-tree . arguments

Print the dependency tree, passing ARGUMENTS.

Procedure: uv-venv . arguments

Create the virtual environment, passing ARGUMENTS.

Procedure: uv-version

Return the version line the installed uv prints, trimmed.

Procedure: uvx . arguments

Run a tool installed in a temporary environment, as ‘uvx ruff’ does.

Procedure: uvx-argv . arguments

Return the argv that runs uvx with ARGUMENTS.

Procedure: veritas-env KEY: #:module #:top-dir #:type #:benchmarks?

Return the VERITAS_* assignments the runner reads, as NAME=VALUE strings.

The suite is located by MODULE, the module the runner loads, TOP-DIR, where the specs live, and TYPE, which directory under TOP-DIR. BENCHMARKS? turns the benchmark run on. They are strings because ‘run’ hands its ‘#:env’ straight to ‘env’, so a value with a space in it stays one value.

(veritas-env)
⇒ ("VERITAS_TEST_MODULE=veritas" "VERITAS_TEST_TOP_DIR=test" ...)
Procedure: veritas-shell-command KEY: #:guile #:load-paths #:expression

Return the same words with EXPRESSION quoted for a shell.

‘manifest-shell’ and ‘time-machine-manifest-shell’ join their words into one command line, so the expression, which has spaces and parentheses, has to survive as one word. Use ‘veritas-test-argv’ with ‘run’, which starts guile without a shell and needs no quoting.

Procedure: veritas-test KEY: #:verbose? #:guile #:load-paths #:module #:top-dir #:type #:benchmarks? #:expression

Run the Veritas suite and fail the task when it does not pass.

This is the one line a Maak file needs for its test task:

(define (test)
  (veritas-test))

The status the runner answers with is the exit status guile leaves, so a red suite is a failed task with no shell fallback to remember.

Procedure: veritas-test-argv KEY: #:guile #:load-paths #:expression

Return the argv that runs the Veritas suite, without running it.

LOAD-PATHS are the directories guile searches before anything installed, which is what makes the checkout’s own library and specs the ones under test. GUILE names the interpreter, so a task can pin one.

The expression is one argv element, unquoted: this list is what ‘run’ starts directly. For the words a manifest shell re-reads, use ‘veritas-shell-command’, which is this list with the expression quoted.

(veritas-test-argv)
⇒ ("guile" "-L" "./src" "-L" "./test" "-c" veritas-expression)
Procedure: wait-job job

Wait for JOB to finish and return #t when it exited with code 0.

Returns #f for a non-zero exit or a signal. Waiting twice is fine: the status is remembered after the first wait.

Procedure: watch-changed? before after

Return #t when the two snapshots describe a different tree.

Procedure: watch-files root

Return the files a watch of ROOT follows, as absolute paths.

A git checkout is read with ‘git ls-files’; anything else is walked. A git command that fails – a repository whose index is locked, say – falls back to the walk rather than watching nothing.

Procedure: watch-interval

Return the watch interval in seconds.

‘MAAK_WATCH_INTERVAL’ sets it; the default is one second. A value that is not a positive number is a maak error rather than a silent fallback, so a typo does not turn into a watch that never notices anything.

Procedure: watch-relist KEY: #:root #:program #:arguments #:interval

Re-run a task listing now, and again whenever ROOT changes.

This is the ‘dev’ and ‘hot-reload’ task that most Maak files spell out by hand: a watch whose action is a listing, where a broken edit is reported and the watch carries on, because the next save is how it gets fixed. PROGRAM is the maak to run – a checkout’s launcher by default – and ARGUMENTS are its words, ‘–list’ unless the task wants something else.

(define (dev)
  "Watch the tree and re-list the tasks on every change."
  (watch-relist))

(define (test-watch)
  "Re-run the suite on every change, instead of re-listing."
  (watch-relist #:arguments '(("test"))))
Procedure: watch-snapshot files

Return FILES as a sorted list of ‘(PATH MTIME . SIZE)’, for comparison.

A file that disappeared between the listing and the stat is left out: it is a change, and the next snapshot will not mention it either.

Procedure: watch-tree root thunk KEY: #:interval

Run THUNK now, then again whenever the tree under ROOT changes.

INTERVAL is how often the tree is looked at, in seconds. The run happens immediately, so ‘–watch’ starts with the same run the same command would do without it; the snapshot is taken after the run, so what the task itself wrote is the baseline rather than a change. THUNK is expected to report its own failures: the watch has nowhere to return a status to, and a failing run must not stop it.

Procedure: wget arguments KEY: #:allow-failure? #:verbose?

Run wget with ARGUMENTS, a list of strings; see ‘wget-argv’.

Procedure: wget-argv arguments

Return the argv that runs wget with ARGUMENTS.

The escape hatch for a flag no helper models; nothing is handed to a shell, so an argument with a space in it stays one argument.

Procedure: wget-download url KEY: #:output #:directory #:continue? #:quiet? #:timestamping? #:no-clobber? #:headers #:user #:password #:timeout #:tries #:user-agent #:extra #:allow-failure? #:verbose?

Download URL with wget; see ‘wget-download-argv’.

Procedure: wget-download-argv url KEY: #:output #:directory #:continue? #:quiet? #:timestamping? #:no-clobber? #:headers #:user #:password #:timeout #:tries #:user-agent #:extra

Return the argv that downloads URL with wget.

OUTPUT names the file, DIRECTORY is the prefix the file is written under, and CONTINUE? resumes a partial file. QUIET? silences the progress output; TIMESTAMPING? and NO-CLOBBER? decide what to do with an existing file.

Procedure: wget-mirror url KEY: #:directory #:no-parent? #:page-requisites? #:convert-links? #:cut-dirs #:no-host-directories? #:quiet? #:headers #:user-agent #:timeout #:tries #:extra #:allow-failure? #:verbose?

Mirror the site at URL with wget; see ‘wget-mirror-argv’.

Procedure: wget-mirror-argv url KEY: #:directory #:no-parent? #:page-requisites? #:convert-links? #:cut-dirs #:no-host-directories? #:quiet? #:headers #:user-agent #:timeout #:tries #:extra

Return the argv that mirrors the site at URL with wget.

The defaults are the ones a documentation snapshot wants: recursion that stays under URL, no host directory at the top, and a DIRECTORY prefix when one is named. PAGE-REQUISITES? also fetches the images and stylesheets, CONVERT-LINKS? rewrites the saved pages to point at them, and CUT-DIRS drops leading path components from the local tree.

Procedure: wget-output arguments KEY: #:allow-failure?

Run wget with ARGUMENTS and return what it printed.

In dry-run mode nothing runs, the command is printed, and the empty string comes back.

Procedure: wget-text url KEY: #:headers #:user #:password #:user-agent #:timeout #:tries #:extra #:allow-failure?

Fetch URL with wget and return the body as a string.

wget writes the body to standard output with –output-document=-, which is what lets a task read it instead of finding a file afterwards. The progress output is silenced so the result is only the body.

Procedure: wget-text-argv url KEY: #:headers #:user #:password #:user-agent #:timeout #:tries #:extra

Return the argv that fetches URL’s body for a task to read.

Procedure: which command

Return the absolute path of COMMAND on ‘PATH’, or #f when it is missing.

(which guile)
⇒ /gnu/store/.../bin/guile
Procedure: with-directory dir thunk

Call THUNK with the process working directory changed to DIR.

The previous directory is restored even when THUNK raises.

(with-directory build-dir (lambda () (syscall make-command)))
Procedure: with-env name value thunk

Call THUNK with environment variable NAME set to VALUE.

The previous value, if any, is restored afterwards.

Procedure: with-env-vars variables thunk

Call THUNK with every NAME and VALUE pair of VARIABLES set.

(with-env-vars configured-variables (lambda () (syscall make-command)))
Procedure: with-load-path dirs thunk

Call THUNK with DIRS added to the load path, restoring it afterwards.

DIRS is a list of directory names. The load path is saved and restored even when THUNK raises, so a failing task does not leave the process with a polluted search path.

(with-load-path '("./lib" "./src")
  (lambda () (use-modules (my project))))
Procedure: write-file file content KEY: #:append? #:mkdir-parents?

Write CONTENT to FILE, creating its directory first when needed.

With APPEND? #t the content is added to the end of FILE rather than replacing it.

Procedure: zip-create output files KEY: #:directory #:recursive? #:exclude #:junk-paths? #:quiet? #:verbose? #:allow-failure?

Write FILES as the zip archive OUTPUT.

FILES is a list of paths relative to DIRECTORY, which defaults to the current directory. The archive itself is written relative to the directory the task started in, so a ‘#:directory "dist"’ does not leave the zip inside dist.

(zip-create "maak-1.0.zip" (list "src" "README.org")
            #:exclude (list "*.go" "*.o"))
Procedure: zip-create-argv output files KEY: #:recursive? #:exclude #:junk-paths? #:quiet? #:verbose?

Return the argv that writes FILES as the zip archive OUTPUT.

The archive is created in the current directory; zip-create is the one that changes into #:directory for the duration of the command, because Info-ZIP has no -C-style option to name a tree. EXCLUDE is a list of patterns passed as -x, after the files, which is where zip expects them. #:junk-paths? stores bare file names rather than the paths they were found under.

Procedure: zip-extract archive KEY: #:directory #:overwrite? #:quiet? #:allow-failure?

Unpack ARCHIVE, into DIRECTORY when one is named.

With OVERWRITE? (the default) existing files are replaced without a prompt; with it #f they are kept and unzip skips them.

Procedure: zip-extract-argv archive KEY: #:directory #:overwrite? #:quiet?

Return the argv that unpacks ARCHIVE.

OVERWRITE? is unzip’s -o: files already there are replaced rather than asked about, which is what an unattended task needs. DIRECTORY is where the files are written.

Procedure: zip-list archive KEY: #:quiet? #:allow-failure?

Print a listing of the files in ARCHIVE, without unpacking it.

Procedure: zip-list-argv archive KEY: #:quiet?

Return the argv that lists the contents of ARCHIVE.

Procedure: ~ . args

A utility function to format a string (interpolation). Alias for (apply format #f ARGS).

(~ "Hello world, my name is ~a and I am ~a years old"
    "Joe"
    30)

ARGUMENTS:

  • args (list): A list of arguments where the first element is the format string and the subsequent elements are the values to be substituted.

RETURNS: A newly allocated string resulting from the formatting operation.

1.16.5 Record Types

Record type: &maak-error

This record type has the following fields:

  • message
  • hint

1.16.6 Variables

Variable: maak-homepage
"https://github.com/jjba23/maak"
Variable: maak-license
"MIT"
Variable: maak-version
"1.1.2"
Variable: veritas-expression
"(exit ((@@ (veritas runner) run-tests)))"

1.17 (maak main)

The command line entry point.

Two things matter here beyond parsing the options. First, a user-facing failure must read as one line, not as a Guile backtrace: every error maak raises itself is a ‘&maak-error’ (see ‘(maak dsl)’), and this module prints those as a short message with a hint. Second, the load path is assembled from several sources – the ‘-L’ flag, ‘MAAK_LOAD_PATH’, and the directory of the maak file itself – so a project can require its own modules without exporting GUILE_LOAD_PATH by hand.

1.17.1 Overview

1.17.2 Procedures

Procedure: describe-tasks file

Return the tasks FILE defines, as the description an editor reads.

FILE is read as well as loaded: see the note above for which reader answers what. A task file in JSON, TOML or YAML describes its tasks itself, because there is no lambda list to read out of a loaded procedure.

Procedure: error-message-string key vals

Return the most descriptive string Guile attached to a caught error.

The shape of the arguments depends on who raised the error. A call to ‘error’ arrives as (#f MESSAGE () #f), where the message is the second element, while a primitive failure such as ‘(car 1)’ arrives as (#f MESSAGE (1) (1)) whose *first* string is only the name of the procedure – reporting that as the message would hide the one sentence the user needs. The second element is the message in both shapes, so it is preferred, and the remaining values are searched only when it is not a string, as when ‘throw’ is handed a key and a message but no irritants.

Procedure: exception->message key vals

Return a one-line human message for a caught error.

It prefers an attached exception message, then the message among the raising values, and only then falls back to the raw key. Guile raises many errors with a format *template* (for example ‘no code for module ~S’) plus the arguments; those are filled in here so the user never sees a bare ‘~S’.

Procedure: main KEY: #:args

Entry point for the maak command line interface.

Parse ARGS and either print help or the version, list the tasks, or run the requested tasks. Returns the process exit status: 0 on success, 1 when the maak file or a task failed. User-facing errors print as one line; set ‘MAAK_DEBUG’ (or pass –debug) to see the Guile backtrace instead.

Procedure: report-generic-error key vals

Print an unexpected error.

An unexpected failure is a bug in maak, or a genuine error in the maak file, rather than something maak can explain, so the message says so and points at the way to get the backtrace – and, when it is a missing module, at the way to put it on the load path.

Procedure: report-maak-error error

Print a ‘&maak-error’ ERROR as a short, red, backtrace-free message.

Procedure: resolve-banner? options

Return whether the greeting banner should be printed for OPTIONS.

The ‘–no-banner’ flag wins over ‘–banner’, which wins over the environment: an explicit ‘–banner’ is how a reader of a script asks for the banner back after ‘MAAK_NO_BANNER’ was exported for the shell as a whole.

Procedure: resolve-env-files options file

Return the environment files to read for OPTIONS and maak file FILE.

‘–env-file’ names them explicitly and, when given, is the only source; otherwise ‘MAAK_ENV_FILE’ is read, and failing that a ‘.env’ beside the maak file. ‘–no-env-file’ turns the whole mechanism off, which is what a reproducible run wants – the same command, no matter what a checkout happens to contain.

Procedure: resolve-list-width options

Return the width ‘–list-width’ gives, or #f when nothing is folded.

Procedure: resolve-listing-style options

Return the layout ‘–list’ asks for, as a symbol.

‘–list’ on its own is the aligned table; ‘–list=STYLE’ names one of ‘listing-styles’. A layout maak does not know is refused here rather than printed as something the reader did not ask for.

Procedure: resolve-maak-file file

Return the absolute path of the maak file to load, or raise a maak error.

FILE defaults to ‘maak-default-file’ when the command line did not name one, and a checkout with no ‘maak.scm’ may hold one of the task files in JSON, TOML or YAML instead. The path is canonicalised because ‘load’ resolves a relative name against the directory of the module that calls it – from this module, ‘./maak.scm’ would be searched for as ‘maak/maak.scm’ and could load a completely different file.

Procedure: resolve-print-directory? options

Return whether the directories ‘-C/–directory’ enters should be reported.

A run that changes directory says where it ended up, because a task that ran somewhere else is the kind of thing that is worth knowing without asking. The report is what make’s ‘-w’ prints, and ‘–no-print-directory’ is the switch of make’s that turns it off – useful when the output of a run is read by something other than a person. ‘–quiet’ asks for the same silence, among other things, and so does not bring the lines back.

Procedure: truthy-string? str

Return #t when STR is set to something other than 0, false or no.

A switch that lives in the environment has to be given a value, and every convention for ‘off’ is accepted rather than only the empty string.

1.17.3 Variables

Variable: listing-styles
(table plain long names json)
Variable: maak-default-file
"./maak.scm"
Variable: maak-option-spec
((file (single-char #\f) (value #t) (required? #f)) (resources (single-char #\r) (value #t) (required? #f)) (list (single-char #\l) (value optional) (required? #f)) (list-width (value #t) (required? #f)) (json (value #f) (required? #f)) (plan (value #f) (required? #f)) (watch (value #f) (required? #f)) (explain (value #f) (required? #f)) (dry-run (single-char #\n) (value #f) (required? #f)) (quiet (single-char #\q) (value #f) (required? #f)) (tasks (single-char #\t) (value #t) (required? #f)) (directory (single-char #\C) (value #t) (required? #f)) (keep-going (single-char #\k) (value #f) (required? #f)) (ignore-errors (single-char #\i) (value #f) (required? #f)) (jobs (single-char #\j) (value #t) (required? #f)) (no-print-directory (value #f) (required? #f)) (load-path (single-char #\L) (value #t) (required? #f)) (env-file (single-char #\e) (value #t) (required? #f)) (no-env-file (value #f) (required? #f)) (banner (value #f) (required? #f)) (no-banner (value #f) (required? #f)) (version (single-char #\v) (value #f) (required? #f)) (debug (value #f) (required? #f)) (help (single-char #\h) (value #f) (required? #f)))

1.18 (maak maven)

Maven helpers: the lifecycle a Java project runs, as argv a task can inspect.

There is no build engine here. ‘maven-argv’ is a pure builder and ‘maven’ feeds its list to ‘run’, so ‘–dry-run’ prints the invocation and ‘–plan’ records it. An option this builder does not name travels as an argument, which is how a plugin goal maak has never heard of is still a Maven goal.

The program is a parameter, honoured from MAAK_MAVEN then MAVEN, and a value may carry flags the way a shell would read them. ‘maven-wrapper-command’ answers with ‘./mvnw’ when a checkout has one, which is the version of Maven the project itself pins; a task opts in with ‘(parameterize ((maven-command (maven-wrapper-command))) ...)’.

1.18.1 Overview

  • maven-command — A parameter object.
  • maven — Run the Maven GOALS, forwarding OPTIONS to ‘maven-argv’.
  • maven-argv — Return the argv that runs the Maven GOALS, without running it.
  • maven-clean — Remove the build output with ‘mvn clean’, passing ARGUMENTS.
  • maven-compile — Compile the sources with ‘mvn compile’, passing ARGUMENTS.
  • maven-dependency-tree — Print the dependency tree with ‘mvn dependency:tree’, passing ARGUMENTS.
  • maven-deploy — Deploy the artefact with ‘mvn deploy’, passing ARGUMENTS.
  • maven-effective-pom — Print the effective POM with ‘mvn help:effective-pom’, passing ARGUMENTS.
  • maven-install — Install the artefact into the local repository, passing ARGUMENTS.
  • maven-output — Run the Maven ARGV and return its standard output.
  • maven-package — Package the artefact with ‘mvn package’, passing ARGUMENTS.
  • maven-site — Build the project site with ‘mvn site’, passing ARGUMENTS.
  • maven-test — Run the tests with ‘mvn test’, passing ARGUMENTS.
  • maven-validate — Validate the project with ‘mvn validate’, passing ARGUMENTS.
  • maven-verify — Run the verification phase with ‘mvn verify’, passing ARGUMENTS.
  • maven-wrapper-command — Return the Maven command to use in DIRECTORY.
  • maven-wrapper? — Return #t when DIRECTORY holds an executable Maven wrapper.

1.18.2 Parameters

Parameter: maven-command

Default value:

"mvn"

1.18.3 Procedures

Procedure: maven goals . options

Run the Maven GOALS, forwarding OPTIONS to ‘maven-argv’.

(maven "package" #:arguments '("-DskipTests"))
Procedure: maven-argv goals KEY: #:arguments #:file #:settings #:profiles #:properties #:offline? #:update-snapshots? #:quiet? #:errors? #:debug? #:threads #:batch-mode? #:no-transfer-progress? #:fail-at-end? #:also-make? #:also-make-dependents? #:projects #:resume-from

Return the argv that runs the Maven GOALS, without running it.

GOALS is a goal or phase name, or a list of them. FILE names a POM or a project directory with ‘-f’; SETTINGS a settings file with ‘-s’. PROFILES and PROJECTS become ‘-P’ and ‘-pl’ lists. PROPERTIES become ‘-D’ words. THREADS is a positive number or a string such as ‘"1C"’. ARGUMENTS are appended as they are, so a plugin option this builder does not name still reaches Maven.

(maven-argv '("clean" "package")
            #:properties '(("skipTests" . "true"))
            #:profiles '("release"))
⇒ ("mvn" "-P" "release" "-DskipTests=true" "clean" "package")
Procedure: maven-clean . arguments

Remove the build output with ‘mvn clean’, passing ARGUMENTS.

Procedure: maven-compile . arguments

Compile the sources with ‘mvn compile’, passing ARGUMENTS.

Procedure: maven-dependency-tree . arguments

Print the dependency tree with ‘mvn dependency:tree’, passing ARGUMENTS.

Procedure: maven-deploy . arguments

Deploy the artefact with ‘mvn deploy’, passing ARGUMENTS.

Procedure: maven-effective-pom . arguments

Print the effective POM with ‘mvn help:effective-pom’, passing ARGUMENTS.

Procedure: maven-install . arguments

Install the artefact into the local repository, passing ARGUMENTS.

Procedure: maven-output argv KEY: #:allow-failure?

Run the Maven ARGV and return its standard output.

A query runs even in a dry run, because it reads the project rather than changing it; ‘maven help:evaluate’ is the usual one.

Procedure: maven-package . arguments

Package the artefact with ‘mvn package’, passing ARGUMENTS.

Procedure: maven-site . arguments

Build the project site with ‘mvn site’, passing ARGUMENTS.

Procedure: maven-test . arguments

Run the tests with ‘mvn test’, passing ARGUMENTS.

Procedure: maven-validate . arguments

Validate the project with ‘mvn validate’, passing ARGUMENTS.

Procedure: maven-verify . arguments

Run the verification phase with ‘mvn verify’, passing ARGUMENTS.

Procedure: maven-wrapper-command OPT: directory

Return the Maven command to use in DIRECTORY.

A checkout with an executable ‘mvnw’ answers with it, because that is the Maven version the project pins; otherwise the answer is ‘maven-command’.

Procedure: maven-wrapper? OPT: directory

Return #t when DIRECTORY holds an executable Maven wrapper.


1.19 (maak net)

The download half of a task, without a shell string: curl and wget with their common flags as keyword arguments, plus the few higher-level answers a task actually asks for – fetch a URL to a file, read a URL into a string, check a status code, post JSON, mirror a site.

Every command helper has an ‘-argv’ builder. The builder returns the words without running anything: that is what the procedure feeds to ‘run’, what –dry-run prints, and what a test can assert without a network. The builders are exported for the same reason the archive and container builders are: a task that needs to log or extend a command should not have to rebuild its flags. ‘download’ is the exception, because it chooses between the two programs; it has no single command line of its own.

‘download’ is the one helper that chooses a program. ‘fetch-command’ is a parameter, detected as curl when it is installed and wget otherwise, and overridable with MAAK_FETCH or a lexical ‘parameterize’. The direct curl- and wget- helpers never consult it: when a task needs a particular tool, it names that tool.

Nothing here touches the network when the module is loaded.

1.19.1 Overview

  • fetch-command — A parameter object.
  • curl — Run curl with ARGUMENTS, a list of strings; see ‘curl-argv’.
  • curl-argv — Return the argv that runs curl with ARGUMENTS.
  • curl-download — Download URL with curl; see ‘curl-download-argv’.
  • curl-download-argv — Return the argv that downloads URL to OUTPUT.
  • curl-get — Fetch URL with curl; see ‘curl-get-argv’ for the options.
  • curl-get-argv — Return the argv that fetches URL with curl.
  • curl-head — Ask for URL’s headers with curl; see ‘curl-head-argv’.
  • curl-head-argv — Return the argv that asks for URL’s headers with a HEAD request.
  • curl-output — Run curl with ARGUMENTS and return what it printed.
  • curl-post — Send a POST request to URL; see ‘curl-post-argv’.
  • curl-post-argv — Return the argv that sends a POST request to URL.
  • curl-status — Return URL’s HTTP status code as a number.
  • curl-status-argv — Return the argv that prints URL’s HTTP status code.
  • curl-text — Fetch URL with curl and return the body as a string.
  • curl-text-argv — Return the argv that fetches URL’s body for a task to read.
  • curl-upload — Upload FILE to URL with curl; see ‘curl-upload-argv’.
  • curl-upload-argv — Return the argv that uploads FILE to URL with curl.
  • detect-fetch-command — Return the download program ‘download’ should use.
  • download — Download URL with the detected downloader.
  • fetch-available? — Return #t when COMMAND, the downloader ‘download’ would use, is on PATH.
  • wget — Run wget with ARGUMENTS, a list of strings; see ‘wget-argv’.
  • wget-argv — Return the argv that runs wget with ARGUMENTS.
  • wget-download — Download URL with wget; see ‘wget-download-argv’.
  • wget-download-argv — Return the argv that downloads URL with wget.
  • wget-mirror — Mirror the site at URL with wget; see ‘wget-mirror-argv’.
  • wget-mirror-argv — Return the argv that mirrors the site at URL with wget.
  • wget-output — Run wget with ARGUMENTS and return what it printed.
  • wget-text — Fetch URL with wget and return the body as a string.
  • wget-text-argv — Return the argv that fetches URL’s body for a task to read.

1.19.2 Parameters

Parameter: fetch-command

Default value:

"curl"

1.19.3 Procedures

Procedure: curl arguments KEY: #:allow-failure? #:verbose?

Run curl with ARGUMENTS, a list of strings; see ‘curl-argv’.

Procedure: curl-argv arguments

Return the argv that runs curl with ARGUMENTS.

The escape hatch for a flag no helper models; nothing is handed to a shell, so an argument with a space in it stays one argument.

Procedure: curl-download url KEY: #:output #:directory #:create-dirs? #:resume? #:headers #:follow? #:fail? #:silent? #:show-error? #:compressed? #:timeout #:retry #:user #:user-agent #:insecure? #:cookie #:cookie-jar #:extra #:allow-failure? #:verbose?

Download URL with curl; see ‘curl-download-argv’.

Procedure: curl-download-argv url KEY: #:output #:directory #:create-dirs? #:resume? #:headers #:follow? #:fail? #:silent? #:show-error? #:compressed? #:timeout #:retry #:user #:user-agent #:insecure? #:cookie #:cookie-jar #:extra

Return the argv that downloads URL to OUTPUT.

Without OUTPUT curl keeps the remote name, which is what –remote-name means. DIRECTORY is curl’s –output-dir, and CREATE-DIRS? makes the parents of the destination. RESUME? continues a partial download.

Procedure: curl-get url KEY: #:output #:output-dir #:create-dirs? #:resume? #:headers #:follow? #:fail? #:silent? #:show-error? #:compressed? #:timeout #:retry #:user #:user-agent #:insecure? #:cookie #:cookie-jar #:extra #:allow-failure? #:verbose?

Fetch URL with curl; see ‘curl-get-argv’ for the options.

Procedure: curl-get-argv url KEY: #:output #:output-dir #:create-dirs? #:resume? #:headers #:follow? #:fail? #:silent? #:show-error? #:compressed? #:timeout #:retry #:user #:user-agent #:insecure? #:cookie #:cookie-jar #:extra

Return the argv that fetches URL with curl.

The defaults are the ones a task wants: redirects are followed, an HTTP error is a failure, and the progress meter is replaced by silence plus real errors. OUTPUT writes the body to a file, OUTPUT-DIR names the directory for it, and CREATE-DIRS? creates the parents. RESUME? continues a partial file.

Procedure: curl-head url KEY: #:headers #:follow? #:fail? #:silent? #:show-error? #:timeout #:retry #:user #:user-agent #:insecure? #:cookie #:extra #:allow-failure? #:verbose?

Ask for URL’s headers with curl; see ‘curl-head-argv’.

Procedure: curl-head-argv url KEY: #:headers #:follow? #:fail? #:silent? #:show-error? #:timeout #:retry #:user #:user-agent #:insecure? #:cookie #:extra

Return the argv that asks for URL’s headers with a HEAD request.

Procedure: curl-output arguments KEY: #:allow-failure?

Run curl with ARGUMENTS and return what it printed.

This is the reading counterpart of ‘curl’: the body is a value a task can trim, split or parse. In dry-run mode nothing runs, the command is printed, and the empty string comes back.

Procedure: curl-post url KEY: #:data #:json #:data-file #:form #:method #:headers #:follow? #:fail? #:silent? #:show-error? #:compressed? #:timeout #:retry #:user #:user-agent #:insecure? #:cookie #:cookie-jar #:extra #:allow-failure? #:verbose?

Send a POST request to URL; see ‘curl-post-argv’.

Procedure: curl-post-argv url KEY: #:data #:json #:data-file #:form #:method #:headers #:follow? #:fail? #:silent? #:show-error? #:compressed? #:timeout #:retry #:user #:user-agent #:insecure? #:cookie #:cookie-jar #:extra

Return the argv that sends a POST request to URL.

DATA is a body string, JSON is a JSON body sent with curl’s –json (which also sets the content type and Accept header), DATA-FILE is a file whose bytes are the body, and FORM is a list of –form fields. At least one of them must be given. METHOD defaults to POST; pass another method for an API that spells its update differently.

Procedure: curl-status url KEY: #:headers #:follow? #:timeout #:retry #:user #:user-agent #:insecure? #:cookie #:extra #:allow-failure?

Return URL’s HTTP status code as a number.

A transport failure raises unless ALLOW-FAILURE? is #t, in which case #f is returned when curl prints no code. An HTTP error is still a status: 404 comes back as 404.

Procedure: curl-status-argv url KEY: #:headers #:follow? #:timeout #:retry #:user #:user-agent #:insecure? #:cookie #:extra

Return the argv that prints URL’s HTTP status code.

The body is discarded and –fail is deliberately left off, so a 404 is reported as 404 rather than as a failed download.

Procedure: curl-text url KEY: #:headers #:follow? #:fail? #:timeout #:retry #:user #:user-agent #:insecure? #:cookie #:extra #:allow-failure?

Fetch URL with curl and return the body as a string.

Use this instead of ‘curl-get’ when the task needs the response, not a line on the terminal. A non-zero curl exits non-zero and raises, unless ALLOW-FAILURE? is #t.

Procedure: curl-text-argv url KEY: #:headers #:follow? #:fail? #:timeout #:retry #:user #:user-agent #:insecure? #:cookie #:extra

Return the argv that fetches URL’s body for a task to read.

Procedure: curl-upload url file KEY: #:method #:headers #:follow? #:fail? #:silent? #:show-error? #:compressed? #:timeout #:retry #:user #:user-agent #:insecure? #:cookie #:cookie-jar #:extra #:allow-failure? #:verbose?

Upload FILE to URL with curl; see ‘curl-upload-argv’.

Procedure: curl-upload-argv url file KEY: #:method #:headers #:follow? #:fail? #:silent? #:show-error? #:compressed? #:timeout #:retry #:user #:user-agent #:insecure? #:cookie #:cookie-jar #:extra

Return the argv that uploads FILE to URL with curl.

METHOD defaults to PUT, which is what an object store usually expects; pass POST for an API that takes the file as a form upload.

Procedure: detect-fetch-command KEY: #:path #:preferred

Return the download program ‘download’ should use.

PREFERRED, when non-empty, wins unchanged. Otherwise curl is chosen when it is on PATH, then wget. The fallback is curl even when neither is installed, so a missing program is reported as a missing program rather than silently replaced by the other one.

PATH is the search path, PATH itself by default, so the choice can be tested without changing the process environment.

(detect-fetch-command #:path search-path)
(detect-fetch-command #:preferred "wget")
Procedure: download url KEY: #:output #:directory #:continue? #:headers #:user #:password #:user-agent #:timeout #:retries #:quiet? #:tool #:allow-failure? #:verbose?

Download URL with the detected downloader.

TOOL is curl or wget; the default comes from ‘fetch-command’, which is curl when it is installed, wget otherwise, or whatever MAAK_FETCH names. OUTPUT is the destination file (the remote name when it is #f), DIRECTORY is the directory it belongs in, and CONTINUE? resumes a partial file. HEADERS, USER-AGENT, TIMEOUT and RETRIES are passed to either program; USER and PASSWORD become curl’s –user or wget’s –user/–password.

(download "https://example.org/release.tar.gz"
          #:output "release.tar.gz"
          #:continue? #t)
(parameterize ((fetch-command "wget"))
  (download "https://example.org/" #:output "index.html"))
Procedure: fetch-available? KEY: #:command

Return #t when COMMAND, the downloader ‘download’ would use, is on PATH.

Procedure: wget arguments KEY: #:allow-failure? #:verbose?

Run wget with ARGUMENTS, a list of strings; see ‘wget-argv’.

Procedure: wget-argv arguments

Return the argv that runs wget with ARGUMENTS.

The escape hatch for a flag no helper models; nothing is handed to a shell, so an argument with a space in it stays one argument.

Procedure: wget-download url KEY: #:output #:directory #:continue? #:quiet? #:timestamping? #:no-clobber? #:headers #:user #:password #:timeout #:tries #:user-agent #:extra #:allow-failure? #:verbose?

Download URL with wget; see ‘wget-download-argv’.

Procedure: wget-download-argv url KEY: #:output #:directory #:continue? #:quiet? #:timestamping? #:no-clobber? #:headers #:user #:password #:timeout #:tries #:user-agent #:extra

Return the argv that downloads URL with wget.

OUTPUT names the file, DIRECTORY is the prefix the file is written under, and CONTINUE? resumes a partial file. QUIET? silences the progress output; TIMESTAMPING? and NO-CLOBBER? decide what to do with an existing file.

Procedure: wget-mirror url KEY: #:directory #:no-parent? #:page-requisites? #:convert-links? #:cut-dirs #:no-host-directories? #:quiet? #:headers #:user-agent #:timeout #:tries #:extra #:allow-failure? #:verbose?

Mirror the site at URL with wget; see ‘wget-mirror-argv’.

Procedure: wget-mirror-argv url KEY: #:directory #:no-parent? #:page-requisites? #:convert-links? #:cut-dirs #:no-host-directories? #:quiet? #:headers #:user-agent #:timeout #:tries #:extra

Return the argv that mirrors the site at URL with wget.

The defaults are the ones a documentation snapshot wants: recursion that stays under URL, no host directory at the top, and a DIRECTORY prefix when one is named. PAGE-REQUISITES? also fetches the images and stylesheets, CONVERT-LINKS? rewrites the saved pages to point at them, and CUT-DIRS drops leading path components from the local tree.

Procedure: wget-output arguments KEY: #:allow-failure?

Run wget with ARGUMENTS and return what it printed.

In dry-run mode nothing runs, the command is printed, and the empty string comes back.

Procedure: wget-text url KEY: #:headers #:user #:password #:user-agent #:timeout #:tries #:extra #:allow-failure?

Fetch URL with wget and return the body as a string.

wget writes the body to standard output with –output-document=-, which is what lets a task read it instead of finding a file afterwards. The progress output is silenced so the result is only the body.

Procedure: wget-text-argv url KEY: #:headers #:user #:password #:user-agent #:timeout #:tries #:extra

Return the argv that fetches URL’s body for a task to read.


1.20 (maak niri)

Helpers for talking to a running niri compositor through ‘niri msg’. A task that changes the session – focus a workspace, spawn a program, put a window on another output – can do it in a line rather than in a shell string, and a task that reads the session can ask for JSON and parse it.

Two families are exported. The queries (‘niri-outputs‘, ‘niri-workspaces‘, ‘niri-windows’, ...) are ordinary commands; ‘niri-capture‘ runs any of them and returns what niri printed, which is what a task needs for a decision. The actions (‘niri-focus-workspace‘, ‘niri-spawn‘, ...) are thin wrappers over ‘niri msg action’.

Every helper has an ‘-argv‘ builder where the command has options worth asserting on. The builders are what ‘–dry-run‘ prints and what the tests exercise; no compositor is needed to check the command line.

‘niri msg’ is deliberately not started when this module loads. A task that needs niri checks ‘niri-available?’ first, or lets the missing program be reported by ‘run’ as exit code 127.

1.20.1 Overview

1.20.2 Procedures

Procedure: niri arguments KEY: #:json? #:allow-failure? #:verbose?

Send ARGUMENTS to ‘niri msg’.

This is the escape hatch for subcommands and flags without a wrapper. Nothing is handed to a shell, so a program name or a workspace name with a space in it reaches niri as one argument.

A command that exits non-zero raises a maak error, unless ALLOW-FAILURE? is #t, in which case the call answers #f – the usual ‘run’ contract.

Procedure: niri-action arguments KEY: #:json? #:allow-failure? #:verbose?

Perform an action with ARGUMENTS, through ‘niri msg action’.

A bare action name is enough for the ones that take no argument, such as close-window; the others take their reference after it.

(niri-action (list "focus-workspace" "2"))
(niri-action (list "spawn" "--" "foot" "-e" "htop"))
Procedure: niri-action-argv arguments KEY: #:json?

Return the argv that performs an action with its ARGUMENTS.

The action name comes first and its own flags follow, so ("focus-workspace" "2") is the argv for ‘focus-workspace 2’.

Procedure: niri-argv arguments KEY: #:json?

Return the argv that sends ARGUMENTS to ‘niri msg‘.

With JSON? the global --json flag is inserted before the subcommand, which is where niri expects it. ARGUMENTS is the subcommand and its flags: ("outputs"), ("action" "close-window"), and so on.

Procedure: niri-available?

Return #t when the niri program can be found on PATH.

Procedure: niri-capture arguments KEY: #:json? #:allow-failure?

Send ARGUMENTS to ‘niri msg’ and return what it printed.

This is the query form: the output is a string a task can trim, split or hand to a JSON parser, rather than a line on the terminal. In dry-run mode nothing runs, the command is printed, and the empty string comes back.

Procedure: niri-casts KEY: #:json? #:allow-failure?

List the screencasts.

Procedure: niri-close-window KEY: #:json? #:allow-failure?

Close the focused window.

Procedure: niri-focus-column index KEY: #:json? #:allow-failure?

Focus the column at INDEX.

Procedure: niri-focus-monitor name KEY: #:json? #:allow-failure?

Focus the monitor NAME.

Procedure: niri-focus-window id KEY: #:json? #:allow-failure?

Focus the window with ID.

Procedure: niri-focus-window-previous KEY: #:json? #:allow-failure?

Focus the previously focused window.

Procedure: niri-focus-workspace reference KEY: #:json? #:allow-failure?

Focus the workspace REFERENCE, an index or a name.

Procedure: niri-focus-workspace-previous KEY: #:json? #:allow-failure?

Focus the previous workspace.

Procedure: niri-focused-output KEY: #:json? #:allow-failure?

Print information about the focused output.

Procedure: niri-focused-window KEY: #:json? #:allow-failure?

Print information about the focused window.

Procedure: niri-fullscreen-window KEY: #:json? #:allow-failure?

Toggle fullscreen on the focused window.

Procedure: niri-keyboard-layouts KEY: #:json? #:allow-failure?

Print the configured keyboard layouts.

Procedure: niri-layers KEY: #:json? #:allow-failure?

List the open layer-shell surfaces.

Procedure: niri-move-column-to-monitor name KEY: #:json? #:allow-failure?

Move the focused column to the monitor NAME.

Procedure: niri-move-column-to-workspace reference KEY: #:json? #:allow-failure?

Move the focused column to the workspace REFERENCE.

Procedure: niri-move-window-to-monitor name KEY: #:json? #:allow-failure?

Move the focused window to the monitor NAME.

Procedure: niri-move-window-to-workspace reference KEY: #:window-id #:focus #:json? #:allow-failure?

Move the focused window, or WINDOW-ID, to the workspace REFERENCE.

FOCUS is default unless given: with #t the focus follows the window, and with #f it stays on the original workspace, which niri spells as --focus true and --focus false.

Procedure: niri-output output action . arguments

Change OUTPUT with ACTION and ARGUMENTS; see ‘niri-output-argv’.

The change is temporary and is not written to niri’s configuration file.

Procedure: niri-output-argv output action . arguments

Return the argv that changes OUTPUT with ACTION and ARGUMENTS.

The output name comes first and the action after it, which is the order ‘niri msg output’ requires: niri msg output DP-1 mode 1920x1080@60.

(niri-output-argv "DP-1" "scale" "1.5")
Procedure: niri-output-mode output mode KEY: #:allow-failure?

Set OUTPUT’s mode, such as 1920x1080@60.

Procedure: niri-output-off output KEY: #:allow-failure?

Turn OUTPUT off.

Procedure: niri-output-on output KEY: #:allow-failure?

Turn OUTPUT on.

Procedure: niri-output-position output x y KEY: #:allow-failure?

Set OUTPUT’s position on the desktop to X and Y.

Procedure: niri-output-scale output scale KEY: #:allow-failure?

Set OUTPUT’s scale, such as 1.5.

Procedure: niri-output-transform output transform KEY: #:allow-failure?

Set OUTPUT’s transform, such as 90 or flipped-180.

Procedure: niri-outputs KEY: #:json? #:allow-failure?

List the connected outputs.

Procedure: niri-overview-state KEY: #:json? #:allow-failure?

Print the overview state.

Procedure: niri-pick-color KEY: #:json? #:allow-failure?

Pick a color from the screen with the mouse.

Procedure: niri-pick-window KEY: #:json? #:allow-failure?

Pick a window with the mouse and print information about it.

Procedure: niri-power-off-monitors KEY: #:json? #:allow-failure?

Power off all monitors via DPMS.

Procedure: niri-power-on-monitors KEY: #:json? #:allow-failure?

Power on all monitors via DPMS.

Procedure: niri-quit KEY: #:skip-confirmation? #:json? #:allow-failure?

Exit niri.

SKIP-CONFIRMATION? is the default because a task that asks niri to quit is not sitting at a keyboard to press Enter.

Procedure: niri-request-error KEY: #:json? #:allow-failure?

Ask niri to return an error, which is useful for checking a client’s error handling against a live compositor.

Procedure: niri-screenshot KEY: #:json? #:allow-failure?

Open the screenshot UI.

Procedure: niri-screenshot-screen KEY: #:json? #:allow-failure?

Screenshot the focused screen.

Procedure: niri-screenshot-window KEY: #:json? #:allow-failure?

Screenshot the focused window.

Procedure: niri-set-column-width change KEY: #:json? #:allow-failure?

Change the width of the focused column by CHANGE.

Procedure: niri-set-window-width change KEY: #:id #:json? #:allow-failure?

Change the width of the focused window, or of window ID, by CHANGE.

CHANGE is a string such as +10% or 500, exactly as niri’s command line takes it.

Procedure: niri-set-workspace-name name KEY: #:json? #:allow-failure?

Set the name of the focused workspace to NAME.

Procedure: niri-spawn command KEY: #:json? #:allow-failure?

Spawn COMMAND, a list of strings, without a shell.

The -- that separates niri’s own flags from the program is added here, so a program with a flag that looks like niri’s is still passed through.

Procedure: niri-spawn-sh command KEY: #:json? #:allow-failure?

Spawn COMMAND through the shell.

Use ‘niri-spawn’ when the program and its arguments are already separate strings; this one is for a line that needs a shell.

Procedure: niri-toggle-overview KEY: #:json? #:allow-failure?

Toggle the overview.

Procedure: niri-toggle-windowed-fullscreen KEY: #:json? #:allow-failure?

Toggle windowed (fake) fullscreen on the focused window.

Procedure: niri-unset-workspace-name KEY: #:json? #:allow-failure?

Unset the name of the focused workspace.

Procedure: niri-version KEY: #:json? #:allow-failure?

Print the version of the running niri instance.

Procedure: niri-windows KEY: #:json? #:allow-failure?

List the open windows.

Procedure: niri-workspaces KEY: #:json? #:allow-failure?

List the workspaces.


1.21 (maak nix)

Nix helpers, mirroring the Guix ones in ‘(maak dsl)’. maak is Guix-first, but a task that has to build on a Nix machine should not have to hand-roll ‘nix-shell’ or ‘nix develop’ invocations either.

The two families are deliberately separate: ‘nix-shell’ and ‘nix-build’ are the classic, ‘shell.nix’/‘default.nix’ based commands, while ‘nix-develop’, ‘nix-flake-build’ and ‘nix-run’ are the flake based ones. ‘nix-flake-check’ validates a flake the way ‘guix build’ would validate a package.

Every helper here builds one command line and hands it to ‘$’, so all of them take the same five decorations: ‘#:env’, ‘#:sudo?’, ‘#:dev-null?’, ‘#:allow-failure?’ and ‘#:async?’. See ‘$’ in ‘(maak dsl)’ for what each does, and note that ‘#:env’ is what makes ‘nix-shell –run’ or ‘nix develop –command’ see the variables a build needs.

1.21.1 Overview

  • nix-build — Build the derivation in FILE with the classic ‘nix-build’.
  • nix-develop — Run CMD-PARTS inside the development shell of the flake FLAKE.
  • nix-flake-build — Build the flake FLAKE, optionally selecting the output ATTR.
  • nix-flake-check — Check every output of the flake FLAKE, as ‘nix flake check’ does.
  • nix-run — Run the application APP of the flake FLAKE with CMD-PARTS as its arguments.
  • nix-shell — Run CMD-PARTS inside a Nix shell.

1.21.2 Procedures

Procedure: nix-build KEY: #:file #:arguments #:out-link #:verbose? #:env #:sudo? #:dev-null? #:allow-failure? #:async?

Build the derivation in FILE with the classic ‘nix-build’.

ARGUMENTS are extra words passed through verbatim, for example ‘–argstr system x86_64-linux’. OUT-LINK names the result symlink (‘–out-link’), defaulting to Nix’s own ‘result’.

Procedure: nix-develop cmd-parts KEY: #:flake #:impure? #:join #:verbose? #:env #:sudo? #:dev-null? #:allow-failure? #:async?

Run CMD-PARTS inside the development shell of the flake FLAKE.

FLAKE is a path or flake reference such as ‘.‘ or ‘github:owner/repo’. With IMPURE? the shell inherits the host environment (‘–impure’), which some tools that read environment variables need.

(nix-develop '("make test") #:flake ".")
Procedure: nix-flake-build KEY: #:flake #:attr #:verbose? #:env #:sudo? #:dev-null? #:allow-failure? #:async?

Build the flake FLAKE, optionally selecting the output ATTR.

(nix-flake-build #:flake "." #:attr "packages.x86_64-linux.maak")
Procedure: nix-flake-check KEY: #:flake #:all-systems? #:verbose? #:env #:sudo? #:dev-null? #:allow-failure? #:async?

Check every output of the flake FLAKE, as ‘nix flake check’ does.

With ALL-SYSTEMS? the check runs for all systems the flake declares rather than just the current one.

Procedure: nix-run cmd-parts KEY: #:flake #:app #:join #:verbose? #:env #:sudo? #:dev-null? #:allow-failure? #:async?

Run the application APP of the flake FLAKE with CMD-PARTS as its arguments.

(nix-run '("--version") #:flake "." #:app "maak")
Procedure: nix-shell cmd-parts KEY: #:file #:pure? #:packages #:join #:verbose? #:env #:sudo? #:dev-null? #:allow-failure? #:async?

Run CMD-PARTS inside a Nix shell.

With FILE the shell is described by that file (typically ‘shell.nix’); without it, Nix looks for ‘shell.nix’ or ‘default.nix’ in the current directory. Each of PACKAGES is added with ‘-p’, and PURE? passes ‘–pure’ so the host environment is hidden.

The command is handed to Nix’s own ‘–run’, so it executes inside the shell rather than after it.

(nix-shell '("python -c 'print(1)'") #:packages '("python3"))

1.22 (maak plan)

The plan a task describes: the commands it would run, without running them. ‘–plan’ executes a task with dry-run semantics and the recorder in ‘(maak dsl)’ collects each command the task builds, so the answer describes what the task’s own Scheme decided rather than what a reader of its text could guess.

The rendering lives here, apart from the recording: a step is data – task, kind, argv, environment, directory, elevation – and this module prints it for a person or as JSON for a machine. ‘–plan –json’ is the versioned shape a CI job archives and an editor diffs.

1.22.1 Overview

  • plan-json — Return STEPS as one versioned JSON object, run from ROOT.
  • plan-text — Return STEPS as the plan a person reads.

1.22.2 Procedures

Procedure: plan-json steps OPT: root

Return STEPS as one versioned JSON object, run from ROOT.

The object is ‘{"version":1,"root":...,"plan":[...]}’, and each step names its task, its kind (‘run’, ‘shell’ or ‘pipeline’), its argv (a list of strings, a list of lists for a pipeline, or the one line of a shell command), its working directory, the environment assignments it was given, its escalation, whether its output is discarded and whether it would be started in the background.

Procedure: plan-text steps

Return STEPS as the plan a person reads.

Each step is numbered, named with the task that built it, and followed by its command; the details that are not visible in the command line – the working directory, the environment it was given, the escalation, a discarded output and a background start – are printed underneath it. A task that builds no command says so rather than printing an empty plan.


1.23 (maak python)

Python helpers: uv, the interpreter, the ‘pyproject.toml’ a project already has, and the four checks a Python CI runs.

There is no second environment manager here. uv owns the lock file, the virtual environment and the interpreter it downloads; a maak task runs the command and reads the result. ‘uv-argv’ is a pure builder, so a test asserts the command line without uv installed, and ‘uv’ feeds that list to ‘run’, so ‘–dry-run’ prints it and ‘–plan’ records it. An option this builder does not name travels as an argument, which is how a subcommand maak has never heard of is still a uv command.

The pyproject readers answer the two questions a release task asks – what is this package called, and what version is it – from the file itself, because they are answered with no uv, no network and no virtual environment. They read the file with ‘(maak formats)’, so a file the reader understands is a file they answer for, and anything else is a maak error naming the line.

The programs are parameters, honoured from MAAK_UV then UV, MAAK_UVX then UVX, and MAAK_PYTHON then PYTHON. A value may carry a wrapper (‘"uv –preview"’), split into words the way an unquoted shell word is, so a task can pin an option for one command.

1.23.1 Overview

  • pyproject-file — A parameter object.
  • python-command — A parameter object.
  • uv-command — A parameter object.
  • uvx-command — A parameter object.
  • pyproject-data — Return PATH read as TOML, a string-keyed alist, in file order.
  • python — Run the Python interpreter, forwarding OPTIONS to ‘python-argv’.
  • python-argv — Return the argv that runs the Python interpreter, without running it.
  • python-build-backend — Return the build backend of the project, or #f when it names none.
  • python-check — Run the lint, the type check and the tests, in that order.
  • python-format — Format with ruff, over ARGUMENTS or over the whole project.
  • python-lint — Lint with ruff, over ARGUMENTS or over the whole project.
  • python-module — Run MODULE with the interpreter, passing ARGUMENTS.
  • python-output — Run the interpreter ARGV and return its standard output as a string.
  • python-project — Return the ‘[project]’ table of PATH, or raise when there is none.
  • python-project-name — Return the name the ‘[project]’ table gives the package.
  • python-project-scripts — Return the names of the console scripts the project defines.
  • python-project-version — Return the version the ‘[project]’ table gives the package.
  • python-requires-python — Return the interpreter constraint of the project, or #f when it sets none.
  • python-test — Run the tests with pytest, passing ARGUMENTS to it.
  • python-type-check — Type-check with mypy, over ARGUMENTS or over the whole project.
  • python-version — Return the version line the installed interpreter prints, trimmed.
  • uv — Run uv SUBCOMMAND, forwarding OPTIONS to ‘uv-argv’.
  • uv-add — Add a dependency to the project, passing ARGUMENTS.
  • uv-argv — Return the argv that runs uv SUBCOMMAND, without running it.
  • uv-build — Build the source and wheel distributions into ‘dist/’, passing ARGUMENTS.
  • uv-export — Export the lock file to another format, passing ARGUMENTS.
  • uv-init — Create a new project with ‘uv init’, passing ARGUMENTS.
  • uv-lock — Update the lock file, passing ARGUMENTS.
  • uv-output — Run the uv ARGV and return its standard output as a string.
  • uv-pip — Run a ‘uv pip’ command, passing ARGUMENTS.
  • uv-publish — Publish the built distributions, passing ARGUMENTS.
  • uv-python — Manage the interpreters uv installs, passing ARGUMENTS.
  • uv-remove — Remove a dependency from the project, passing ARGUMENTS.
  • uv-run — Run a command in the project’s environment, passing ARGUMENTS.
  • uv-sync — Synchronise the environment with the lock file, passing ARGUMENTS.
  • uv-tree — Print the dependency tree, passing ARGUMENTS.
  • uv-venv — Create the virtual environment, passing ARGUMENTS.
  • uv-version — Return the version line the installed uv prints, trimmed.
  • uvx — Run a tool installed in a temporary environment, as ‘uvx ruff’ does.
  • uvx-argv — Return the argv that runs uvx with ARGUMENTS.

1.23.2 Parameters

Parameter: pyproject-file

Default value:

"pyproject.toml"
Parameter: python-command

Default value:

"python3"
Parameter: uv-command

Default value:

"uv"
Parameter: uvx-command

Default value:

"uvx"

1.23.3 Procedures

Procedure: pyproject-data OPT: path

Return PATH read as TOML, a string-keyed alist, in file order.

The file is read even in a dry run, like pkg-config: it describes the project rather than changing it, and a plan that left out the version a publish would use would be a plan of a different release.

Procedure: python . options

Run the Python interpreter, forwarding OPTIONS to ‘python-argv’.

Procedure: python-argv KEY: #:arguments #:module #:isolated?

Return the argv that runs the Python interpreter, without running it.

MODULE runs the module of that name with ‘-m’, which is how a runner that is installed but not on ‘PATH’ is meant to be started. ISOLATED? adds ‘-I’, so the interpreter ignores ‘PYTHONPATH’ and the user’s site directory – what a task wants when it reads a value rather than a local experiment. ARGUMENTS are the words the interpreter or the module is given.

(python-argv #:module "pytest" #:arguments '("-q"))
⇒ ("python3" "-m" "pytest" "-q")
Procedure: python-build-backend OPT: path

Return the build backend of the project, or #f when it names none.

Procedure: python-check

Run the lint, the type check and the tests, in that order.

The order is the cheap failures first: a lint error is a second, a failing test is a minute. Each of the three is its own task as well, so a run that wants one of them names it.

Procedure: python-format . arguments

Format with ruff, over ARGUMENTS or over the whole project.

Procedure: python-lint . arguments

Lint with ruff, over ARGUMENTS or over the whole project.

The default is the project directory, so a check task reads ‘(python-lint)’; the words a caller gives replace it rather than adding to it, because a path and a default path are two answers to the same question.

Procedure: python-module module . arguments

Run MODULE with the interpreter, passing ARGUMENTS.

Procedure: python-output argv KEY: #:allow-failure?

Run the interpreter ARGV and return its standard output as a string.

See ‘uv-output’ for what a query does in a dry run and on failure.

Procedure: python-project OPT: path

Return the ‘[project]’ table of PATH, or raise when there is none.

Procedure: python-project-name OPT: path

Return the name the ‘[project]’ table gives the package.

Procedure: python-project-scripts OPT: path

Return the names of the console scripts the project defines.

Procedure: python-project-version OPT: path

Return the version the ‘[project]’ table gives the package.

A project that lists "version" in ‘dynamic’ has no version in the file: it is computed by the build backend, and this raises rather than guessing at what the backend would answer.

Procedure: python-requires-python OPT: path

Return the interpreter constraint of the project, or #f when it sets none.

Procedure: python-test . arguments

Run the tests with pytest, passing ARGUMENTS to it.

(python-test)
(python-test "-k" "release" "-x")
Procedure: python-type-check . arguments

Type-check with mypy, over ARGUMENTS or over the whole project.

Procedure: python-version

Return the version line the installed interpreter prints, trimmed.

Procedure: uv subcommand . options

Run uv SUBCOMMAND, forwarding OPTIONS to ‘uv-argv’.

(uv "run" #:arguments '("pytest" "-q"))
Procedure: uv-add . arguments

Add a dependency to the project, passing ARGUMENTS.

Procedure: uv-argv subcommand KEY: #:arguments #:project #:directory #:cache-dir #:offline? #:no-cache? #:no-progress? #:refresh? #:verbose #:quiet? #:color #:frozen? #:locked? #:no-sync? #:env-file #:python

Return the argv that runs uv SUBCOMMAND, without running it.

The options uv documents for the program as a whole – PROJECT, DIRECTORY, CACHE-DIR, OFFLINE?, NO-CACHE?, NO-PROGRESS?, REFRESH?, the verbosity and COLOR – come before SUBCOMMAND. The ones uv documents for the commands that read the project – FROZEN?, LOCKED?, NO-SYNC?, ENV-FILE and PYTHON – come after it, which is where uv accepts them. ARGUMENTS are appended as they are, so an option this builder does not name, or the words ‘uv run’ passes to the program, still reach uv.

VERBOSE is #t for one ‘-v’ or a positive number for that many.

(uv-argv "sync" #:frozen? #t #:python "3.12")
⇒ ("uv" "sync" "--frozen" "--python" "3.12")

(uv-argv "run" #:arguments '("pytest" "-q"))
⇒ ("uv" "run" "pytest" "-q")
Procedure: uv-build . arguments

Build the source and wheel distributions into ‘dist/’, passing ARGUMENTS.

Procedure: uv-export . arguments

Export the lock file to another format, passing ARGUMENTS.

Procedure: uv-init . arguments

Create a new project with ‘uv init’, passing ARGUMENTS.

Procedure: uv-lock . arguments

Update the lock file, passing ARGUMENTS.

Procedure: uv-output argv KEY: #:allow-failure?

Run the uv ARGV and return its standard output as a string.

A query runs even in a dry run: it reads the project rather than changing it. A failure raises a maak error naming the command, or comes back as #f when the caller asked for the exit status instead.

Procedure: uv-pip . arguments

Run a ‘uv pip’ command, passing ARGUMENTS.

Procedure: uv-publish . arguments

Publish the built distributions, passing ARGUMENTS.

A dry run of the release is ‘(uv-publish "–dry-run")’: uv’s own flag is what makes it one, while maak’s dry run prints the command instead.

Procedure: uv-python . arguments

Manage the interpreters uv installs, passing ARGUMENTS.

Procedure: uv-remove . arguments

Remove a dependency from the project, passing ARGUMENTS.

Procedure: uv-run . arguments

Run a command in the project’s environment, passing ARGUMENTS.

The words after ‘uv run’ are the program and its own arguments, so ‘(uv-run "pytest" "-q")’ runs pytest quietly.

(uv-run "pytest" "-k" "release")
(uv-run "python" "-c" "import example; print(example.__version__)")
Procedure: uv-sync . arguments

Synchronise the environment with the lock file, passing ARGUMENTS.

Procedure: uv-tree . arguments

Print the dependency tree, passing ARGUMENTS.

Procedure: uv-venv . arguments

Create the virtual environment, passing ARGUMENTS.

Procedure: uv-version

Return the version line the installed uv prints, trimmed.

Procedure: uvx . arguments

Run a tool installed in a temporary environment, as ‘uvx ruff’ does.

Procedure: uvx-argv . arguments

Return the argv that runs uvx with ARGUMENTS.


1.24 (maak shell)

The shell helpers that sit on top of ‘(maak dsl)’. Where the core module offers the primitives (‘$’, ‘run’, ‘syscall’, ‘cp’, a few file moves), this one collects the everyday conveniences a task reaches for: locating a program before relying on it, running a command and reading its output, changing directory for the duration of a thunk, and reading environment variables.

Every helper here honours ‘dry-run?’ and ‘quiet?’ through the ‘run’ or ‘syscall’ it is built on, so a dry run prints instead of acting.

1.24.1 Overview

  • capture — Run COMMAND and return its standard output as a string.
  • cd — Change the process working directory to DIR and return it.
  • chmod-file — Change the permissions of FILE to MODE, an octal string such as 755.
  • command-exists? — Return #t when COMMAND can be found on ‘PATH’.
  • env-file-entries — Return the ‘(NAME .
  • env-get — Return the value of environment variable NAME, or DEFAULT when unset.
  • env-set! — Set environment variable NAME to VALUE and return VALUE.
  • env-unset! — Remove environment variable NAME.
  • home-dir — Return the current user’s home directory, or the empty string when unset.
  • install-directory — Create DIRECTORY and its parents with MODE.
  • install-file — Install SOURCE at DESTINATION with MODE, creating parent directories.
  • ln-s — Create a symbolic link LINK-NAME pointing at TARGET.
  • load-env-file — Read the ‘NAME=VALUE’ assignments of PATH into the environment.
  • read-file — Return the contents of FILE as a string.
  • require-command — Return the path of COMMAND, raising a maak error when it is missing.
  • shell-quote — Return STR quoted so that a shell reads it as one literal word.
  • tmp-dir — Return the directory for temporary files, honouring ‘TMPDIR’.
  • touch — Create FILE if it does not exist, or update its timestamp.
  • which — Return the absolute path of COMMAND on ‘PATH’, or #f when it is missing.
  • with-directory — Call THUNK with the process working directory changed to DIR.
  • with-env — Call THUNK with environment variable NAME set to VALUE.
  • with-env-vars — Call THUNK with every NAME and VALUE pair of VARIABLES set.
  • write-file — Write CONTENT to FILE, creating its directory first when needed.

1.24.2 Procedures

Procedure: capture command KEY: #:error? #:allow-failure?

Run COMMAND and return its standard output as a string.

With ERROR? true the command’s standard error is captured too.

A command that exits non-zero raises a maak error naming its exit code, rather than returning the empty or partial output it managed to produce: a caller that reads ‘""’ cannot tell a command that printed nothing from one that failed. With ALLOW-FAILURE? true the output is returned anyway, and the caller decides what the failure means.

In dry-run mode the command is only printed and the empty string is returned. Use ‘$’ when a failing command must stop the task without its output, and ‘run’ when the command takes arguments that a shell must not split.

(string-trim (capture describe-tags-command))
Procedure: cd dir

Change the process working directory to DIR and return it.

Unlike ‘with-directory’ the change lasts for the rest of the run, which is what a task that only ever works from one place wants.

Procedure: chmod-file mode file KEY: #:recursive? #:verbose? #:expand?

Change the permissions of FILE to MODE, an octal string such as 755.

With EXPAND? #t the shell expands FILE, so a wildcard names every file whose permissions are to change.

Procedure: command-exists? command

Return #t when COMMAND can be found on ‘PATH’.

Procedure: env-file-entries path

Return the ‘(NAME . VALUE)’ assignments in the environment file PATH.

Blank lines and lines whose first non-blank character is ‘#’ are skipped, as are lines without an ‘=’. A leading ‘export ’ is accepted so a file that is valid for a POSIX shell is valid here too. The name and the value are trimmed, and a value wrapped in matching single or double quotes is unwrapped.

(env-file-entries ".env")
⇒ (("CI" . "1") ("DATABASE_URL" . "postgres://localhost/dev"))
Procedure: env-get name OPT: default

Return the value of environment variable NAME, or DEFAULT when unset.

Procedure: env-set! name value

Set environment variable NAME to VALUE and return VALUE.

Procedure: env-unset! name

Remove environment variable NAME.

Procedure: home-dir

Return the current user’s home directory, or the empty string when unset.

Procedure: install-directory directory KEY: #:mode #:verbose? #:expand?

Create DIRECTORY and its parents with MODE.

The directory counterpart of ‘install-file’: one ‘install -d’ that sets the mode of the directory it creates, which is what a Makefile’s ‘$(MKDIR_P) $(DESTDIR)$(datadir)/app’ does.

Procedure: install-file source destination KEY: #:mode #:verbose? #:expand?

Install SOURCE at DESTINATION with MODE, creating parent directories.

This is the ‘install‘ a Makefile’s ‘install‘ target reaches for, with the destination named in full. MODE is an octal string such as "755" for a program or "644" for data. The parent directories are made with ‘mkdir-p’ first, because ‘install -D’ is a GNU extension and this works wherever ‘install’ does. A ‘DESTDIR’ staging prefix is the caller’s to compose; a task migrates a Makefile’s ‘$(DESTDIR)$(bindir)’ by concatenating it into DESTINATION.

(install-file "build/app" "/usr/local/bin/app" #:mode "755")
Procedure: ln-s target link-name KEY: #:force? #:verbose? #:expand?

Create a symbolic link LINK-NAME pointing at TARGET.

With FORCE? (the default) an existing link is replaced, which is what ‘ln -sf’ does. With EXPAND? #t the shell expands the two paths as words.

Procedure: load-env-file path KEY: #:override?

Read the ‘NAME=VALUE’ assignments of PATH into the environment.

Returns the list of variables that were actually set. A name that is already in the environment keeps its value unless OVERRIDE? is #t: the environment a process was started with has the last word over a file next to the code, which is the precedence ‘dotenv’ established and the one that makes ‘CI=1 maak test’ behave as asked. Pass ‘#:override? #t’ when the file is meant to win.

A missing PATH is not an error – the file is optional by definition – and returns the empty list.

(load-env-file ".env")
(load-env-file ".env.local" #:override? #t)
Procedure: read-file file KEY: #:default

Return the contents of FILE as a string.

When the file does not exist, DEFAULT is returned instead of raising; this keeps a task from having to guard every optional file with ‘file-exists?’.

Procedure: require-command command KEY: #:hint

Return the path of COMMAND, raising a maak error when it is missing.

Use this at the top of a task that depends on an external program so the user learns about the missing tool in one line instead of from a failing shell command.

(require-command guile #:hint "Install Guile 3.")
Procedure: shell-quote str

Return STR quoted so that a shell reads it as one literal word.

The POSIX recipe: wrap the value in single quotes and turn every embedded single quote into the four characters backslash-quote-quote-quote. Unlike ‘~s’, this is safe for spaces, tabs, ‘$’, backticks and newlines.

Procedure: tmp-dir

Return the directory for temporary files, honouring ‘TMPDIR’.

Procedure: touch file KEY: #:verbose? #:expand?

Create FILE if it does not exist, or update its timestamp.

With EXPAND? #t the shell expands FILE, so a wildcard touches every name it matches; see ‘run’ for what the opt-in does to the other helpers.

Procedure: which command

Return the absolute path of COMMAND on ‘PATH’, or #f when it is missing.

(which guile)
⇒ /gnu/store/.../bin/guile
Procedure: with-directory dir thunk

Call THUNK with the process working directory changed to DIR.

The previous directory is restored even when THUNK raises.

(with-directory build-dir (lambda () (syscall make-command)))
Procedure: with-env name value thunk

Call THUNK with environment variable NAME set to VALUE.

The previous value, if any, is restored afterwards.

Procedure: with-env-vars variables thunk

Call THUNK with every NAME and VALUE pair of VARIABLES set.

(with-env-vars configured-variables (lambda () (syscall make-command)))
Procedure: write-file file content KEY: #:append? #:mkdir-parents?

Write CONTENT to FILE, creating its directory first when needed.

With APPEND? #t the content is added to the end of FILE rather than replacing it.


1.25 (maak sift)

sift (https://github.com/jjba23/sift) formats, lints and reads Scheme, Emacs Lisp and Common Lisp, and keeps its three jobs apart: ‘format’ prints or writes, ‘lint’ reports, ‘check’ asks the formatting question without touching the tree, and ‘ci’ asks both at once. Its exit status says which job answered:

0 nothing to report 1 findings, or a file ‘format’ would change 2 a usage error, an unreadable file, or a file that cannot be parsed

That 1 is what makes this module more than a ‘run’. A wrapper that treated it as a crash would report a lint finding as a broken pipeline, and one that ignored it would let a gate pass on a dirty tree, so the status is read here and the gates name which of the two happened.

‘sift-argv’ is a pure builder: a test asserts the command line without sift installed, ‘–dry-run’ prints it and ‘–plan’ records it. The program is a parameter, honoured from MAAK_SIFT then SIFT, and it may carry a wrapper or a path to a checkout’s own ‘bin/sift’, which is how a project lints itself with the sift it is developing.

1.25.1 Overview

  • sift-command — A parameter object.
  • sift — Run sift SUBCOMMAND over FILES, raising when it exits non-zero.
  • sift-argv — Return the argv that runs sift SUBCOMMAND over FILES, without running it.
  • sift-check — Ask whether FILES are formatted, failing the task when one is not.
  • sift-ci — Ask the formatting question and the lint question in one pass.
  • sift-exit-meaning — Return what sift’s exit CODE means: ‘clean’, ‘findings’ or ‘error’.
  • sift-files — Return the Lisp files under DIRECTORY, sorted, skipping EXCLUDE directories.
  • sift-format — Format FILES, rewriting them with WRITE? and printing them otherwise.
  • sift-lint — Lint FILES, failing the task when a rule at SEVERITY or above fires.
  • sift-status — Run the sift ARGV and return its exit status: 0, 1 or 2.

1.25.2 Parameters

Parameter: sift-command

Default value:

"sift"

1.25.3 Procedures

Procedure: sift subcommand files KEY: #:arguments #:verbose?

Run sift SUBCOMMAND over FILES, raising when it exits non-zero.

This is the short form: ‘(sift "lint" "src")’. Use ‘sift-argv’ for the structured options, and one of the gates below when a finding of status 1 should be a task failure with an explanation rather than a bare non-zero exit.

(sift "explain" '() #:arguments '("SIFT012"))
Procedure: sift-argv subcommand files KEY: #:program #:arguments #:dialect #:style #:brackets #:blank-lines #:line-length #:indent #:comment-align? #:sort? #:write? #:check? #:diff? #:fix? #:stdin? #:stdout? #:label #:severity #:output-format #:checkers #:exclude-checkers #:file-filters #:config #:trust-config? #:watch? #:quiet? #:verbose? #:force? #:no-color?

Return the argv that runs sift SUBCOMMAND over FILES, without running it.

FILES is a string or a list of strings, and a directory means every Lisp file below it, which is sift’s own reading of an operand. ARGUMENTS are appended after the files as they are, so an option this builder does not name still reaches sift.

The combinations sift refuses are refused here as well, before anything runs: ‘–write’ with ‘–stdout’, ‘–sort’ without ‘–write’, and ‘ci’ with ‘–fix’.

(sift-argv "check" "src" #:dialect "scheme" #:style "community")
⇒ ("sift" "check" "--dialect" "scheme" "--style" "community" "src")

(sift-argv "lint" '("src" "tests") #:severity "warning"
           #:output-format "github")
Procedure: sift-check files KEY: #:dialect #:style #:arguments #:verbose?

Ask whether FILES are formatted, failing the task when one is not.

This is ‘sift check’: it prints the patch it would make and exits 1, and that 1 becomes a maak error here, so a task named ‘check’ fails the pipeline without a shell ‘|| exit 1’ to remember.

Procedure: sift-ci files KEY: #:dialect #:style #:severity #:output-format #:arguments #:verbose?

Ask the formatting question and the lint question in one pass.

This is the pipeline’s command: ‘sift ci’ writes nothing, reports both kinds of finding, and exits 1 if either answers badly. OUTPUT-FORMAT ‘github’ turns each finding into a workflow annotation, and ‘sarif’ writes one document for a code-scanning service.

Procedure: sift-exit-meaning code

Return what sift’s exit CODE means: ‘clean’, ‘findings’ or ‘error’.

Zero is ‘clean’. One is ‘findings’, which is what the tree answered badly. Anything else is ‘error’, which for sift is a usage error, an unreadable file or a file that cannot be parsed. The decision lives in one place so a gate, a caller reading a status and this module’s test all agree on it.

Procedure: sift-files directory KEY: #:extensions #:exclude

Return the Lisp files under DIRECTORY, sorted, skipping EXCLUDE directories.

sift walks a directory operand itself, so this is for the list a task means rather than a different walk: a project whose fixtures are deliberately unformatted passes ‘#:exclude ’("fixtures")’, which is the ‘find ... -not -path’ the Maak files spell out today, and a project with a second dialect in a corner passes ‘#:extensions’.

EXCLUDE names directories to prune at any depth; the directories that never hold source (‘node_modules‘, ‘.git‘ and the like) are pruned already, by the same walk and the same list ‘(maak watch)’ uses.

(sift-ci (sift-files "src"))
(sift-check (append (sift-files "src")
                    (sift-files "tests" #:exclude '("fixtures"))))
Procedure: sift-format files KEY: #:write? #:check? #:diff? #:style #:dialect #:arguments #:verbose?

Format FILES, rewriting them with WRITE? and printing them otherwise.

This does not fail on a reformatted file, because reformatting is the job. With CHECK? nothing is written and a file that would change is a failure, and with DIFF? the patch is printed instead: the two shapes a CI job wants, and neither of them touches the tree.

Procedure: sift-lint files KEY: #:severity #:output-format #:arguments #:verbose?

Lint FILES, failing the task when a rule at SEVERITY or above fires.

SEVERITY is ‘error’, ‘warning’ or ‘info’ – the smallest one to report, ‘info’ unless given. OUTPUT-FORMAT is ‘human’, ‘json’, ‘null’, ‘github’ or ‘sarif’, and it changes what is printed rather than what is found.

Procedure: sift-status argv KEY: #:verbose?

Run the sift ARGV and return its exit status: 0, 1 or 2.

sift’s output goes to the terminal as it is written, because the findings are the answer and capturing them would leave the user with a status to look up. A dry run runs nothing and answers 0 after recording the command in the plan, which is what keeps a gate safe to try before it is trusted.


1.26 (maak tasks)

The task description: what a Maak file says its tasks are, read from the file rather than from the loaded module, and printed in the shapes a consumer other than a person can read.

Reading is what makes it possible. A file is a Guile module, and loading it runs whatever its top level does and needs every module it imports; an editor asks about a file somebody is halfway through writing, on a machine that may not have that project’s Guile libraries. So a task is recognised the way the language spells one – a top-level ‘define’, ‘define*’, or a name bound to a ‘lambda’ or ‘lambda*’ – the ‘#:export’ list decides which are visible, the docstring is the documentation, and the lambda list is the argument grammar.

What the file says beyond the lambda list is a function call, not new syntax: ‘task-metadata!’ declares what a task needs first, whether a listing should offer it and how it is invoked, and this module reads that call the way it reads a definition. ‘(maak maak)’ evaluates the same call and is what the runner obeys, so the two answers are compared rather than assumed: ‘contrib/test/maak-tasks.sh’ runs both readers over the same file and requires the same bytes.

Mermaid diagram, as source:

flowchart LR
  file["maak.scm"] --> forms["read-forms<br/>the file as data, never evaluated"]
  forms --> defs["a top-level define, define*,<br/>or a name bound to a lambda"]
  defs --> exports{"does the module<br/>declare #:export?"}
  exports -- "yes, and the name is in it" --> task
  exports -- "yes, and the name is not" --> helper["a helper, not a task"]
  exports -- "no" --> task
  forms --> metadata["metadata-plist<br/>the task-metadata! calls"]
  metadata --> task["static-tasks<br/>name, docstring, lambda list,<br/>dependencies, hidden flag"]
  task --> listing["maak: the task listing"]
  task --> plan["maak --dry-run: the plan"]
  task --> callgraph["static-call-graph<br/>which task calls which"]

1.26.1 Overview

1.26.2 Macros

Macro: argument-default x

Undocumented macro.

Macro: argument-doc x

Undocumented macro.

Macro: argument-has-default? x

Undocumented macro.

Macro: argument-keyword x

Undocumented macro.

Macro: argument-kind x

Undocumented macro.

Macro: argument-name x

Undocumented macro.

Macro: argument? x

Undocumented macro.

Macro: make-argument x

Undocumented macro.

Macro: make-task-description x

Undocumented macro.

Macro: task-description-arguments x

Undocumented macro.

Macro: task-description-depends x

Undocumented macro.

Macro: task-description-doc x

Undocumented macro.

Macro: task-description-example x

Undocumented macro.

Macro: task-description-hidden? x

Undocumented macro.

Macro: task-description-line x

Undocumented macro.

Macro: task-description-name x

Undocumented macro.

Macro: task-description? x

Undocumented macro.

1.26.3 Procedures

Procedure: argument-docs doc

Return the argument prose DOC carries, as (NAME . PROSE) pairs, in order.

The section is introduced by a line reading ‘Args:’ and runs to a blank line or the end of the docstring; see the note above for the shape of an entry.

Procedure: argument-signature found-argument

Return the command-line spelling of FOUND-ARGUMENT.

Procedure: json-array items

Undocumented procedure.

Procedure: json-object pairs

Undocumented procedure.

Procedure: json-string text

Undocumented procedure.

Procedure: maak-file-in dir

Return the path of the maak.scm in DIRECTORY or its parents, or #f.

Procedure: read-forms path

Return the top-level forms of PATH, in file order.

The file is read, not evaluated. A file that cannot be read to the end is an error rather than the tasks before the mistake: maak would refuse to load it too, and the short list would then overwrite a good one wherever it is written out, which is the one thing a stale edition is good for.

Procedure: static-call-graph path

Return the calls between the tasks PATH defines, as an alist.

Each entry is ‘(TASK . (CALLEE ...))’, in the file’s task order, and a callee is another task the file defines. Only calls written in the file are seen: a call built by ‘apply’, passed as a procedure or produced by a macro is not. A task that calls itself is kept, because recursion is a real edge; the page that renders the graph says the reading is static.

Procedure: static-tasks path

Return the tasks PATH defines, in file order, as <task-description>s.

When the module declares exports, only those are described; a module that exports nothing describes every procedure it defines, which is the rule the runner applies to the loaded module (see the Tasks page, docs/tasks.org).

A hidden task is described too: it is left out of what a listing prints, but naming it is still how it is run. A name defined more than once is described where its last definition stands, which is the one maak binds.

Procedure: task-names-text tasks

Return the names of TASKS, one per line, in file order.

Procedure: task-preview-text task

Return the description of TASK, as a picker’s preview pane shows it.

Procedure: task-words-text task

Return TASK’s arguments, one tab separated line each, as a picker reads them.

The line is the kind, the name, the default, whether there is one and the prose the docstring gives the argument, so a picker can prompt with the same words an editor’s own prompt uses without parsing JSON.

Procedure: tasks-fzf-text tasks

Return TASKS as name, signature and first docstring line, one per line.

Procedure: tasks-json tasks path

Return TASKS as one JSON object, naming the file they were read from.

The object is versioned: ‘version’ is 1 for this shape, so a consumer can tell a description it understands from one written after it.

Procedure: zed-tasks-json tasks OPT: executable

Return TASKS as the .zed/tasks.json Zed reads.

Zed has no discovery hook: it reads a static tasks file, so this is written by ‘maak-tasks –zed’, and kept current by ‘maak-zed watch’, which is the last entry in the list. EXECUTABLE is the command a generated task runs.


1.27 (maak veritas)

Veritas is the test framework this project and its siblings are written with, and every one of their Maak files spells the same invocation out by hand: four environment variables the runner reads, the library and the test tree on the load path, and one expression that exits with the runner’s status.

This module is that invocation, in the two shapes a Maak file needs it: the argv ‘run’ takes directly, and the same words with the expression quoted for ‘manifest-shell’ and ‘time-machine-manifest-shell’, which join their arguments into one shell line. Getting that difference wrong is the quiet bug the quoting is for: an expression with spaces in it becomes three arguments, and guile reports a syntax error instead of running a suite.

Nothing here is specific to this repository’s suite: MODULE, TYPE and TOP-DIR are the runner’s own vocabulary, so a project with integration specs beside its unit specs passes a type of integration.

1.27.1 Overview

1.27.2 Procedures

Procedure: veritas-env KEY: #:module #:top-dir #:type #:benchmarks?

Return the VERITAS_* assignments the runner reads, as NAME=VALUE strings.

The suite is located by MODULE, the module the runner loads, TOP-DIR, where the specs live, and TYPE, which directory under TOP-DIR. BENCHMARKS? turns the benchmark run on. They are strings because ‘run’ hands its ‘#:env’ straight to ‘env’, so a value with a space in it stays one value.

(veritas-env)
⇒ ("VERITAS_TEST_MODULE=veritas" "VERITAS_TEST_TOP_DIR=test" ...)
Procedure: veritas-shell-command KEY: #:guile #:load-paths #:expression

Return the same words with EXPRESSION quoted for a shell.

‘manifest-shell’ and ‘time-machine-manifest-shell’ join their words into one command line, so the expression, which has spaces and parentheses, has to survive as one word. Use ‘veritas-test-argv’ with ‘run’, which starts guile without a shell and needs no quoting.

Procedure: veritas-test KEY: #:verbose? #:guile #:load-paths #:module #:top-dir #:type #:benchmarks? #:expression

Run the Veritas suite and fail the task when it does not pass.

This is the one line a Maak file needs for its test task:

(define (test)
  (veritas-test))

The status the runner answers with is the exit status guile leaves, so a red suite is a failed task with no shell fallback to remember.

Procedure: veritas-test-argv KEY: #:guile #:load-paths #:expression

Return the argv that runs the Veritas suite, without running it.

LOAD-PATHS are the directories guile searches before anything installed, which is what makes the checkout’s own library and specs the ones under test. GUILE names the interpreter, so a task can pin one.

The expression is one argv element, unquoted: this list is what ‘run’ starts directly. For the words a manifest shell re-reads, use ‘veritas-shell-command’, which is this list with the expression quoted.

(veritas-test-argv)
⇒ ("guile" "-L" "./src" "-L" "./test" "-c" veritas-expression)

1.27.3 Variables

Variable: veritas-expression
"(exit ((@@ (veritas runner) run-tests)))"

1.28 (maak version)

The single place the program’s version is written by hand, together with the handful of facts the CLI reports about itself. ‘–version’ prints it, the Nix derivation reads this file while it evaluates, and the copies that cannot read Scheme – the RPM spec, the Arch recipe, the Homebrew formula, the manual page and the installation page – are rewritten from it by the ‘sync-version’ task, which reads this file rather than the library it happens to be running under. A release is therefore one edit, not a search of the tree, and the suite fails while any copy disagrees with this one.

1.28.1 Overview

1.28.2 Procedures

Procedure: maak-version-string

Return the one-line version banner printed by ‘maak –version’.

Procedure: print-version OPT: port

Print the version banner, and the program’s homepage, to PORT.

1.28.3 Variables

Variable: maak-homepage
"https://github.com/jjba23/maak"
Variable: maak-license
"MIT"
Variable: maak-version
"1.1.2"

1.29 (maak watch)

‘maak –watch TASK’ re-runs the task when the tree changes. The repository’s own ‘dev’ and ‘hot-reload’ tasks were the hand-rolled version of this, and needed watchexec; this is the same idea in maak itself, with no dependency beyond a filesystem and a clock.

Watching is a snapshot comparison: the tree is described as a sorted list of file, modification time and size, and a change is a different list. A git checkout is asked for the files it tracks and for the untracked ones it does not ignore (‘git ls-files –cached –others –exclude-standard’), which is the set a person means by "the tree"; a directory that is not a checkout is walked, skipping the directories that are never a source file. Neither answer follows a symbolic link, so a loop in the tree cannot hang the watch.

The snapshot is taken after each run rather than before the next poll, so a task that writes into the tree – a build directory, a log, a generated file – does not start itself again. A change that lands while a run is in progress is therefore part of that run’s baseline; the trade is deliberate, because the alternative is a task that rebuilds forever.

1.29.1 Overview

  • directory? — An undocumented procedure.
  • walk-files — Return every regular file under ROOT, skipping the ignored directories.
  • watch-changed? — Return #t when the two snapshots describe a different tree.
  • watch-files — Return the files a watch of ROOT follows, as absolute paths.
  • watch-interval — Return the watch interval in seconds.
  • watch-relist — Re-run a task listing now, and again whenever ROOT changes.
  • watch-snapshot — Return FILES as a sorted list of ‘(PATH MTIME .
  • watch-tree — Run THUNK now, then again whenever the tree under ROOT changes.

1.29.2 Procedures

Procedure: directory? path

Undocumented procedure.

Procedure: walk-files root KEY: #:extensions #:exclude

Return every regular file under ROOT, skipping the ignored directories.

EXTENSIONS, when a list, keeps only the names ending in one of them, and EXCLUDE names directories to prune at any depth. The two deliverables a watch and a lint both need – what the tree is, and which directories are never a source file – are decided here and nowhere else, so ‘(maak sift)’ asks for this walk rather than writing a second one with its own list.

Procedure: watch-changed? before after

Return #t when the two snapshots describe a different tree.

Procedure: watch-files root

Return the files a watch of ROOT follows, as absolute paths.

A git checkout is read with ‘git ls-files’; anything else is walked. A git command that fails – a repository whose index is locked, say – falls back to the walk rather than watching nothing.

Procedure: watch-interval

Return the watch interval in seconds.

‘MAAK_WATCH_INTERVAL’ sets it; the default is one second. A value that is not a positive number is a maak error rather than a silent fallback, so a typo does not turn into a watch that never notices anything.

Procedure: watch-relist KEY: #:root #:program #:arguments #:interval

Re-run a task listing now, and again whenever ROOT changes.

This is the ‘dev’ and ‘hot-reload’ task that most Maak files spell out by hand: a watch whose action is a listing, where a broken edit is reported and the watch carries on, because the next save is how it gets fixed. PROGRAM is the maak to run – a checkout’s launcher by default – and ARGUMENTS are its words, ‘–list’ unless the task wants something else.

(define (dev)
  "Watch the tree and re-list the tasks on every change."
  (watch-relist))

(define (test-watch)
  "Re-run the suite on every change, instead of re-listing."
  (watch-relist #:arguments '(("test"))))
Procedure: watch-snapshot files

Return FILES as a sorted list of ‘(PATH MTIME . SIZE)’, for comparison.

A file that disappeared between the listing and the stat is left out: it is a change, and the next snapshot will not mention it either.

Procedure: watch-tree root thunk KEY: #:interval

Run THUNK now, then again whenever the tree under ROOT changes.

INTERVAL is how often the tree is looked at, in seconds. The run happens immediately, so ‘–watch’ starts with the same run the same command would do without it; the snapshot is taken after the run, so what the task itself wrote is the baseline rather than a change. THUNK is expected to report its own failures: the watch has nowhere to return a status to, and a failing run must not stop it.