# 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 after this many passes 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. |
| `remove_orphan_outputs` | boolean | `true` | When true (the default), a full build removes the output files an earlier full build produced that no product declares any more: the outputs of a deleted source, a disabled processor, a moved `output_dir`. A file changed since it was built, or tracked by git, is kept with a warning. Builds narrowed with `-p`, `-x`, targets, `--iset` or `--pset` neither remove nor record anything. Set `remove_orphan_outputs = false` under `[build]` in `rsconstruct.toml` (one project) or in `~/.config/rsconstruct/config.toml` (every project you build) to keep every output; set it back to `true`, or remove the line, to turn it on again. See [Orphan Outputs](internal/orphan-outputs.md#turning-it-off-and-on). |
| `sandbox_builtin_children` | integer | `0` | Under the sandbox, the number of sandboxed children that share the ready products of a builtin processor that does not batch (`icheckstyle`, `ishellcheck`, ...); each child checks its share one product after another. `0` = one child per parallel job. Natively such a processor checks each product in process and this is unused. See [Sandboxed Execution](internal/sandbox.md#builtin-processors). |
| `execution_model` | string | `"sandbox"` | How processors run their external tools. `"native"` runs them directly in the project tree, as rsconstruct did by default before 0.9.163. `"sandbox"` (the default) 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. A build in which anything runs sandboxed fails up front when `bwrap` is missing, naming it with an install hint; it never falls back to native. A machine that cannot have `bwrap` (macOS, a minimal container) sets `"native"`, in the project or in the user config. 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)). A processor that cannot run in a sandbox at all is shown by `processor list` with `Sandbox` = `No`, and 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. No processor is marked that way today: the Chromium-based ones (marp, mermaid, chromium, drawio) turn Chromium's own sandbox off when sandboxed (see [Sandboxing Chromium](internal/sandbox-chromium.md)). Design notes: [Sandboxed Execution](internal/sandbox.md). |
| `undeclared_reads` | string | `"off"` | Whether to watch which project files each tool reads. `"report"` runs every external tool of a product under `strace` (apt `strace`; a build with the report on fails up front when it is missing, and `tool install machine` installs it) and, after each successful run, warns about every file inside the project the tool opened for reading that its product does not declare: not an input (declared, or added by an analyzer), not an output or under an output directory, and not under a place the tool keeps its own state (its `sandbox_writable` entries, including `**/__pycache__` and `.rsconstruct/tools`). Reads under `.rsconstruct/`, `.venv/`, `node_modules/` and `.git/` are never reported. Builtin processors are not watched (their work is rsconstruct's own code). Only products that run are watched, so use it with `build --force` or on a cold cache. Traced runs are slower. Linux only. Works natively and under the sandbox. Design notes and measurements: [Undeclared Reads](internal/undeclared-reads.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. |
| `enabled_if_dir_exists` | string | unset | Run this processor only on a machine where this directory exists; a leading `~/` expands to the home directory (the only expansion: no environment variables). Where the directory is missing, the processor is off exactly as with `enabled = false` (no products, no tool to install, exempt from the `src_dirs` and `dep_auto` existence checks), and it is never hidden: the build prints `[build] <iname> skipped: <dir> does not exist`, `processor used` lists it under `Skipped on this machine`, and `processor config` shows the effective `enabled = false` beside the field. `enabled = false` wins over it. Accepted on every processor; not part of the cache key, since it decides whether the processor runs, not what it produces. **This deliberately makes a build machine-dependent**, which rsconstruct otherwise refuses (the user config cannot add processors): it exists for a processor whose job is a side effect on the local machine, such as mirroring files into a folder a sync client uploads, which has no meaning on CI or on another clone. The condition sits in the committed config, so anyone reading it sees which machines run the processor and why. **Known gap:** such a processor writes a stamp as its declared output, and the cache judges the stamp, not the side effect. Inputs that return to a state built before (an edit reverted) match that earlier cache entry, so the processor is skipped or its stamp restored without running, and the side effect keeps the newer state until the next new input state or a manual run. |
| `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 keep one native whose tool writes state the sandbox would refuse, or to sandbox one in a project that builds natively. Accepted on every processor. A builtin (in-process) processor resolved to `"sandbox"` runs in a sandboxed child rsconstruct (see [Sandboxed Execution](internal/sandbox.md#builtin-processors)); natively it runs in the build's own process, as always. |
| `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`, `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. `iyamlschema`, a builtin that fetches the JSON schemas its files name, defaults to `true`. 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, `.git` for git, ...; `**/__pycache__` and `.rsconstruct/tools` for every processor; `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`. |