Skip to the content
Diaspar

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 check reports errors and warnings without emitting C or running cc, with --deny-warnings for CI. doc works in the terminal before any HTML output exists. No plugins found on the PATH, no separate lint command.
  • Tasks are programs (design §5): a task is scripts/NAME.dias with a main, run by diaspar run NAME and listed by diaspar run --list. No task file, no :tasks key and no shell commands in the manifest; a project that wants many small tasks writes one script with subcommands. task keeps its meaning of a concurrent task (D035).
  • No fall-through: an unknown command is an error, never a script of the same name (diaspar release is not diaspar run release), so a later built-in command cannot silently take a project's name.
  • Scripts (design §6): diaspar FILE.dias runs a single file, so #!/usr/bin/env diaspar works; 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 name self is freed for diaspar self update and diaspar self info.
  • This repository keeps a thin mise.toml (build, check) as its front door; the task bodies become scripts when scope and spawn exist (stage D, step 1b). Diaspar replaces mise for its users' tasks, not as a tool manager.
  • One :diaspar key 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.
  • --watch restarts 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/ and build/release/, tool state in .diaspar/, intermediate files and downloaded packages in a content-addressed cache of the user; not one target/ for everything.
  • diaspar install may 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.