maak

Instead of learning a limited DSL, you can leverage your existing Lisp skills to define tasks, manage data, and automate your workflows with ease. Define functions, manipulate lists, use conditional, create macros—the entire language is at your disposal.

You can also easily call external shell commands and integrate with your existing scripts and tools.

All you will need to do to use Maak is to write a file (by default ./maak.scm) where you define your Maak file module and import Maak library:

(define-module (maak)
  #:declarative? #t
  #:use-module (maak maak))

Any thunk (no-argument function) you define in this file becomes a runnable task. If no task is passed via command-line, Maak will run the default task.

Tasks can:

• Run shell commands with the $ helper.
• Print logs with log-info.
• Call other Maak tasks.
• Use any Guile Scheme function you define (or import from a library).
• Some syntactic sugar for working with Guix dev shells manifest-shell and program-shell

⚠️ Beware not to use names for tasks that conflict with names of built-in Scheme functions as this can cause some problems. For example, avoid calling something format or display, choose something else instead.

You can extend Maak by defining new tasks — just like writing functions in Scheme.

Here’s an example:

(define (hello)
  "Say hello from Maak!"
  (display "Hello from Maak!")
  (display (format #f "~a + ~a = ~a" 3 4 (+ 3 4))))

You can now run it:

More advanced examples here:

;; Format Scheme source code files according to the Guix style guide.
(define (fmt)
  (log-info "Format Scheme files using Guix Style")
  ($ '("find . -maxdepth 8 -name '*.scm'"
       "-type f -exec guix style -f {} \\;")
     #:verbose? #t))

;; Display program help screen.
(define (help)
  ($ '("guix shell -f guix.scm -- maak --help")))

;; By default (no task given) run help.
(define (default)
  ($ '("maak --list"))

;; Do some quick math
(define (arithmetics)
  (fmt) ;; call another task first
  (let* ((entries '(1 3 5 7 9))
         (arithmetics (lambda(x) (* x x 3)))
         (some-data (map arithmetics entries)))
    (log-info "Running default task")
    (log-info "Performed some fun arithmetics:\nResult: ~a" some-data)))

Have you ever found Makefile to be repetitive, lacking expressiveness and having a weird, limited syntax and unexpected arcane behavior?

No fear, Maak is here. With the full power of Lisp directly in your command runner/control plane, easily define functions, data, lists, loop through them, macros, etc. Maak replaces the arcane syntax of Make with the power and elegance of a full-featured functional programming language: GNU Guile Scheme λ.

Maak replaces Make’s runes and mystery with the power and clarity of GNU Guile Scheme λ.

Find below a list of some projects using maak for their automation. Reminder: maak.scm is the default name of a maak file, but you can choose to use a different one.

• Heks GNU/Linux - The witches' GNU/Linux: modular, flexible, reproducible, powered by Lisp and Fedora / Debian + GNOME / Niri
• LucidPlan - Project management (CMS) for everyone - free and open
• Veritas - Unit, Integration and Black Box testing framework powered by Lisp (Guile Scheme)
• Mutastructura - Relational Schema and Database Migrations powered by Lisp (Guile Scheme)
• GGG (Guile Glyph Generator) - Create SVG images, handy useful glyphs, org/markdown badges.
• Hygguile - UI framework for cozy and professional user-interfaces for everyone with the power of Scheme.
• SSS (Supreme Sexp System) - SSS is a Lisp machine adventure, where the hacking culture is celebrated. This custom GNU + Linux setup enhances customization to infinity, encourages the hacking spirit.

The project's automation is done using Maak itself, check the maak.scm file.

Also, find the technical Guile Scheme API documentation of Maak here:

https://jointhefreeworld.org/api-docs/maak/API.html

You can see the program's help by invoking ggg with the --help argument or looking at resources/help.txt.

maak is officially distributed via:

• Guix package manager
• Podman/Docker images

That being said, feel free to use it as you wish, within the terms of the GNU General Public License v3 or newer.

guix package --install-from-file=./guix.scm

guix time-machine --channels=channels.scm -- shell -f guix.scm

guix time-machine --channels=channels.scm -- shell -f guix.scm -- maak --help

guix time-machine --channels=channels.scm -- \
     shell -m manifest.scm -- guile -L ./src -c '((@(maak main) main))' \
     --list

 docker container run -v /home/joe:/home/joe \
     docker.io/jjba23/maak:latest maak -f /home/joe/hacking/maak/maak.scm --list

Maak offers a simple but powerful shell completion. When you are in a directory with maak.scm files, you can type maak followed by space, then hit TAB and you will see the names of maak tasks appear. This is done by reading the current file and extracting task names from it with some awk magic.

See the script at scripts/maak-completion.bash . You should "source" this script if you want these completions to always be available for you.

Load maak Bash shell auto-completions with :

#!/usr/bin/env bash
# Integrate Guix-managed Bash & Maak
maak_bin_install_dir=$(which maak)
maak_install_dir=$(realpath "${maak_bin_install_dir}")
maak_bin=$(dirname "${maak_install_dir}")
maak_store=$(dirname "${maak_bin}")
maak_completions="${maak_store}/share/scripts/maak-completion.bash"

# Load Maak auto-completions
if [[ -f "${maak_completions}" ]]; then
  # echo "Found completions: ${maak_completions}"
  # echo "Loading Maak completions..."
  source "${maak_completions}" || true
fi

Maak and all of its source code are free software, licensed under the GNU General Public License v3 (or newer at your convenience).

https://www.gnu.org/licenses/gpl-3.0.html

The documentation and examples, including this document, which are provided with Maak, are all licensed under the GNU Free Documentation License v1.3 (or newer at your convenience).

https://www.gnu.org/licenses/fdl-1.3.html

A REPL (Read-Eval-Print Loop) is an interactive environment, which can be used connected to your console, running application, language compiler and more, which gives you superpowers as an engineer 🦸🏼.

Lisp dialects, more specifically Guile Scheme, have great support for this. I personally of course like to do this with Guix, Emacs, (Arei/Ares + sesman) you can get an ultimate extensible powerful editor experience, miles ahead of traditional IDEs 🐂 .

It fundamentally changes the development workflow by eliminating the slow edit, save, compile, run cycle. Instead of writing a whole program and then running it to see what happens, you get a fast, conversational workflow. What does this mean for in practice?

• Incremental Development: Write, test, inspect, evaluate one function or even one line at a time. Get immediate feedback without running the entire app.
• Powerful Debugging: Forget adding print statements and restarting. You can pause, inspect objects, change values, and even redefine a broken function on the fly to test a fix in any environment (yes even in production, while running).
• Fast Prototyping & Learning: Instantly experiment with a new library or API. Just load it and start calling functions to see how they work, which is much faster than only reading documentation.

When integrated into your code editor, you can execute any piece of code (a line, a selection, or a file) with a keyboard shortcut and see the result instantly, creating a seamless and powerful development experience.

This project adheres to the jointhefreeworld code of conduct. Find it here:

https://jointhefreeworld.org/blog/articles/personal/jointhefreeworld-code-of-conduct/index.html

In summary, we foster an inclusive, respectful, and cooperative environment for all contributors and users of this free software project. Inspired by the ideals of the GNU Project, we strive to uphold freedom, equality, and community as guiding principles. We believe that collaboration in a community of mutual respect is essential to creating excellent free software.

The project logo of maak is courtesy of Google Gemini.

Contributing to free software is a uniquely beautiful act because it embodies principles of generosity, collaboration, and empowerment.

We welcome everyone to feel invited to the Maak Project, and encourage active contribution in all forms, to improve it and/or suggest improvements, brainstorm with me, make it more modular/flexible, etc, feel free to contact me <jjbigorra@gmail.com> to chat, discuss or report feedback.

Find here the Backlog and Kanban boards for Maak: https://lucidplan.jointhefreeworld.org/tickets/maak

Maak embodies the spirit of GNU: simplicity, freedom, and curiosity. It’s both a tool and a playground for learning Lisp-based automation.

As you grow comfortable, extend Maak — define your own DSLs, orchestrate builds, or automate your projects in elegant Scheme.

Happy hacking! ✨

Maak was designed with a few simple but powerful ideas in mind — ideas rooted in the GNU tradition and Lisp philosophy.

In systems where maak is already installed, a good way to compile from source and test all program functionalities is a pure shell:

guix shell --pure -f guix.scm bash coreutils util-linux-with-udev guile -- maak test-all-maak-functions

guix shell --pure -f guix.scm bash coreutils util-linux-with-udev guile -- maak --list