Maak v1.0.0 – 无限可扩展的命令运行器,Lisp 编写的构建系统
摘要
Maak v1.0.0 发布,这是一个无限可扩展的命令运行器与构建系统,其任务列表本身就是一个 Guile Scheme 模块——每个过程都直接成为 CLI 任务,无需学习任何 DSL,参数传递不依赖 shell,支持试运行(dry-run)规划,并提供可组合、可测试的任务。
查看缓存全文
缓存时间: 2026/11/22 03:21
jjba23/maak
来源:https://github.com/jjba23/maak
#+title: maak:无限可扩展的命令运行器 #+author: Josep Bigorra #+email: [email protected] #+options: toc:nil num:nil
[[https://jointhefreeworld.org/ggg/dist/scheme-guile.svg]] [[https://jointhefreeworld.org/ggg/dist/gnu-guix.svg]] [[https://jointhefreeworld.org/ggg/dist/maak.svg]] [[https://jointhefreeworld.org/ggg/dist/license-mit.svg]] [[https://jointhefreeworld.org/ggg/dist/jointhefreeworld-org.svg]]
#+attr_html: :width 160 :alt maak logo [[file:logo.svg]]
- 每个任务都是一个 λ
maak 是一个命令运行器,它的任务列表就是一个 Lisp 文件。你编写 =maak.scm= —— 一个完全正常的 Guile 模块 —— 其中的每个过程都会成为一个可以在命令行上命名的任务。不需要学习任何 DSL,也不需要在脑子里记第二门语言:构建就是程序。
#+begin_src scheme (define-module (maak) #:declarative? #t #:use-module (maak maak))
;; 任务就是一个 λ:(define (build) …) 等价于 (define build (lambda () …))。
(define (build)
“将 ./pages 中的每个页面编译到 ./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)))))
;; 两个程序,一条管道,失败时会指明是哪一段出错。 (define (check) “对每个被跟踪的页面进行 lint。” (run-pipeline (list (list “git” “ls-files” “pages”) (list “xargs” “markdownlint”))))
;; 参数以命令行上输入的字符串形式到达。 (define (deploy host) “将 ./build 发布到 HOST,替换其上的内容。” (unless (file-exists? “build/index.html”) (task-error “没有可部署的内容” #:hint “请先运行 `maak build’。”)) (run (list “rsync” “-av” “–delete” “build/” (~ “~a:/srv/www/” host))))
;; 过程是值,因此任务可以像普通函数一样组合。 (define (ci host) “一次性完成检查、构建和发布。” (check) (build) (deploy host)) #+end_src
循环和条件会展开为四条命令,=–plan= 会把每条命令以它本来的 argv 形式展示出来——没有 shell 去重新解析,没有引号需要猜测:
#+begin_src shell $ 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 #+end_src
#+begin_quote 大多数构建工具都会发明自己有限的领域特定语言。Maak 则拥抱强大的 λ Lisp 和出色的 Guile Scheme 编程语言。
/这也意味着你的代码至少在未来 50 年里都是灵活、健壮、可靠(+声明式)的。/ #+end_quote
- 为什么这很重要。 任务是真正的 Scheme 函数:可组合、可测试、可声明、可试运行、可并行、可复现。
- 一路 Lisp 到底
- 整个语言,而不是 DSL。 定义函数、使用列表和哈希表、编写宏、导入库。只要能用 Guile 写出来,就能写成任务。
- Lambda 可以组合。 任务通过函数调用调用另一个任务,任务列表就是一个列表——没有子进程,没有重新解析文件来找出该运行什么。
- 你的编辑器已经懂这门语言。 文档字符串就是任务列表,REPL 就是开发循环,=maak –list= 读起来就像 =apropos=。
- Guix 和 Nix 也是值。 一个 pin 是任务可以决定的存储路径,而不是另一个工具必须解释的字符串。
- 默认无 shell。
run接受一个程序及其参数作为独立的字符串,因此包含空格的路径仍然是一个参数。 - 读起来像句子的错误。
task-error打印一行信息和一条提示,以非零状态退出,并把回溯藏在–debug之后。
完整的流水线、后台任务、= -j=、guix、nix、容器、niri、下载、gettext、maven、uv、python 列表见 [[file:docs/features.org][Features]]。
** 函数如何成为任务
当 maak 要回答关于一个 Maak 文件的问题时,该文件是被读取而非执行的:顶层的 define、define* 或绑定到 lambda 的名字就是一个任务,#:export 列表决定其中哪些是可见的,文档字符串就是文档,lambda 列表就是参数语法。正因如此,对于一个别人写到一半的文件,即使在没有其依赖库的机器上,也能给出列表、计划和调用图。
#+attr_html: :width 720 :alt 将 maak.scm 文件从数据变成任务描述,并在此之上构建视图 [[file:resources/diagrams/task-description.svg]]
- 看它运行
#+attr_html: :width 800 :alt 终端中的 maak –plan deploy [[file:resources/maak-demo.gif]]
- 文档
从快速开始入手,或打开完整的 [[file:docs/index.org][文档索引]]。
| 页面 | 涵盖内容 | |——+––––––––| | [[file:docs/quick-start.org][快速开始]] | 你的第一个 Maak 文件:从模块到试运行的八个步骤。 | | [[file:docs/tasks.org][任务]] | 函数如何成为任务,导出隐藏了什么,参数如何到达。 | | [[file:docs/cli.org][命令行]] | 每个选项、任务和参数的语法、=–list= 的输出。 | | [[file:docs/configuration.org][配置]] | 环境变量,以及试运行和静默模式背后的参数。 | | [[file:docs/builtins.org][内置工具包]] | =run=、流水线、任务、文件辅助函数、=task-error=、gettext。 | | [[file:docs/rust-and-cargo.org][Rust 与 Cargo]] | Cargo 和 rustup 辅助函数、结构化命令行、作为值的元数据、产物路径。 | | [[file:docs/python.org][Python、uv 与 pyproject]] | uv 辅助函数、发布读取的版本与名称、以及四项 CI 检查。 | | [[file:docs/frontend.org][前端项目]] | npm、pnpm 和 yarn 统一在一组过程之后,以及发布读取的 package.json。 | | [[file:docs/task-files.org][JSON、TOML 和 YAML 中的任务文件]] | 不用语言的任务列表:模式、格式及其局限。 | | [[file:docs/maven-and-gradle.org][Maven、Gradle 与 JVM]] | Maven 生命周期和 Gradle 任务作为 argv、wrapper 检测,以及 JVM 报告。 | | [[file:docs/emacs-lisp.org][Emacs Lisp 包]] | 字节编译、批处理模式下的 ERT 和 checkdoc,以及打包惯例。 | | [[file:docs/guix-and-nix.org][Guix、Nix 与可复现性]] | 构建命令行的辅助函数,以及返回值的那些。 | | [[file:docs/stability.org][关于稳定性]] | 版本号的含义,以及稳定性承诺。 | | [[file:docs/why-maak.org][为什么是 maak,为什么是 Lisp]] | Make 做不到什么,以及得以沿用的 Make 标志一览表。 | | [[file:docs/editors.org][编辑器、shell 与 REPL]] | maak.el 和七种集成、shell 补全、REPL 工作流。 | | [[file:docs/ai.org][Maak 文件与 AI 助手]] | 该问 maak 什么而不是靠猜、Maak 文件被审查所依据的规则,以及可放入项目 agents 文件的一段内容。 |
手册页随程序一起安装(man maak,或在检出目录中使用 maak man),技术性的 Guile API 文档发布在 https://jointhefreeworld.org/api-docs/maak/index.html,每个版本都记录在 [[file:NEWS.org][NEWS.org]] 中。
- 编辑器支持
Emacs 是一等公民。[[https://github.com/jjba23/maak.el][maak.el]] 是 maak 的正统前端:在 Emacs 里选择任务、提示输入参数、查看输出并跳转到定义——用的就是命令行所运行的同一个 =maak.scm=。
其他编辑器同样得到支持。Neovim、Vim、VS Code、Helix、IntelliJ、Zed 和 Sublime Text 各自在 [[file:contrib/README.org][contrib/]] 中都有集成。
[[file:docs/editors.org][编辑器、shell 与 REPL]] 有详细说明,每个集成都有自己的 README。
AI 助手也以同样方式得到支持:[[file:contrib/ai/README.org][contrib/ai]] 提供一个 skill 文件——Maak 文件的规则、它的词汇表以及检查工作的循环,合为一个上下文文件——而 [[file:docs/ai.org][Maak 文件与 AI 助手]] 说明该问 maak 什么而不是靠猜。
- 安装
Guix、Nix、Homebrew、容器镜像、RPM 和 Debian 包都在 [[file:docs/installation.org][安装 maak]] 中。从检出目录运行时,启动器会使用本目录自身的源码:
#+begin_src shell guix shell -m manifest.scm – ./scripts/maak –list #+end_src
- 社区与支持
- Issue 与开发: [[https://github.com/jjba23/maak][GitHub 仓库]];待办清单和看板位于 https://lucidplan.jointhefreeworld.org/tickets/maak。
- 聊天、支持、讨论、公告: [[https://jointhefreeworld.zulipchat.com/#narrow/channel/632494-maak][maak Zulip 社区]]。
Bug 报告、补丁、AI 政策和行为准则见 [[file:docs/community.org][社区、贡献与行为准则]]。如果你喜欢这项工作,可以[[https://bmc.link/jjbigorra][请我喝杯咖啡 ☕]],让我更有动力继续做下去。
- 许可证
maak 及其全部源代码、构建文件和文档——包括本文档——均为自由软件,采用 MIT 许可证(MIT)授权。
https://opensource.org/license/mit
全文包含在随源码一起分发的 =LICENSE= 文件中。
简而言之:使用它、研究它、修改它、分享它——并在你传递出去的副本中保留版权声明和许可声明。
Happy hacking!✨
- 谁在使用 maak
maak 运行着许多项目的构建、发布和站点自动化,完整列表见 [[file:docs/who-uses-maak.org][谁在使用 maak]]。
在你的项目中使用了 maak?发一个链接过来,它就可以列在那里。
相似文章
Maak.el:Emacs中的Lisp机命令运行器,具备无限扩展性与Scheme支持
Maak.el是一个Emacs Lisp工具,作为Lisp机的命令运行器,提供无限扩展性和Scheme支持。
热接线Lisp机器
一位开发者分享了他们使用Emacs和Org-mode构建零依赖静态网站生成器的经验,讨论了现有工具(如org-publish)的局限性,以及他们创建发布方案以保留工作流程的过程。
@msimoni:我一天内创建了这个,它有点像拼凑的语言,但确实有一些有趣的想法和结果:Idle…
一位开发者创建了 Idle,这是一个用于 WebAssembly GC 的静态类型、低级 Lisp,具有 O(1) 方法查找和从 Wasm 模块加载宏等有趣功能。
Rhombus v1.0: 一种带有常规语法的Racket风格语言
Rhombus v1.0,一种基于Racket构建的、具有常规语法和强大宏功能的新型可扩展编程语言,已发布。
@RoundtableSpace: 一位开发者在发布15天后将Grok Bot 0.18重构为可读的TypeScript,并将其转化为一个shell,该shell r…
一位开发者将Grok Bot 0.18重构为可读的TypeScript,并创建了一个shell,该shell通过Claude Code和Codex等AI工具路由任务,支持本地执行和插件。