Decision D037 · accepted
Tooling: one diaspar command, tasks as programs, scripts, the toolchain
A record of the language's design, as it stood on 2026-11-18: written for the people who build Diaspar, and kept as it was written. Its code is a sketch, not a program of the site, and an older record may show syntax that a later one changed. It names files of the language's source, which is not public yet.
Status: accepted (2026-11-18), the answers to the questions of design/tooling.md section 13, question 9 (examples in documentation as tests) is decided in D016. The design document holds the details (each command, its flags, the output); this decision records what was settled. Research: reports/Developer tooling for Diaspar.md.
Decision
- One binary, about twenty commands (design §2):
new,run,test,bench,check,build,fmt,repl,doc;add,remove,update,tree,fetch,install,publish;connect,lsp,mcp;clean,self.diaspar checkreports errors and warnings without emitting C or runningcc, with--deny-warningsfor CI.docworks in the terminal before any HTML output exists. No plugins found on thePATH, no separatelintcommand. - Tasks are programs (design §5): a task is
scripts/NAME.diaswith amain, run bydiaspar run NAMEand listed bydiaspar run --list. No task file, no:taskskey and no shell commands in the manifest; a project that wants many small tasks writes one script with subcommands.taskkeeps its meaning of a concurrent task (D035). - No fall-through: an unknown command is an error, never a script of the same name (
diaspar releaseis notdiaspar run release), so a later built-in command cannot silently take a project's name. - Scripts (design §6):
diaspar FILE.diasruns a single file, so#!/usr/bin/env diasparworks; a script may declare its dependencies inline. - The REPL starts inside the package with the lockfile's dependencies, as
iex -S mix, and serves the live protocol (D020). - The language's own development tools (
diff,tests,self,fuzz,seed,prims,ucd) move to a hidden group,diaspar dev …, now; later they become scripts of the compiler's package. The nameselfis freed fordiaspar self updateanddiaspar self info. - This repository keeps a thin
mise.toml(build,check) as its front door; the task bodies become scripts whenscopeandspawnexist (stage D, step 1b). Diaspar replaces mise for its users' tasks, not as a tool manager. - One
:diasparkey in the manifest names both the required toolchain and the language version, with no editions. When the installed toolchain does not satisfy it, the command fails with what to install; it never downloads a toolchain by itself. - A waiting period for new versions of dependencies, three days by default, once a public registry exists; changeable in configuration.
--watchrestarts the program or the tests on every command that has it; loading changed definitions into a running program is a separate flag, designed with D018.- Directories: binaries in
build/dev/andbuild/release/, tool state in.diaspar/, intermediate files and downloaded packages in a content-addressed cache of the user; not onetarget/for everything. diaspar installmay ask before installing a program, naming the effects its packages are allowed (D025); this is the one command that prompts, and without a terminal it needs--allow-effects.
Amendments: D025 gains scripts/ and the :diaspar key; D032 gains examples/ and scripts/ in a package.
Amended 2026-11-18 by design/ffi.md section 13 (decided by the FFI agent on the author's delegation; question 1 there asks the author to confirm the name): the command set gains bind, which generates a wrapper package's declarations of a C library from its headers, and --check for CI. diaspar build gains --link LIBS.
Rejected alternatives
The design document's sections list them; in short: a task file as Rake's and Mix's, or tasks in the manifest as npm's scripts; fall-through to scripts of the same name; editions as Rust's; a toolchain manager inside the tool that downloads on mismatch, as Go's toolchain lines; one build directory for everything; prompts anywhere but install.