Maak v1.0.0 - infinitely extensible command runner, build sys in Lisp
Maak is a command runner, and its task list is a Lisp file. You write maak.scm - a perfectly normal Guile module - and every procedure in it becomes a task you can name on the command line. There is no DSL to learn and no second language to keep in your head: the build is the program.
(define-module (maak) #:declarative? #t #:use-module (maak maak))
;; A task is a Ξ»: (define (build) ...) is (define build (lambda () ...)).
(define (build)
"Compile every page in ./pages into ./build."
(let ((out "build"))
(mkdir-p out)
(for-each (lambda (page)
(run (list "pandoc" (~ "pages/~a.md" page) "-o" (~ "~a/~a.html" out page))))
'("index" "about"))
(when (file-exists? "static/style.css")
(cp "static/style.css" (~ "~a/style.css" out)))))
;; Two programs, one pipe, and a failure that names the stage that failed.
(define (check)
"Lint every tracked page."
(run-pipeline (list (list "git" "ls-files" "pages")
(list "xargs" "markdownlint"))))
;; Its arguments arrive as the strings typed on the command line.
(define (deploy host)
"Ship ./build to HOST, replacing what is there."
(unless (file-exists? "build/index.html")
(task-error "nothing to deploy" #:hint "Run `maak build' first."))
(run (list "rsync" "-av" "--delete" "build/" (~ "~a:/srv/www/" host))))
;; Procedures are values, so tasks compose like any other function.
(define (ci host)
"Check, build and ship in one go."
(check)
(build)
(deploy host))
The loop and the conditional expand into four commands, and --plan shows each one as the argv it is - no shell to re-parse, no quote to guess at:
$ maak --plan build
maak plan
[1] build mkdir -pv build cwd: /home/me/site
[2] build pandoc pages/index.md -o build/index.html cwd: /home/me/site
[3] build pandoc pages/about.md -o build/about.html cwd: /home/me/site
[4] build cp -r -v static/style.css build/style.css cwd: /home/me/site
Why Lisp
Most build tools invent their own limited domain-specific language. Maak embraces the powerful Ξ» Lisp and the amazing Guile Scheme programming language. This also means your code is flexible, robust and reliable (+declarative) for at least the next 50 years.
- Why it matters. Tasks are real Scheme functions: composable, testable, declarative, dry-runnable, parallelisable, and reproducible.
- The entire language, not a DSL. Define functions, use lists and hash tables, write macros, import libraries. If you can write it in Guile, you can write it in a task.
- Lambdas compose. A task calls another task with a function call, and a list of tasks is a list - no subprocess, no re-parsing a file to find out what to run.
- Your editor already knows the language. Docstrings are the task list, the REPL is the development loop, and
maak --listreads likeapropos. - Guix and Nix are values too. A pin is a store path a task can decide on, not a string another tool has to interpret.
- Shell-free by default.
runtakes a program and its arguments as separate strings, so a path with a space in it stays one argument. - Errors that read like sentences.
task-errorprints one line and a hint, exits non-zero, and keeps the backtrace behind--debug.
See the full list pipelines, background jobs, -j, guix, nix, containers, niri, downloads, gettext, maven, uv, python in Features.
How tasks are found
A Maak file is read, not run, when maak answers a question about it: a top-level define, define* or a name bound to a lambda is a task, the #:export list decides which of them are visible, the docstring is the documentation and the lambda list is the argument grammar. That is what lets a listing, a plan and the call graph be answered for a file somebody is halfway through writing, on a machine that does not have its libraries.
Start with the quick start, or open the whole documentation index.
Documentation index
| Page | What it covers |
|---|---|
| Quick start | Your first Maak file: eight steps from a module to a dry run. |
| Tasks | How a function becomes a task, what exports hide, how arguments arrive. |
| The command line | Every option, the grammar of tasks and arguments, --list output. |
| Configuration | Environment variables, and the parameters behind dry-run and quiet. |
| The built-in toolkit | run, pipelines, jobs, file helpers, task-error, gettext. |
| Rust and Cargo | Cargo and rustup helpers, the structured command line, metadata as a value, artefact paths. |
| Python, uv and pyproject | uv helpers, the version and name a release reads, and the four CI checks. |
| Frontend projects | npm, pnpm and yarn behind one set of procedures, and the package.json a release reads. |
| Task files in JSON, TOML and YAML | A task list without the language: the schema, the formats, their limits. |
| Maven, Gradle and the JVM | The Maven lifecycle and Gradle tasks as argv, wrapper detection, and the JVM reports. |
| Emacs Lisp packages | Byte-compiling, ERT and checkdoc in batch, and the packaging conventions. |
| Guix, Nix and reproducibility | The helpers that build the command line, and the ones that return values. |
| On Stability | What the versions mean, and the promises of stability |
| Why maak, and why Lisp | What Make cannot do, and the table of Make flags that did carry over. |
| Editors, shells and the REPL | maak.el and the seven integrations, the shell completions, the REPL workflow. |
| Maak files and AI assistants | What to ask maak instead of guessing, the rules a Maak file is reviewed against, and a block for a projectβs agents file. |
The manual page is installed with the program (man maak, or maak man in a checkout), the technical Guile API documentation is published at https://jointhefreeworld.org/api-docs/maak/index.html, and every release is recorded in NEWS.org.
Editors and assistants
Emacs is the first-class citizen. maak.el is maakβs canonical front end: pick a task, prompt for its arguments, watch the output and jump to the definition, from inside Emacs, from the same maak.scm the command line runs.
The other editors are also served. Neovim, Vim, VS Code, Helix, IntelliJ, Zed and Sublime Text each have an integration in contrib/. Editors, shells and the REPL has the details, and every integration has a README of its own.
An assistant is served the same way: contrib/ai ships a skill file - the Maak fileβs rules, its vocabulary and the loop that checks the work, as one context file - and Maak files and AI assistants says what to ask maak instead of guessing.
Installing and developing
Guix, Nix, Homebrew, the container image, the RPM and the Debian package are all in Installing maak. From a checkout, the launcher runs this treeβs own sources:
guix shell -m manifest.scm -- ./scripts/maak --list
- Issues and development: the GitHub repository; the backlog and Kanban boards live at https://lucidplan.jointhefreeworld.org/tickets/maak.
- Chat, support, discussion, announcements: the maak Zulip community.
Bug reports, patches, the AI policy and the code of conduct are in Community, contributing and conduct.
If you like this work, you can buy me a cup of coffee β so I can keep going with a lot of motivation.
License
maak, and all of its source code, build files and documentation - this document included - are free software, licensed under the MIT License (MIT). https://opensource.org/license/mit
The full text is in the LICENSE file shipped with the source. In short: use it, study it, change it, share it - and keep the copyright notice and the permission notice with the copies you pass on.
Happy hacking! β¨
maak runs the build, release and site automation of many projects, see a list in Who uses maak. Using maak in your project? Send a link and it can be listed there.
Comments
Comments
No comments yet. Start the discussion.