# Configuration
RSConstruct is configured via an `rsconstruct.toml` file in the project root.
An optional `rsconstruct.local.toml` overlay, when present, is merged over the
main file at load time — see [Local overlay](#local-overlay-rsconstructlocaltoml).
An optional user-level file can set `[build]` defaults underneath both and
choose the columns the CLI's tables show — see
[User config](#user-config-configrsconstructconfigtoml).
## Full reference
```toml
[build]
parallel = 1 # Number of parallel jobs (1 = sequential, 0 = auto-detect CPU cores)
# Also settable via RSCONSTRUCT_THREADS env var (CLI -j takes precedence)
batch_size = 0 # Max files per batch for batch-capable processors (0 = no limit)
output_dir = "out" # Global output directory prefix for generator processors
# Declare processors by adding [processor.TYPE.NAME] sections.
# Only declared processors run — no processors are enabled by default.
# Use `rsconstruct smart auto` to auto-detect and add relevant processors.
[processor.checker.ruff]
# args = []
[processor.checker.pylint]
# args = ["--disable=C0114"]
[processor.generator.cc_single_file]
# cc = "gcc"
# cflags = ["-Wall", "-O2"]
[vars]
my_excludes = ["/vendor/", "/third_party/"] # Define variables for reuse with ${var_name}
[cache]
restore_method = "auto" # auto (default: copy in CI, hardlink otherwise), hardlink, or copy
compression = false # Compress cached objects with zstd (requires restore_method = "copy")
remote = "s3://my-bucket/rsconstruct-cache" # Optional: remote cache URL
remote_push = true # Push local builds to remote (default: true)
remote_pull = true # Pull from remote cache on cache miss (default: true)
mtime_check = true # Use mtime pre-check to skip unchanged file checksums (default: true)
webcache_ttl_secs = 604800 # How long a fetched HTTP response stays fresh (default: 7 days)
[analyzer]
auto_detect = true
enabled = ["cpp", "python"]
[graph]
viewer = "google-chrome" # Command to open graph files (default: platform-specific)
[completions]
shells = ["bash"]
[dependencies]
npm = ["eslint", "prettier"] # Node.js packages, into .rsconstruct/tools
gem = ["mdl"] # Ruby gems, into .rsconstruct/tools
cargo = ["cargo-deny"] # Crates from crates.io, into .rsconstruct/tools
system = ["pandoc", "graphviz"] # System packages, onto the machine
[pages]
dir = "out/web" # Directory published to GitHub Pages (omit the section entirely for non-Pages repos)
[command.symlink_install]
sources = ["dotfiles"] # Folders whose files `rsconstruct symlink-install` links...
targets = ["~/"] # ...into these folders, pairwise (same length as sources)
```
Per-processor configuration is documented on each processor's page under [Processors](processors.md).
## Processor instances
Processors are declared by adding a `[processor.TYPE.NAME]` section to `rsconstruct.toml`. An empty section enables the processor with default settings:
```toml
[processor.checker.pylint]
```
Customize with config fields:
```toml
[processor.checker.pylint]
args = ["--disable=C0114,C0116"]
src_dirs = ["src"]
```
Remove the section to disable the processor.
### Multiple instances
Run the same processor multiple times with different configurations by adding named sub-sections:
```toml
[processor.checker.pylint.core]
src_dirs = ["src/core"]
args = ["--disable=C0114"]
[processor.checker.pylint.tests]
src_dirs = ["tests"]
args = ["--disable=C0114,C0116"]
```
Each instance runs independently with its own config and cache.
You cannot mix single-instance and multi-instance formats for the same processor — use either `[processor.checker.pylint]` or `[processor.checker.pylint.NAME]`, not both.
#### Processor names
A processor is named by its full path, `processor.<type>.<name>`, the same path its source file has (`src/processor/checker/ruff.rs` is `processor.checker.ruff`). The type is one of `checker`, `generator`, `explicit` and `mass_generator`; the name is unique only within its type, which is why the config-driven processors share one name: `processor.generator.generic`, `processor.explicit.generic`, `processor.mass_generator.generic`. The section header is the name: `[processor.checker.ruff]`.
`rsconstruct processor list` prints every processor's full name; `rsconstruct processor list --type mass_generator` narrows it to one type.
#### Instance naming
A single instance declared as `[processor.checker.pylint]` has the instance name `processor.checker.pylint`. Named instances declared as `[processor.checker.pylint.core]` and `[processor.checker.pylint.tests]` have instance names `processor.checker.pylint.core` and `processor.checker.pylint.tests`.
The instance name is used everywhere a processor is identified:
- **Build output and progress**: `[processor.checker.pylint.core] src/core/main.py`
- **Error messages**: `Error: [processor.checker.pylint.tests] tests/test_foo.py: ...`
- **Build statistics**: each instance reports its own file counts and durations
- **Cache keys**: instances have separate caches, so changing one config does not invalidate the other
- **Output directories**: generator processors default to `out/{instance_name}` — `out/processor.generator.tera` for a single tera instance, `out/processor.generator.marp.slides` and `out/processor.generator.marp.docs` for two marp instances — so outputs never collide
- **The `--processor` filter**: use the full instance name, e.g., `rsconstruct build -p processor.checker.pylint.core`
- **`processor config`, `processor files`, `--iset`**: `rsconstruct processor config processor.checker.pylint.core`, `--iset processor.checker.pylint.core.max_jobs=2`
#### Migrating from short names
Until rsconstruct 0.9.x a processor was named by its bare name (`[processor.ruff]`, `-p ruff`, `out/tera`). Those names are gone: an old-style header is a config error with a hint (`[processor.ruff]: unknown processor type 'ruff' … did you mean [processor.checker.ruff]?`), so a config that was missed fails loudly rather than silently building nothing. Every cache entry is keyed by the processor name, so the first build after renaming a section rebuilds that processor once.
### Auto-detection
Run `rsconstruct smart auto` to scan the project and automatically add `[processor.TYPE.NAME]` sections for all processors whose files are detected and whose tools are installed. It does not remove existing sections.
## Variable substitution
Define variables in a `[vars]` section and reference them using `${var_name}` syntax:
```toml
[vars]
kernel_excludes = ["/kernel/", "/kernel_standalone/", "/examples_standalone/"]
[processor.checker.cppcheck]
src_exclude_dirs = "${kernel_excludes}"
[processor.generator.cc_single_file]
src_exclude_dirs = "${kernel_excludes}"
```
Variables are substituted before TOML parsing. The `"${var_name}"` (including quotes) is replaced with the TOML-serialized value, preserving types (arrays stay arrays, strings stay strings). A reference must constitute the **entire quoted value** — an embedded reference like `"${base}/src"` cannot be substituted and is a config error, as is any undefined variable reference.
## Local overlay (`rsconstruct.local.toml`)
If a file named `rsconstruct.local.toml` exists next to `rsconstruct.toml`, it
is loaded automatically and deep-merged over the main config. This lets many
repos share one canonical, identical `rsconstruct.toml` while keeping
repo-specific configuration — `[dependencies]` lists, `[processor.explicit.*]`
generators, exclude lists, one-off workarounds — in the local file.
Merge semantics:
- **Tables merge recursively.** A local `[processor.checker.mypy]` with only
`batch = false` adds that one key to the main file's mypy section; the rest
of the section is untouched.
- **Arrays and scalars replace wholesale.** If the local file sets
`src_dirs`, that exact list is used — values are never concatenated, so the
local file can also *remove* entries by setting a shorter list.
- **Local-only sections are added.** The overlay can declare whole processors,
analyzers, or global sections the main file doesn't have.
Rules and caveats:
- The overlay only extends a main config: `rsconstruct.local.toml` without an
`rsconstruct.toml` is an error.
- `[vars]` substitution is per-file — each file's `${...}` references resolve
against its own `[vars]` section only.
- The merged result is validated as one config, so unknown fields or type
errors in the local file are reported the same way as in the main file.
- `rsconstruct processor config <iname>` shows the merged values.
- In watch mode, both files are watched for changes.
This supports a shared-config pattern: one `rsconstruct.toml` distributed
across many repos plus a small optional `rsconstruct.local.toml` per repo for
what's genuinely repo-specific. Note that every `src_dirs` entry must exist in
every repo that carries it (see [Missing `src_dirs` and `src_files`
entries](#missing-src_dirs-and-src_files-entries)); a shared file can no longer
list directories only some repos have, and `[build] allow_missing_src_dirs`
exists for a project that still wants that.
## User config (`~/.config/rsconstruct/config.toml`)
A per-user file, read from `$XDG_CONFIG_HOME/rsconstruct/config.toml` (or
`~/.config/rsconstruct/config.toml` when `XDG_CONFIG_HOME` is unset), sets
`[build]` defaults for every project you build on this machine, and under
[`[tables]`](#tables) chooses which columns the CLI's tables show. For
`[build]` the precedence is, lowest first:
1. built-in defaults
2. the user config
3. `rsconstruct.toml`
4. `rsconstruct.local.toml`
Keys merge one by one, so a repo that sets a `[build]` key overrides the user
value for that key only. Example:
```toml
# ~/.config/rsconstruct/config.toml
[build]
reject_dot_src_dirs = true
```
Rules:
- **Only `[build]` and `[tables]` are allowed.** A `[processor.*]`,
`[analyzer.*]` or any other table in this file is a config error naming
the offending section. Anything that changes what a repo scans or builds
belongs in the repo's own files, where every machine and CI see the same
thing; a machine-wide file that could add processors would make the same
repo build differently on two machines. `[tables]` passes because it
changes nothing about the build, only how the CLI prints its tables.
- **CI never reads it.** Continuous integration checks out the repo and
nothing else, so a switch that must hold in CI has to be set in
`rsconstruct.toml`. The user file is a local safety net and a way to try a
policy across all your projects before committing it to each of them.
- It applies even in a directory without `rsconstruct.toml`, for the commands
that run without a config.
- Watch mode does not watch this file; restart the watcher after editing it.
- `rsconstruct toml files` prints the resolved path of this file, together
with the rest of the chain, and whether each one exists.
### `[tables]`
Every table rsconstruct prints has a name and a fixed set of columns. By
default a table shows all of them except a few that are hidden unless
`--verbose` asks for them. An entry under `[tables]` replaces that default
for one table: the value is the list of columns to show, in the order to
show them, spelled exactly as the column headers are.
```toml
# ~/.config/rsconstruct/config.toml
[tables]
# processor list: just the names and whether each one batches.
processor_list = ["Name", "Batch"]
# tool list: always show how to install a tool, without --verbose.
tool_list = ["Tool", "Status", "Install"]
# hook: the Lua function names first, descriptions last.
hook_list = ["Function", "Hook", "Description"]
```
`rsconstruct --fields <command>` prints a table's name, the command that
prints it and its column names, with no data; `rsconstruct --all <command>`
shows every column of every table, whatever this section says. A key that
names no table, or a column that the table does not have, is a config error
listing the valid names. The two tables whose columns depend on the data
(`product_status`, `tag_matrix`) are checked when they are printed; an
unknown column there is a warning and is skipped.
The tables, their commands and their columns; a column marked *(verbose)*
is hidden by default:
| Table | Command | Columns |
|---|---|---|
| `analyzer_defconfig` | `rsconstruct analyzer defconfig` | `Field`, `Type`, `Default` |
| `analyzer_list` | `rsconstruct analyzer list` | `Name`, `Builtin`, `Description` *(verbose)* |
| `analyzer_stats` | `rsconstruct analyzer stats, analyzer build` | `Analyzer`, `Files`, `Dependencies` |
| `analyzer_used` | `rsconstruct analyzer used` | `Name`, `Detected`, `Description` *(verbose)* |
| `build_timings` | `rsconstruct build --timings` | `Phase`, `Duration` |
| `error_list` | `rsconstruct error` | `Code`, `Name`, `Description` *(verbose)* |
| `hook_list` | `rsconstruct hook` | `Hook`, `Function` *(verbose)*, `Location` *(verbose)*, `Description` |
| `info_source` | `rsconstruct info source` | `Extension`, `Count` |
| `processor_config` | `rsconstruct processor config` | `Field`, `Value` |
| `processor_fields` | `rsconstruct processor defconfig, processor info` | `Field`, `Type`, `Default`, `Required`, `Checksum`, `Description` *(verbose)* |
| `processor_list` | `rsconstruct processor list` | `Name`, `Type`, `Builtin`, `Rust`, `Batch`, `Cache`, `Sandbox`, `Rust alternative`, `Description` *(verbose)* |
| `processor_recommend` | `rsconstruct processor recommend` | `Extension / File`, `Processor`, `Also`, `Reason` |
| `processor_search` | `rsconstruct processor search` | `Name`, `Type`, `Description`, `Keywords` |
| `processor_types` | `rsconstruct processor types` | `Type`, `Batch`, `Description`, `Batching` *(verbose)* |
| `processor_used` | `rsconstruct processor used` | `Name`, `Type`, `Detected`, `Description` *(verbose)* |
| `product_status` | `rsconstruct status, build --dry-run` | `Processor`, one column per product state (`up-to-date`, `restorable`, `stale`, `new` for `status`; `skip`, `restore`, `build`, `build-new` for `build --dry-run`), `builtin`, `rust` |
| `sloc` | `rsconstruct sloc` | `Language`, `Files`, `Blank`, `Comment`, `Code` |
| `status_breakdown` | `rsconstruct status --breakdown` | `Processor`, `Files`, `Breakdown` |
| `tag_count` | `rsconstruct tag count` | `Count`, `Tag` |
| `tag_coverage` | `rsconstruct tag coverage` | `Category`, `Files`, `Coverage` |
| `tag_matrix` | `rsconstruct tag matrix` | `File`, then one column per tag category |
| `tag_suggest` | `rsconstruct tag suggest` | `Tag`, `Score` |
| `tool_list` | `rsconstruct tool list` | `Tool`, `Status`, `Runtime`, `Target`, `Processors`, `Install` *(verbose)* |
| `tool_runtimes` | `rsconstruct tool stats` | `Runtime`, `Installed` |
| `tool_stats` | `rsconstruct tool stats` | `Tool`, `Status`, `Processors`, `Install` |
| `webcache_list` | `rsconstruct webcache list` | `URL`, `Size`, `Age`, `State` |
## Section details
### `[build]`
| Key | Type | Default | Description |
|---|---|---|---|
| `parallel` | integer | `1` | Number of parallel jobs. `1` = sequential, `0` = auto-detect CPU cores. Can also be set via the `RSCONSTRUCT_THREADS` environment variable (CLI `-j` takes precedence). |
| `batch_size` | integer | `0` | Maximum files per batch for batch-capable processors. `0` = no limit (all files in one batch). To disable batching, pass `--batch-size -1` on the CLI or set `batch = false` on individual processors. |
| `output_dir` | string | `"out"` | Global output directory prefix. Processor `output_dir` defaults that start with `out/` are remapped to use this prefix (e.g., setting `"build"` changes `out/processor.generator.marp` to `build/marp`). Individual processors can still override their `output_dir` explicitly. |
| `max_discovery_passes` | integer | `10` | Maximum fixed-point discovery passes. Discovery repeats while processors keep adding products from each other's declared outputs; a config still adding products at the cap fails the build (naming the processors involved) instead of silently truncating the graph. |
| `hash_tool_versions` | boolean | `true` | Mix the identity of each processor's external tools into its products' cache keys, so upgrading a tool invalidates what that tool produced. Tools are identified by the resolved binary's path, size and mtime (no `--version` subprocess and no read of its bytes). Which release is installed is [`rsconstruct.lock`](tool-lock.md)'s business, not the cache key's. Set to `false` to leave tool identity out of cache keys entirely. |
| `hash_python_env` | boolean | `true` | Mix a fingerprint of the project's Python environment (the distributions installed in `./.venv` and the interpreter version from `pyvenv.cfg`) into the cache keys of the processors that depend on it: the Python checkers, and any processor whose tool runs the venv's Python (see the per-processor [`hash_python_env`](#processortypename) field). Upgrading the packages (`uv lock --upgrade && uv sync`) then rebuilds what was checked or built against the old ones. No effect in a project without `./.venv`. Set to `false` to leave the Python environment out of every cache key. Design notes: [Python Environment Fingerprint](internal/python-env-fingerprint.md). |
| `python` | string | `"python"` | The Python interpreter rsconstruct runs and requires wherever it needs Python. This one key covers every use: the default `command` of the processors that run the interpreter directly (`doctest`, `jinja2`, `mako`), the interpreter that the Python checkers (black, mypy, pylint, pytest, yamllint, jsonlint) and the `a2x`, `pip`, `tera` and `sphinx` processors list as a required tool, the default of sphinx's own `python` field, tera's `load_python()`, and the installed-package query in `rsconstruct doctor`. A bare name is looked up on `PATH`, where the project's `./.venv/bin` comes first, so a uv-made venv (which provides both `python` and `python3`) works with either. Set `python = "python3"` on a machine that has only `python3`, i.e. no venv and no `python-is-python3` package; `tool install machine` then installs the `python3` apt package instead of `python-is-python3`. A processor's explicit `command` still wins over this default. Must not be empty. |
| `execution_model` | string | `"native"` | How processors run their external tools. `"native"` runs them directly in the project tree, as rsconstruct always has. `"sandbox"` runs each one under [bubblewrap](https://github.com/containers/bubblewrap) (`bwrap`, apt `bubblewrap`): the filesystem is read-only except `$HOME` and `/tmp`, the network is cut off, and the project tree sits behind an overlay so that only the product's declared outputs reach it. A tool that writes or removes any other path in the project fails its product with a list of the paths, and nothing it wrote is kept; a tool that fails leaves no partial outputs. **A correctness check, not a security boundary**: it catches undeclared outputs and build-time network access, not hostile tools. It is an option, never required: the default stays `"native"`, a build that does not ask for the sandbox never needs `bwrap`, and a build that does fails up front when `bwrap` is missing. The sandbox is not part of any cache key. Linux only (bubblewrap 0.9 or newer). Each processor can override this, and tune the sandbox with `sandbox_network` and `sandbox_writable` (see [`[processor.TYPE.NAME]`](#processortypename)). Some processors cannot run in a sandbox at all (marp, mermaid, chromium and drawio, which launch Chromium; `processor list` shows them with `Sandbox` = `No`): a build in which any enabled instance of one would run sandboxed fails at the start with a config error naming each, before any work is done, until it is set to `execution_model = "native"` or disabled. Design notes: [Sandboxed Execution](internal/sandbox.md). |
| `warn_symlinks` | boolean | `false` | Warn about every symlink skipped during the file-index walk. The walker never follows symlinks, so a symlinked source (or a symlinked directory of sources) is absent from the index — never checked, never built. Set to `true` to make that gap visible. Off by default because projects that deliberately keep symlinks around (vendored trees, dotfile farms) would drown in warnings. |
| `command_timeout_secs` | integer | `0` | Wall-clock limit in seconds for every external command a processor runs; a command still running at the limit is killed and its product fails with `Command timed out after Ns and was killed`. `0` means no limit. **Off by default, on purpose**: a tool that hangs is a bug in the tool, its input, or the environment, and the fix is to find that cause — not to cut the tool off. Set this only where a build must not be allowed to sit forever (an unattended runner) and a loud kill beats a silent hang. A processor with its own timeout (`marp`'s `timeout_secs`) keeps it; the explicit value wins. |
| `allow_missing_dep_auto` | boolean | `false` | Skip a `dep_auto` entry you listed when the file does not exist, as every entry used to be skipped. By default such an entry is a config error naming the processor, the file and the config line: a listed file that is missing is a typo or a stale copy of a shared config, and either way a dependency that silently tracks nothing. Processor defaults (`.pylintrc`, `ruff.toml`, ...) are optional by nature and are never checked. |
| `allow_missing_src_dirs` | boolean | `false` | Skip a `src_dirs` entry that names a directory which does not exist, as every entry used to be skipped. By default such an entry is a config error naming the processor and the entry: a directory listed in the config that is not there is a typo, a stanza left behind when the directory moved, or a copy of another repo's config, and in every case a processor that checks nothing while the build stays green. A directory an upstream processor declares as its output is never reported, whatever this is set to. This switch covers directories only: a missing `src_files` entry is always an error. |
| `reject_dot_src_dirs` | boolean | `false` | Make a `src_dirs` entry of `"."` a config error. `"."` and `""` both mean the whole project tree, recursively; written as `"."` it reads like "the root directory" and hides that the stanza sweeps every subdirectory too. Turn this on in a project whose stanzas are meant to name the directories they cover: the error names the stanza and the config line, and the fix is to list the real directories, or to write `""` if sweeping the tree is intended. Off by default because `"."` is not wrong, only easy to misread. Disabled stanzas are not checked. |
| `worker_stack_mib` | integer | `256` | Stack size, in MiB, of each build worker thread. The builtin checkers parse arbitrary files with recursive parsers; on a small stack a deeply nested file (thousands of `(` in Lua, of `<div>` in HTML) overflows it, which aborts the whole process. Only touched pages are committed, so the reservation costs address space, not memory. A panic inside a processor fails that product only. |
The `output_dir` prefix is purely a layout choice — `rsconstruct clean outputs` does not special-case it. Cleanup is driven by per-product `outputs` and `output_dirs` declarations, then a generic empty-directory sweep walks parents bottom-up. See [Clean behavior](processors.md#clean-behavior) and [`rsconstruct clean`](commands.md#rsconstruct-clean) for details.
### `[processor.TYPE.NAME]`
Each `[processor.TYPE.NAME]` section declares a processor instance. The header is the processor's full name: `TYPE` is its type (`checker`, `generator`, `explicit`, or `mass_generator`) and `NAME` the processor within that type (`[processor.checker.ruff]`, `[processor.generator.cc_single_file]`). A fourth segment names an instance (`[processor.checker.pylint.core]`).
Common fields available to all processors:
| Key | Type | Default | Description |
|---|---|---|---|
| `enabled` | boolean | `true` | Set to `false` to disable this processor without removing the stanza. Accepted on every processor. A disabled processor is skipped during discovery, so it produces no products; `smart remove-no-file-processors` ignores disabled stanzas rather than reporting them as matching no files. |
| `args` | array of strings | `[]` | Extra command-line arguments passed to the tool. |
| `dep_inputs` | array of strings | `[]` | Additional input files that trigger rebuild when changed. |
| `dep_auto` | array of strings | varies | Config files added as inputs. The processor's default list (e.g. `.pylintrc`) is skip-if-absent; a list you write here replaces it, and every entry in it must exist unless `[build] allow_missing_dep_auto` is set. |
| `required_tools` | array of strings | `[]` | Extra tools this processor needs beyond `command`. Normally `command` *is* the tool, so this is empty. Name the real tool here when `command` is a wrapper script that shells out to it — otherwise that tool is invisible to `rsconstruct tool install` and to version locking, and a missing tool surfaces only as a failure inside the wrapper. Each name must have a registry entry (`rsconstruct tool list`). |
| `batch` | boolean | `true` | Whether to batch multiple files into a single tool invocation. A batching checker waits for all of its files to be ready and runs once over them; `--batch-size` on the command line limits or disables batching build-wide. For external tools, a batch failure marks all products in the chunk as failed. Internal processors (`i`-prefixed) return per-file results, so partial failure is handled correctly. |
| `output_depends_on_input_name` | boolean | `false` (`true` for ruff, pylint and mypy) | Set to `true` when the processor's result depends on the input files' paths and not only on their content: its output names the input (`// Generated from foo.c`), or it is a checker with per-path rules (ruff's `per-file-ignores`, mypy's module resolution). The cache normally keys a product by input *content*, so a renamed file with the same content, or an identical file at another path, reuses the cached result; with this set, the input paths are part of the key and such a file is rebuilt. Unchanged files are still skipped and restored from the cache as usual. Accepted on every processor. |
| `hash_python_env` | boolean | unset = detect (`true` for ruff, pyrefly, mypy, pylint, black, pytest, doctest and sphinx) | Set to `true` when the processor's result depends on the Python packages installed in `./.venv`: the fingerprint of the installed distributions and interpreter version becomes part of the cache key, so upgrading them rebuilds. Unset, it is detected: the processor is keyed when its `command` (or a declared `required_tools` entry) runs the venv's Python, i.e. resolves to the venv's interpreter, or is a script whose shebang is `/usr/bin/env python*` or names an interpreter inside `./.venv`. That covers `command = "python"`, `scripts/build.py` with a Python shebang, and Python console scripts installed in the venv. Set `true` for a wrapper that runs Python out of detection's sight (a shell script); set `false` to keep the environment out of a processor's key. Ignored when `[build] hash_python_env = false` or there is no `./.venv`. Accepted on every processor. |
| `execution_model` | string | unset = `[build] execution_model` | `"native"` or `"sandbox"`: overrides the build-wide [`execution_model`](#build) for this processor, e.g. to sandbox one processor while adding it, or to keep one native that cannot run sandboxed. Accepted on every processor; builtin (in-process) processors run no external tool and are unaffected. |
| `sandbox_network` | boolean | `false` | Under the sandbox execution model, let this processor's tools reach the network. Every tool rsconstruct knows declares whether it needs the network (`cargo-deny`, `taplo`, `npm`, `pip`, `uv` and `bundle` do; `rsconstruct tool list --json` shows each tool's `needs_network`), and a sandboxed processor gets it when any tool it runs does, so this field is needed mainly for a user-supplied command that downloads, such as a script. Ignored natively. Accepted on every processor. |
| `sandbox_writable` | array of strings | `[]` | Under the sandbox execution model, places this processor may write its tools' own state in beyond those the tools already declare. Every tool rsconstruct knows declares where it writes state (`target` for cargo, `.ruff_cache` for ruff, `.pytest_cache` for pytest, `**/__pycache__` for every Python tool, `.git` for git, ...; `rsconstruct tool list --json` shows each tool's `sandbox_writable`), and a sandboxed processor may write the places of every tool it runs, so this field is needed mainly for a user-supplied command such as a script, whose tool rsconstruct does not know. Each entry is a path relative to the project root, or `**/NAME` for a directory called NAME anywhere in the tree; `..`, absolute paths and other wildcards are config errors. A path that exists is written directly; anything else written there is moved into the tree after a successful run, like an output. Nothing is created in advance. Ignored natively. Accepted on every processor. |
| `max_jobs` | integer | none | Maximum concurrent jobs for this processor. When set, limits how many instances of this processor run in parallel, regardless of the global `-j` setting. Useful for heavyweight processors (e.g., `marp` spawns Chromium). Omit to use the global parallelism. |
| `src_dirs` | array of strings | `[]` | Directories to scan for source files. **Every processor defaults to `[]`, which scans nothing** — no processor guesses a directory, so one declared without `src_dirs` matches no files and simply builds nothing. A default like `["src"]` would be a guess that silently matches the wrong directory in a project laid out differently; naming the directory is the user's call. To scan the whole project deliberately, use `src_dirs = [""]` — an empty string means the project root and walks everything beneath it, including `node_modules/`, `.venv/` and `target/` unless excluded. `"."` means exactly the same thing, but reads as if it named only the root directory; `[build] reject_dot_src_dirs = true` forbids that spelling. `src_files` is an alternative to `src_dirs` for listing exact paths. **Every entry must name a directory that exists**; an entry that does not is a config error (exit code 2) naming the processor and the entry — see [Missing `src_dirs` and `src_files` entries](#missing-src_dirs-and-src_files-entries) below. The one exception is a directory an upstream processor declares as its output: it does not exist before that processor runs, and is accepted. Use `rsconstruct processor defconfig <name>` to see a processor's defaults. |
| `src_extensions` | array of strings | varies | File extensions to match. |
| `src_exclude_dirs` | array of strings | varies | Directory path segments to exclude from scanning. |
| `src_exclude_files` | array of strings | `[]` | File names to exclude. |
| `src_exclude_paths` | array of strings | `[]` | Paths (relative to project root) to exclude. |
| `src_files` | array of strings | `[]` | Exact paths to match, relative to the project root. On its own it is an allowlist: **exactly the named files are matched and nothing else** (no directory scan, no extension filter). Together with `src_dirs`, the named files are added to what the directories yield. **Every entry must name a file that exists**, or a path an upstream processor declares as its output; anything else is a config error (exit code 2), and unlike a missing directory it is never forgiven — `allow_missing_src_dirs` does not apply to files. See [Missing `src_dirs` and `src_files` entries](#missing-src_dirs-and-src_files-entries). |
Processor-specific fields are documented on each processor's page under [Processors](processors.md).
### `[cache]`
| Key | Type | Default | Description |
|---|---|---|---|
| `restore_method` | string | `"auto"` | How to restore cached outputs. `"auto"` (default) uses `"copy"` in CI environments (`CI=true`) and `"hardlink"` otherwise. `"hardlink"` is faster but requires same filesystem; `"copy"` works everywhere. |
| `compression` | boolean | `false` | Compress cached objects with zstd. Incompatible with `restore_method = "hardlink"` — requires `"copy"`. |
| `remote` | string | none | Remote cache URL. See [Remote Caching](remote-caching.md). |
| `remote_push` | boolean | `true` | Push locally built artifacts to remote cache. |
| `remote_pull` | boolean | `true` | Pull from remote cache on local cache miss. |
| `mtime_check` | boolean | `true` | Persist file checksums across builds using an mtime database. Set to `false` in CI/CD environments where the cache won't survive the build and the write overhead isn't worth it. Can also be disabled via `--no-mtime-cache` flag. See [Checksum Cache](internal/checksum-cache.md). |
| `webcache_ttl_secs` | integer | `604800` (7 days) | How long a cached HTTP response (remote JSON schemas fetched by `iyamlschema`) stays fresh. An entry older than this is re-fetched. Set to `0` to disable the web cache entirely and always re-fetch. Expired entries are reclaimed by [`rsconstruct cache trim`](commands.md#rsconstruct-cache). |
`rsconstruct cache trim` reclaims three kinds of dead weight: unreferenced objects in the store, mtime-database rows for files that no longer exist, and expired web-cache entries. Without it these grow with the history of the project rather than its current size.
### `[analyzer]`
| Key | Type | Default | Description |
|---|---|---|---|
| `auto_detect` | boolean | `true` | When `true`, only run enabled analyzers that auto-detect relevant files. |
| `enabled` | array of strings | `["cpp", "python"]` | List of dependency analyzers to enable. |
### `[graph]`
| Key | Type | Default | Description |
|---|---|---|---|
| `viewer` | string | platform-specific | Command to open graph files |
| `validate_empty_inputs` | boolean | `true` | Reject products with no input files |
| `validate_dep_references` | boolean | `true` | Check the graph's internal consistency (ids, dependency table) after it is built |
| `validate_duplicate_inputs` | boolean | `false` | Report an input file that appears in several products of one processor |
| `validate_early_cycles` | boolean | `false` | Check for dependency cycles right after resolving dependencies, not at scheduling time |
The defaults hold whether or not the `[graph]` table is present.
### `[completions]`
| Key | Type | Default | Description |
|---|---|---|---|
| `shells` | array | `["bash"]` | Shells to generate completions for |
### Missing `src_dirs` and `src_files` entries
A `src_dirs` or `src_files` entry is a claim about where the project keeps its
sources. When the directory or file it names is not there, the build fails at
discovery with exit code 2 (`EXIT_CONFIG_ERROR`) and lists every offending
entry:
```text
Invalid config:
[processor.checker.pylint] src_dirs entry 'scripts' does not exist or is not a directory
[processor.checker.luacheck] src_dirs entry 'config' does not exist or is not a directory
[processor.checker.taplo] src_files entry 'pyproject.toml' does not exist or is not a file
Every src_dirs entry must name a directory that exists and every src_files
entry a file that exists (or a path an upstream processor declares as its
output) — fix the path or remove the entry; [build] allow_missing_src_dirs =
true skips absent directories as before, never absent files
```
Directories used to be a silent skip, visible only under `--phases`, and files
were never checked at all. That let a stanza whose directory had moved, one
copied from another repo, or one with a typo in a file name keep the build
green while checking nothing at all — the worst kind of failure, because the
green tick says the check ran. The fix is always in the config: point the
entry at the directory or file that actually exists, or delete the stanza if
the files are gone.
What is **not** reported:
- `""` and `"."`, which mean the project root and always exist.
- A directory or file an upstream processor declares as its output (for
example a linter whose `src_dirs` is a generator's `output_dir`, or whose
`src_files` names one of its outputs). It does not exist before that
processor has run; discovery sees the declared outputs as virtual files and
accepts the entry.
- Entries of a stanza with `enabled = false`.
- Anything during `rsconstruct clean` and `rsconstruct smart
remove-no-file-processors`: clean must still be able to remove the outputs
of a build whose source directory has since gone, and the repair command
exists to delete the very stanzas this check rejects. Both report the
entries under `--phases` instead.
`[build] allow_missing_src_dirs = true` restores the old skip for directories
in a project that needs it; the skipped entries are then listed under
`--phases`. It never covers `src_files`: a directory can at least plausibly be
empty, a named file that is not there is simply wrong. Prefer fixing the
entry: the switch hides exactly the misconfiguration this check exists to
catch.
### `[dependencies]`
Declare project dependencies by package manager. Used by `rsconstruct doctor` to verify availability, and by `rsconstruct tool install machine` (the `system` list) and `rsconstruct tool install project` (everything else) to install missing packages. There is no Python list: a project's Python packages are declared in `pyproject.toml` and pinned by `uv.lock` (see below).
| Key | Type | Default | Description |
|---|---|---|---|
| `npm` | array of strings | `[]` | Node.js command-line packages installed into the project's tool directory, `.rsconstruct/tools` (see [Tool Lock](tool-lock.md#where-tools-are-installed)), on top of the project's own package.json set. |
| `npm_source` | string | `"package-lock"` | Where the project's Node.js package set comes from: `"package-lock"` installs the closure package-lock.json pins with `npm ci`; `"package-json"` resolves package.json's ranges with `npm install`. |
| `gem` | array of strings | `[]` | Ruby gems installed into the project's tool directory, `.rsconstruct/tools`. |
| `cargo` | array of strings | `[]` | Crates from crates.io installed into the project's tool directory with `cargo install --locked`, by crate name (e.g. `"cargo-deny"`, `"cargo-nextest"`, `"mdbook"`). Bare names; rsconstruct.lock pins the version. See below. |
| `system` | array of strings | `[]` | System packages installed via the detected package manager (`apt-get`, `dnf`, `pacman`, or `brew`). |
#### Python packages live in the repo's `.venv`, owned by uv
A project has one Python environment: the repo's `.venv`, built by `uv sync`
from `uv.lock`. It holds the code's dependencies and the Python tools its
processors run (ruff, pytest, pyrefly) together, all declared in
`pyproject.toml` — tools in the dev dependency group — and pinned by
`uv.lock`, the exact closure including transitive dependencies. `tool install
project` runs `uv sync --locked --no-install-project`: `--locked` fails when
the lock is out of date with pyproject.toml instead of quietly re-resolving
it, and the project itself is left out, since building it is the build's
job (a package whose build hook needs a file CI lacks would otherwise fail
the install). rsconstruct never
runs pip into that venv itself: `uv sync` would remove anything uv.lock does
not list, and a pip install could shift a version the code has locked.
Consequences:
- A Python tool an enabled processor runs that `uv.lock` does not pin is an
error naming the fix, `uv add --dev <tool>`. rsconstruct.lock never pins a
Python package.
- A `pyproject.toml` that declares Python dependencies with no `uv.lock`
beside it is an error: run `uv lock`. The declared dependencies are
`[project].dependencies`, every list in `[project.optional-dependencies]`,
and every [PEP 735](https://peps.python.org/pep-0735/) `[dependency-groups]`
list.
- `uv` itself builds the `.venv` and so cannot come from it: it is a release
binary that every project with Python dependencies locks in
`rsconstruct.lock` (`[binary.uv]`), and `tool install project` links it
into `.rsconstruct/tools` before it runs `uv sync`. The machine needs no
uv.
- Every rsconstruct invocation in a project prepends `.venv/bin` to its own
`PATH`, so `python`, `ruff` and `pytest` resolve to the locked copies with
no venv activated.
`doctor` reads the same closure from `uv.lock` (registry packages only; the
project's own entry is skipped, and any other source kind is an error) and
asks the interpreter whether each is installed.
#### Node.js dependencies come from `package-lock.json` by default
The Node side works the same way. A project's Node.js packages are declared
in its `package.json` (`dependencies`, `devDependencies` and
`optionalDependencies` — the three sections `npm ci` installs) and pinned by
the `package-lock.json` beside it. In the default `npm_source =
"package-lock"` mode, `tool install project` runs `npm ci` in the project root, which
installs exactly the lock's closure into the project's own `node_modules/`
and fails if the lock is out of sync with the manifest instead of silently
re-resolving. A `package.json` that declares packages but has no
`package-lock.json` is an error: run `npm install --package-lock-only`, or
opt out per repo with `npm_source = "package-json"`, which runs `npm install`
and lets the versions float.
The `node` (and so the `npm`) that runs all this is the project's own: a Node
project locks the Node.js release in `rsconstruct.lock`, and `tool install
project` links it into `.rsconstruct/tools` before any npm step.
The install is skipped when every declared package is already present in
`node_modules/` at the version the lock pins — `npm ci` wipes `node_modules/`
before installing, so a needless run is not free. `doctor` reports each
declared package the same way: installed means present in the project's
`node_modules/`, not somewhere global.
To make the installed executables resolvable, every rsconstruct invocation
prepends the project's `node_modules/.bin`, when it exists, to its own
`PATH` at startup (the same mechanism that appends the user gem bin dirs, see
`rsconstruct tool` in the commands reference). Prepended, so the version the
lock pins wins over a global install of the same tool — processors keep
invoking `stylelint` or `mmdc` plainly, and `tool install machine` sees the locked
copy and does not install a global one. This is what `npm run` does for
scripts.
`[dependencies].npm` is for a command-line package the project does not
declare in package.json. It is installed into the project's tool directory,
`.rsconstruct/tools`, at the version rsconstruct.lock pins, never globally:
see [Tool Lock](tool-lock.md#where-tools-are-installed).
#### Rust crates are a list, not tools
A cargo subcommand or other Rust-built tool a build runs (`cargo-deny`,
`cargo-nextest`, `mdbook`) is a crate on crates.io, and crates.io is a
package registry like PyPI or npm. So these are declared as a plain list
under `cargo`, by crate name, and are not entries in the tool registry.
The manifest carries bare names, as everywhere else in the fleet, and
rsconstruct.lock pins each crate's version. `tool install project` installs each
crate into the project's tool directory, `.rsconstruct/tools`, with `cargo
install --locked --root`: `--locked` builds the crate with the Cargo.lock it
was published with, so a given crate version yields the same binary
everywhere. The build happens once per machine, into the tool store, and
every project locking that version links it from there (see [Tool
Lock](tool-lock.md#where-tools-are-installed)).
Presence is judged by the project's tool directory, by crate name and
version, not by a binary on PATH or `cargo install --list`: a crate installed
globally, at whatever version, does not count. `doctor` reports each declared
crate the same way. A `cargo <subcommand>` processor (`cargo deny`, `cargo
nextest`) runs the project's `cargo-<subcommand>` directly, since cargo would
look in `$CARGO_HOME/bin` before `PATH` and find a global one first.
Components rustup manages (`rustfmt`, `clippy`) are not crates and do not
belong in this list.
#### Install order
A project is set up with `rsconstruct tool install machine` and then
`rsconstruct tool install project`, which together install in this fixed
order:
1. **`system`** — OS packages (apt, dnf, pacman, brew), then the other
machine installs (`tool install machine`)
2. **Python** — `uv sync` into the repo's `.venv` (`tool install project`,
from here on), after linking in the project's locked `uv` and `node`
3. **Node.js** — the project's `npm ci`
4. **`.rsconstruct/tools`** — the locked crates, npm packages, gems and
release binaries
This order is deliberate and must not be changed. Language-level packages frequently build native extensions that link against system libraries at install time. For example, installing `manim` pulls in `manimpango`, which compiles a C extension and uses `pkg-config` to find `pangocairo` — so `libpango1.0-dev` must already be on the system before `uv sync` runs. Installing Python (or gem, or npm) packages before `system` causes wheel/extension builds to fail with messages like `Package 'pangocairo' was not found`. That is why `tool install machine` comes first.
The keys inside `[dependencies]` may appear in any order in `rsconstruct.toml`; the install order is enforced regardless.
#### `eatmydata` wrapping
When [`eatmydata`](https://www.flamingspork.com/projects/libeatmydata/) is installed on the system *and* `CI=true` is in the environment, `rsconstruct tool install machine` wraps its `apt`/`dnf`/`pacman` invocations with it. `eatmydata` no-op's `fsync()` for the wrapped process, which speeds up package installs by 3–10×.
The trade-off is loss-on-power-cut: any package files written during the install are not flushed to disk, so a power loss mid-install can leave the package database inconsistent. That's fine on transient CI hosts and wrong on developer workstations — hence the `CI=true` gate.
The wrap inserts `eatmydata` *after* `sudo` so the `LD_PRELOAD` applies to the package manager, not to `sudo` itself: e.g. `sudo eatmydata apt-get install -y …`.
If `eatmydata` is not installed, the commands run unwrapped — no error, no warning.
##### Controlling the wrap
| To... | Do this |
| ------------------------------------------- | ---------------------------------------------------- |
| Use the wrap (the CI default) | Set `CI=true` and have eatmydata installed |
| Skip the wrap in CI | Unset `CI` (or set it to anything other than `true`) |
| Use the wrap outside CI | Run with `CI=true rsconstruct tool install machine` |
| Skip the wrap for a single invocation | Pass `--no-eatmydata` |
The CLI flag `--no-eatmydata` always wins. Otherwise the policy is driven entirely by `CI=true`. There is no `rsconstruct.toml` field for this — the env var is the knob.
The mechanism is a [post-config hook](processors.md): `eatmydata_ci_default` runs after config load and flips the in-memory `dependencies.eatmydata` flag when `CI=true`. List it with `rsconstruct hook`.
##### What's never wrapped
`brew` is never wrapped (eatmydata is Linux-only). `pip`, `npm`, `cargo`, and `gem` are never wrapped either — those don't fsync excessively, so the wrap adds nothing.
### `[pages]`
Declares that this repo publishes a directory to GitHub Pages. The section is optional — its *presence* is the signal. `rsconstruct page dir` prints the directory when the section exists and prints nothing (exit 0) when it doesn't, which lets a single shared CI workflow decide whether to run the Pages upload/deploy steps. See [GitHub Actions](github-actions.md#github-pages-deployment) for the workflow pattern.
| Key | Type | Default | Description |
|---|---|---|---|
| `dir` | string | required | Directory whose contents are published to GitHub Pages (e.g., `"out/web"` or `"_site"`). |
### `[command.symlink_install]`
Configures [`rsconstruct symlink-install`](commands.md#rsconstruct-symlink-install), which symlinks every file under each source folder into the matching target folder, recreating the directory structure. `sources[i]` is installed into `targets[i]`; the command fails if the arrays differ in length or are empty. A leading `~/` in a target is expanded to `$HOME`. The section is read only by that command, never by a build.
| Key | Type | Default | Description |
|---|---|---|---|
| `sources` | string[] | `[]` | Folders (relative to the project root) whose files are linked. |
| `targets` | string[] | `[]` | Folders the links are created in, one per entry of `sources`. |