The index of user-facing documents (how-to and reference) and internal documents (design, development, planning).
| Document | Contents |
|---|---|
| 62-getting-started.md | From installation to building, testing, and running your first project |
| 63-guides.md | Task-oriented how-tos: building, testing, configurations and feature flags, tracing provenance, cross execution, editors, the cache, CI integration |
| 61-acquisition.md | Acquiring dowel itself and switching versions (dowelup) |
A working example lives at examples/hello.
| Document | Contents |
|---|---|
| 10-manifest.md | The manifest model: the two files, the evaluation pipeline in one pass |
| 11-toml-reference.md | dowel.toml: every table and key that is read, and how it is validated |
| 12-build-reference.md | dowel.build: the complete syntax, every target/runner property, the configuration vocabulary |
| 13-semantics.md | How declared values behave: specialization, propagation and merging, planning, execution |
| 14-build-graph.md | build-graph.json: the backend-neutral build description, for running a dowel build with a tool of your own |
| 60-cli.md | The command reference: every option, output contract, exit status, machine-readable diagnostics |
| 91-implementation-status.md | What works today: the not-yet-implemented list, measurements, divergences from the design documents |
The reference includes the full design, so parts of it are not implemented yet. Unimplemented items are marked in place and listed in 91. Where the two disagree, 91 describes the current state.
| Document | Contents |
|---|---|
| 00-overview.md | Goals, non-goals, positioning against existing systems |
| 20-architecture.md | The incremental query engine, the persistent store, language-server internals |
| 30-devexp.md | The design of runners, debugger integration, editor integration |
| 40-migration.md | Migration from existing build systems (design; the commands are not implemented) |
| adr/ | Decisions and their rationale (ADRs) |
| 90-roadmap.md | Implementation order and verification plan |
| 99-open-questions.md | Open questions |
| Document | Contents |
|---|---|
| 50-development.md | The development environment (Nix / container) and conventions |
| 51-testing.md | Test-suite design: what each layer answers, and where a new test belongs |
This repository can be published as-is with GitHub Pages
(Settings → Pages → Deploy from a branch → main / / (root)).
The configuration lives in _config.yml. When published,
relative links between Markdown files resolve to HTML, and each directory’s
README becomes that directory’s index page. Documents are written with
relative links only, so they read the same on the repository and on the site
without a separate build step.
The tens digit is the subject; the ones digit distinguishes documents within a subject.
| Band | Subject |
|---|---|
0x |
Overall positioning |
1x |
The manifest language reference |
2x |
Internals |
3x |
Developer experience (runners, debuggers, editors) |
4x |
Migration from existing build systems |
5x |
Developing this repository |
6x |
User-facing documents (reference and how-to) |
9x |
Planning and current state |
99 |
Open questions |
A new document goes into an existing band when it fits; a new band is added only when a subject fits none. Numbers are never reassigned: document numbers are referenced both from Markdown links and from comments in the source code, and changing one breaks those references.
| Document | Contents |
|---|---|
| 00-overview.md | Goals, non-goals, positioning against existing systems |
| 10-manifest.md | The manifest model and the index of the language references |
| 11-toml-reference.md | dowel.toml reference: tables, keys, validation |
| 12-build-reference.md | dowel.build reference: syntax, properties, configuration vocabulary |
| 13-semantics.md | Semantics: specialization, propagation and merging, planning, execution |
| 20-architecture.md | The incremental query engine, the persistent store, language-server internals |
| 30-devexp.md | Runners, debugger integration, editor integration |
| 40-migration.md | Migration from existing build systems |
| 50-development.md | The development environment (Nix / container) and conventions |
| 51-testing.md | Test-suite design: what each layer answers, and where a new test belongs |
| 60-cli.md | The command reference, output contract, logging and debugging |
| 61-acquisition.md | Acquiring dowel itself and switching versions (dowelup) |
| 62-getting-started.md | How-to: from installation to your first build |
| 63-guides.md | Task-oriented how-to guides |
| 90-roadmap.md | Implementation order and verification plan |
| 91-implementation-status.md | Implementation status, measurements, divergences from the design documents |
| 99-open-questions.md | Open questions |
| adr/ | Decisions and their rationale |
Documentation inconsistencies break neither the build nor the tests, so they
go undetected unless checked. crates/dowel-cli/tests/docs.rs covers what can
be judged mechanically.
| Target | Failure condition |
|---|---|
| Relative links | The target does not exist |
| Documents named from sources and scripts | A document number changed while a non-link reference remained |
| The index above | A document was added but not listed, or removed while its entry remained |
| The table in adr/README.md | An ADR was added but not listed, or the reverse |
| The crate table in 91-implementation-status.md | A crate was added but not listed, or the reverse |
The correctness of the prose itself is not checked. The design is described in 51-testing.md.