dowel documentation
The index of user-facing documents (how-to and reference) and internal documents (design, development, planning).
How-to
| 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.
Reference
| 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.
Design (background and internals)
| 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 |
Developing this repository
| 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 |
Publishing with GitHub Pages
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 site carries its own theme rather than a theme gem, so what the page looks like is readable from this repository alone.
Paths below are relative to the repository root. They are not part of the published site, so they are named rather than linked.
| Path | Contents |
|---|---|
_layouts/ |
The page frame: masthead, cover, footer |
_includes/ |
The sidebar, built from the list below |
_data/nav.yml |
The order of documents in the sidebar |
assets/ |
Styles, the mark, and the script that adds the per-page contents |
Two things are worth knowing before moving the site.
baseurlin_config.ymlis the path the site is served under (/dowel). GitHub Pages does not set it, and every link inside the documents is resolved through it. Serving the site under a domain of its own means emptying it_data/nav.ymlis the one place that repeats the document list. Its entries are checked againstdocs/in both directions bycrates/dowel-cli/tests/docs.rs
Building the site locally needs Jekyll, which is not part of the development environment; the published site is built by GitHub Pages.
Numbering convention
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.
Index
| 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 |
Document conventions
- Decisions are recorded as ADRs. To overturn a decision, mark its ADR as Superseded and add a new one; existing ADRs are never rewritten
- Open questions are collected in 99-open-questions.md. Once decided, an item moves to an ADR and is deleted from the list
- Planning and current state are kept separate: 90-roadmap.md is the plan, 91-implementation-status.md is the current state. Where they disagree, the latter wins
- When the implementation diverges from a design document, the divergence is recorded in the “Divergences from the design documents” section of 91
- User-facing documents (10 / 6x) describe what works; anything not yet implemented is marked as such in place
What is machine-checked
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 site sidebar (_data/nav.yml) |
A document was added but not listed, or an entry points at a document that is gone |
| 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.