RSConstruct - Rust Build Tool

A fast, incremental build tool written in Rust with C/C++ compilation, template support, Python linting, and parallel execution.

Features

• Incremental builds using SHA-256 checksums to detect changes
• C/C++ compilation with automatic header dependency tracking
• Parallel execution of independent build products with -j flag
• Template processing via the Tera templating engine
• Python linting with ruff and pylint
• Documentation spell checking using hunspell dictionaries
• Make integration — run make in directories containing Makefiles
• .gitignore support — respects .gitignore and .rsconstructignore patterns
• Deterministic builds — same input always produces same build order
• Graceful interrupt — Ctrl+C saves progress, next build resumes where it left off
• Config-aware caching — changing compiler flags or linter config triggers rebuilds
• Convention over configuration — simple naming conventions, minimal config needed

Philosophy

Convention over configuration — simple naming conventions, explicit config loading, incremental builds by default.

Nomenclature

This page defines the terminology used throughout RSConstruct’s code, configuration, CLI, and documentation.

Core concepts

Configuration

Cache

Build pipeline

CLI conventions

Installation

Download pre-built binary (Linux)

Pre-built binaries are available for x86_64 and aarch64 (arm64).

Using the GitHub CLI:

# x86_64
gh release download --repo veltzer/rsconstruct --pattern 'rsconstruct-linux-x86_64' --output rsconstruct --clobber

# aarch64 / arm64
gh release download --repo veltzer/rsconstruct --pattern 'rsconstruct-linux-aarch64' --output rsconstruct --clobber

chmod +x rsconstruct
sudo mv rsconstruct /usr/local/bin/

Or with curl:

# x86_64
curl -Lo rsconstruct https://github.com/veltzer/rsconstruct/releases/latest/download/rsconstruct-linux-x86_64

# aarch64 / arm64
curl -Lo rsconstruct https://github.com/veltzer/rsconstruct/releases/latest/download/rsconstruct-linux-aarch64

chmod +x rsconstruct
sudo mv rsconstruct /usr/local/bin/

Install from crates.io

cargo install rsconstruct

This downloads, compiles, and installs the latest published version into ~/.cargo/bin/.

Build from source

cargo build --release

The binary will be at target/release/rsconstruct.

Release profile

The release build is configured in Cargo.toml for maximum performance with a small binary:

[profile.release]
strip = true        # Remove debug symbols
lto = true          # Link-time optimization across all crates
codegen-units = 1   # Single codegen unit for better optimization

For an even smaller binary at the cost of some runtime speed, add opt-level = "z" (optimize for size) or opt-level = "s" (balance size and speed).

Getting Started

This guide walks through setting up an rsconstruct project for the two primary supported languages: Python and C++.

Python

Prerequisites

• rsconstruct installed (Installation)
• ruff on PATH

Setup

Create a project directory and configuration:

mkdir myproject && cd myproject

# rsconstruct.toml
[processor.checker.ruff]

Create a Python source file:

mkdir -p src

# src/hello.py
def greet(name: str) -> str:
    return f"Hello, {name}!"

if __name__ == "__main__":
    print(greet("world"))

Run the build:

rsconstruct build

Expected output:

Processing ruff (1 product)
  hello.py

Run again — nothing has changed, so rsconstruct skips the check:

Processing ruff (1 product)
  Up to date

Adding pylint

Install pylint and add a section for it:

# rsconstruct.toml
[processor.checker.ruff]

[processor.checker.pylint]

Pass extra arguments via processor config:

[processor.checker.pylint]
args = ["--disable=C0114,C0115,C0116"]

Adding zspell for docs

If your project has markdown documentation, add a section for the zspell processor:

[processor.checker.ruff]

[processor.checker.pylint]

[processor.checker.zspell]

Create a .zspell-words file in the project root with any custom words (one per line) that the zspeller should accept.

C++

Prerequisites

• rsconstruct installed (Installation)
• gcc/g++ on PATH

Setup

Create a project directory and configuration:

mkdir myproject && cd myproject

# rsconstruct.toml
[processor.generator.cc_single_file]

Create a source file under src/:

mkdir -p src

// src/hello.c
#include <stdio.h>

int main() {
    printf("Hello, world!\n");
    return 0;
}

Run the build:

rsconstruct build

Expected output:

Processing cc_single_file (1 product)
  hello.elf

The compiled executable is at out/processor.generator.cc_single_file/hello.elf.

Run again — the source hasn’t changed, so rsconstruct restores from cache:

Processing cc_single_file (1 product)
  Up to date

Customizing compiler flags

Pass flags via processor config:

[processor.generator.cc_single_file]
cflags = ["-Wall", "-Wextra", "-O2"]
cxxflags = ["-Wall", "-Wextra", "-O2"]
include_paths = ["include"]

See the CC Single File processor docs for the full configuration reference.

Adding static analysis

Install cppcheck and add a section for it:

[processor.generator.cc_single_file]

[processor.checker.cppcheck]

Both processors run on the same source files — rsconstruct handles them independently.

Next Steps

• Commands — full list of rsconstruct commands
• Configuration — all configuration options
• Processors — detailed docs for each processor

Binary Releases

RSConstruct publishes pre-built binaries as GitHub releases. A release is made with cargo release; CI builds and publishes the binaries from the release commit it pushes.

Supported Platforms

RSConstruct is unix-only. There is no Windows build: the release matrix in .github/workflows/ci.yml has never contained a Windows target, and the codebase assumes unix throughout (flock, /dev/null, $HOME, apt-based tool installation).

How It Works

Everything runs from the single CI workflow (.github/workflows/ci.yml). The workflow triggers on branch pushes only. Every push runs the test job; a push to the default branch whose commit message starts with chore: Release (the commit cargo release makes) also runs three release jobs:

1. build — a matrix job that builds the release binary for each platform and uploads it as a GitHub Actions artifact. It runs only after the test job passes, so a release never ships from a commit whose tests fail.
2. release — waits for all builds to finish, downloads the binary artifacts, and creates a GitHub release named after the version in Cargo.toml (v<version>), with auto-generated release notes and all binaries attached.
3. docs — builds the mdBook documentation and deploys it to GitHub Pages.

Pushing a tag on its own does nothing: cargo release pushes the tag together with the release commit, and the workflow ignores tag pushes so the two do not start two identical runs.

Creating a Release

cargo release patch            # dry run: shows what would happen
cargo release patch --execute  # bump, commit, tag, publish, push

Use minor or major instead of patch for a bigger bump. With --execute, cargo release (configured in release.toml):

1. bumps version in Cargo.toml,
2. commits it as chore: Release rsconstruct version <version>,
3. creates a signed tag v<version>,
4. publishes the crate to crates.io,
5. pushes the commit and the tag.

The push of that commit to the default branch starts the release jobs above. Bumping the version and tagging by hand does not produce a release, because the commit message would not start with chore: Release .

Release Profile

The binary is optimized for size and performance:

[profile.release]
strip = true        # Remove debug symbols
lto = true          # Link-time optimization across all crates
codegen-units = 1   # Single codegen unit for better optimization

Command Reference

A command that takes a subcommand (clean, cache, processor, …) lists its subcommands, each with a one-line description, when run without one, and exits with status 2. The listing leaves the flags out; --help shows them.

Global Flags

These flags can be used with any command:

Example:

rsconstruct --phases build                    # Show phase messages during build
rsconstruct --show-child-processes build      # Show each command being executed
rsconstruct --show-output build               # Show compiler/linter output even on success
rsconstruct --phases --show-child-processes build # Show both phases and commands
rsconstruct -O path build                     # Show output file paths in build messages
rsconstruct -I all build                      # Show all input files (including headers)
rsconstruct --all processor list              # Every column, Description included
rsconstruct --fields tool list                # The table's name and columns, no rows

Table columns

Every table a command prints has a name and a fixed set of columns, and some columns are hidden unless --verbose asks for them (processor list hides Description, hook hides Function and Location). Which columns show is decided in this order:

1. --fields: the table’s name, the command that prints it, and its column names, with no data rows. This is how to find the names for the next two.
2. --all: every column.
3. [tables] in the user config, ~/.config/rsconstruct/config.toml: exactly the columns listed there, in that order. See [tables] for the file format and the list of every table.
4. Otherwise the default: every column except the hidden ones, which --verbose adds back.

--all goes before the command name on tool install and tool list-configured, which have an --all of their own (rsconstruct --all tool list-configured). JSON output is not affected by any of this: --json always carries every field.

rsconstruct build

Requires config. (no subcommands)

Incremental build — only rebuilds products whose inputs have changed.

rsconstruct build                              # Incremental build
rsconstruct build --force                      # Force full rebuild
rsconstruct build -j4                          # Build with 4 parallel jobs
rsconstruct build --dry-run                    # Show what would be built without executing (honors -p/-x/-t)
rsconstruct build --keep-going                 # Continue after errors
rsconstruct build --timings                    # Show per-product and total timing info
rsconstruct build --stop-after discover        # Stop after product discovery
rsconstruct build --stop-after add-dependencies # Stop after dependency scanning
rsconstruct build --stop-after resolve         # Stop after graph resolution
rsconstruct build --stop-after classify        # Stop after classifying products
rsconstruct build --show-output                # Show compiler/linter output even on success
rsconstruct build --auto-add-words             # Add misspelled words to .zspell-words instead of failing
rsconstruct build --auto-add-words -p processor.checker.zspell   # Run only zspell and auto-add words
rsconstruct build -p processor.checker.ruff,processor.checker.pylint               # Run only specific processors
rsconstruct build --explain                    # Show why each product is skipped/restored/rebuilt
rsconstruct build --retry 3                    # Retry failed products up to 3 times
rsconstruct build --no-mtime                   # Disable mtime pre-check, always compute checksums
rsconstruct build --no-summary                 # Suppress the build summary
rsconstruct build --batch-size 10              # Limit batch size for batch-capable processors
rsconstruct build --verify-tool-versions       # Verify tool versions against .tools.versions
rsconstruct build -t "src/*.c"                 # Only build products matching this glob pattern
rsconstruct build -d src                       # Only build products under this directory
rsconstruct build --show-all-config-changes    # Show all config changes, not just output-affecting

By default, tool output (compiler messages, linter output) is only shown when a command fails. Use --show-output to see all output.

Selecting processors (-p, -x)

-p runs the named processors and the processors that generate their inputs, transitively — selecting a checker of generated files also runs the generator, so the checker has something to check even on a clean checkout. (-t/-d do the same for the products they select.)

-x excludes a processor, and with it every product that needs its outputs: those could only run against files nobody is producing. An excluded processor is never pulled back in, even when a -p selection depends on it.

Incremental recovery and batch behavior

Batch-capable processors run their rebuilding products in a single tool invocation, with or without --keep-going. A batch-capable checker waits until every one of its products is ready (its files that depend on a generated file included) and then runs once over all of them; a batch-capable generator’s products run as they become ready, since one of them may feed another. If the tool fails, all products in the batch are marked failed and must be rebuilt. Use --batch-size N to limit batch chunks and improve recovery granularity, or --batch-size -1 to run every product on its own; successfully completed products are cached as soon as their invocation finishes, so after a failure or an interruption the next run only rebuilds what wasn’t completed.

Processor Shortcuts (@ aliases)

The -p flag supports @-prefixed shortcuts that expand to groups of processors:

By type:

• @checker — all checker processors (ruff, pylint, shellcheck, etc.)
• @generator — all generator processors (tera, cc_single_file, etc.)
• @creator — all creator processors (pip, npm, cargo, etc.)
• @explicit — all explicit processors
• @mass_generator — all mass generator processors

By tool or name — any other @x selects both of these:

• every processor that requires tool x (@python3, @node; matched against each processor’s required_tools())
• every processor whose short name is x, with all its instances (@tera → processor.generator.tera and e.g. processor.generator.tera.docs; @generic → the generic processor of every type)

An @x that selects nothing is reported as an unknown processor.

Examples:

rsconstruct build -p @checker              # Run only checker processors
rsconstruct build -p @generator            # Run only generator processors
rsconstruct build -p @python3               # Run all Python-based processors
rsconstruct build -p @checker,tera         # Mix shortcuts with processor names

The --stop-after flag allows stopping the build at a specific phase:

• discover — stop after discovering products (before dependency scanning)
• add-dependencies — stop after adding dependencies (before resolving graph)
• resolve — stop after resolving the dependency graph (before execution)
• classify — stop after classifying products (show skip/restore/build counts)
• build — run the full build (default)

rsconstruct clean

Clean build artifacts. A subcommand is required; run without one, clean lists them.

Two nouns, two depths: clean outputs removes output files and keeps the cache, so the next build restores them; clean all removes outputs and cache. Both take -p to limit themselves to some processors, so clean all -p generator.tera removes everything of tera, files and cache entries, and the next build runs its products again.

rsconstruct clean                # List the subcommands
rsconstruct clean outputs        # Remove build output files (preserves cache)
rsconstruct clean outputs -p generator.tera,generator.tags    # Only clean outputs of these processors
rsconstruct clean outputs --no-empty-dirs # Skip the empty-directory sweep
rsconstruct clean all            # Remove out/ and .rsconstruct/ directories
rsconstruct clean all -p generator.tera   # tera's files and cache entries; re-rendered next build
rsconstruct clean all -p @checker         # Forget every check; all lint runs again
rsconstruct clean all -p mass_generator.linux_module --dry-run   # Show what would go
rsconstruct clean git            # Hard clean using git clean -qffxd (requires git repository)
rsconstruct clean unknown        # Remove files not tracked by git and not known as build outputs
rsconstruct clean unknown --dry-run      # Show what would be removed without deleting
rsconstruct clean unknown --no-gitignore # Include gitignored files as unknown

rsconstruct clean outputs

Removes build output files. The cache (.rsconstruct/) is preserved.

What gets removed depends on each product’s processor type:

• Checkers (ruff, cppcheck, shellcheck, terms, …) — produce no outputs, so nothing to delete.
• Generators (tera, tags, mako, jinja2, mermaid, pdflatex, pdfunite, …) — declare concrete output files. Each declared output file is removed individually with fs::remove_file. Directories are never recursed into.
• Creators (mdbook, jekyll, cargo, npm, gem, cc, …) — invoke an external build that produces an unknown set of files inside a declared output directory (e.g. book/, _site/, target/). The whole declared output_dir is removed recursively. This is the only path that recursively deletes a directory, and it only ever affects directories the creator itself declared.
• Explicit — declares both output_files and output_dirs directly in rsconstruct.toml. Files are removed individually; declared output_dirs are removed recursively (because the user asked for that).
• Mass generators — every file the tool’s plan predicted is a declared output and is removed individually. The output_dirs a mass generator declares only bound where predicted files may live and are never removed.

Empty-directory sweep

After every product’s clean() has run, clean outputs walks every directory that previously contained an output file (and the parents of every removed output_dir), bottom-up, and removes any that are now empty. The sweep:

• Tries fs::remove_dir (non-recursive) — only succeeds when the directory is empty.
• Walks upward through parents until it hits a non-empty directory or the project root.
• Never removes a directory that still contains files — empty dirs only.
• Does not special-case out/. Any path ancestor of a cleaned output is eligible.

Pass --no-empty-dirs to skip the sweep entirely. Files still get cleaned; empty parent directories are left in place.

Filtering by processor

-p / --processor takes a comma-separated list of the same selectors as build -p: a processor name with or without the processor. prefix (generator.tera, as the tables print it), an instance name (generator.marp.slides), @checker for a type, @python3 for every processor that needs a tool, @tera for a short name with all its instances. A selector that matches nothing is an error listing the processors in the config. Only the selected processors’ products are cleaned.

rsconstruct clean all

Without -p, removes the output directory (out/ by default) and .rsconstruct/ outright: every output and the whole cache. With -p, removes everything of the selected processors only: their output files, as clean outputs does, and the cache entries for their products, so the next build runs them again instead of restoring them. Use the -p form to make one processor redo its work without touching the rest of the cache:

rsconstruct clean all                              # everything
rsconstruct clean all -p generator.tera            # everything of tera
rsconstruct clean all -p @checker --dry-run        # what would go

• -p takes the selectors described under Filtering by processor.
• --dry-run names the directories (without -p) or counts the files, output directories and cache entries (with -p; --verbose lists the files) that would go, and removes nothing.
• --no-empty-dirs skips the empty-directory sweep of the -p form, as for clean outputs.

With -p, the cache entry removed is the one for each product’s current inputs, the key the next build would look up. Entries left over from earlier inputs are what cache remove-stale removes, and the blobs they point at are what cache trim removes; clean all -p touches neither. Products downstream of a cleaned one are not cleaned: they run again on the next build if the regenerated output differs, and are rightly skipped if it is byte-identical. With a remote cache and pull enabled, the next build may still restore from the remote.

clean all -p replaced the clean products subcommand of 0.9.133.

Other clean variants

• clean all — removes out/ and .rsconstruct/ outright (cache included). Use when you want a full reset.
• clean git — runs git clean -qffxd. Requires a git repository.
• clean unknown — finds files in the working tree that are neither git-tracked nor declared as a build output, and deletes them. Pass --dry-run to only list them. --no-gitignore includes gitignored files in the search.

rsconstruct status

Requires config. (no subcommands)

Show product status — whether each product is up-to-date, stale, or restorable from cache.

rsconstruct status                     # Show per-processor and total summary
rsconstruct status -v                  # Show per-product status
rsconstruct status --breakdown         # Show source file counts by processor and extension
rsconstruct --json status              # Same summary as JSON

The per-processor table (and each entry of --json’s processor array) carries two flags after the counts: native, whether the processor is pure Rust inside rsconstruct, and rust, whether the code that does the work is written in Rust at all — always so for a native processor, and for an external one only when the tool it runs is (ruff, taplo, rumdl, clippy, cargo, mdbook, pyrefly, rustc). Processors that run a user-supplied command (script, explicit, generator, creator, mass_generator) report rust: false, since the language is unknown.

rsconstruct smart auto

Auto-detect relevant processors and add them to rsconstruct.toml. Scans the project for files matching each processor’s conventions and checks that the required tools are installed. Only adds new sections — existing processor sections are preserved. Requires config.

rsconstruct smart auto

Example output:

Added 3 processor(s): pylint, ruff, shellcheck

rsconstruct init

No config needed. (no subcommands)

Initialize a new rsconstruct project in the current directory.

rsconstruct init

rsconstruct watch

Requires config. (no subcommands)

Watch source files and auto-rebuild on changes.

rsconstruct watch                              # Watch and rebuild on changes
rsconstruct watch --auto-add-words             # Watch with zspell auto-add words
rsconstruct watch -j4                          # Watch with 4 parallel jobs
rsconstruct watch -p processor.checker.ruff                      # Watch and only run the ruff processor

The watch command accepts the same build flags as rsconstruct build (e.g., --jobs, --keep-going, --timings, --processor, --batch-size, --explain, --retry, --no-mtime, --no-summary).

rsconstruct graph

Display the build dependency graph.

rsconstruct graph show                    # Default SVG format
rsconstruct graph show --format dot       # Graphviz DOT format
rsconstruct graph show --format mermaid   # Mermaid format
rsconstruct graph show --format json      # JSON format
rsconstruct graph show --format text      # Plain text hierarchical view
rsconstruct graph show --format svg       # SVG format (requires Graphviz dot)
rsconstruct graph view                    # Open as SVG (default viewer)
rsconstruct graph view --viewer mermaid   # Open as HTML with Mermaid in browser
rsconstruct graph view --viewer svg       # Generate and open SVG using Graphviz dot
rsconstruct graph stats                   # Show graph statistics (products, processors, dependencies)

rsconstruct cache

Manage the build cache.

rsconstruct cache clear         # Clear the entire cache
rsconstruct cache size          # Show cache size
rsconstruct cache trim          # Remove unreferenced objects
rsconstruct cache list          # List all cache entries and their status
rsconstruct cache stale         # Show which cache entries are stale vs current
rsconstruct cache stats         # Show per-processor cache statistics
rsconstruct cache remove-stale  # Remove stale index entries not matching any current product

rsconstruct webcache

Manage the web request cache. Schemas fetched by iyamlschema (and any future processors that fetch URLs) are cached in .rsconstruct/webcache.redb.

rsconstruct webcache clear   # Clear all cached web responses
rsconstruct webcache stats   # Show cache size and entry count
rsconstruct webcache list    # List all cached URLs and their sizes

rsconstruct analyzer

Manage dependency analyzers and inspect the dependency cache they fill. An analyzer scans source files for dependencies (C/C++ #includes, Python imports, Sass @uses, Markdown and Tera references) and records them in .rsconstruct/deps.redb; see Dependency Analyzers. Analyzers are referred to by pname (the type: cpp, icpp, markdown, python, sass, tera) or by iname (the instance as declared in rsconstruct.toml, e.g. cpp or cpp.kernel).

rsconstruct analyzer list                        # List all available analyzers
rsconstruct analyzer used                        # Show which analyzers are enabled and detected
rsconstruct analyzer defconfig cpp               # Show the default configuration of an analyzer type
rsconstruct analyzer config                      # Show the resolved configuration of every declared analyzer
rsconstruct analyzer config cpp                  # ...of one analyzer instance
rsconstruct analyzer add cpp                     # Append [analyzer.cpp] to rsconstruct.toml with comments
rsconstruct analyzer add cpp --dry-run           # Print the snippet instead of writing it
rsconstruct analyzer enable cpp                  # Set enabled = true on the stanza
rsconstruct analyzer disable cpp                 # Set enabled = false on the stanza
rsconstruct analyzer delete cpp                  # Remove the stanza entirely
rsconstruct analyzer build                       # Run dependency analysis without building
rsconstruct analyzer show all                    # Show all cached dependencies
rsconstruct analyzer show files src/main.c       # Show dependencies for a specific file
rsconstruct analyzer show files src/a.c src/b.c  # ...for several files
rsconstruct analyzer show files --hash-pieces src/main.c  # Also show each analyzer's hash pieces
rsconstruct analyzer show analyzers cpp          # Show dependencies found by the C/C++ analyzer
rsconstruct analyzer show analyzers cpp python   # ...by several analyzers
rsconstruct analyzer stats                       # Show statistics by analyzer
rsconstruct analyzer clean                       # Clear the entire dependency cache
rsconstruct analyzer clean --analyzer cpp        # Clear only entries from the cpp analyzer

Example output for rsconstruct analyzer show all:

src/main.c: [icpp] (no dependencies)
src/test.c: [icpp]
  src/utils.h
  src/config.h

Example output for rsconstruct analyzer stats:

╭──────────┬───────┬──────────────╮
│ Analyzer │ Files │ Dependencies │
├──────────┼───────┼──────────────┤
│ icpp     │ 2     │ 2            │
├──────────┼───────┼──────────────┤
│ Total    │ 2     │ 2            │
╰──────────┴───────┴──────────────╯

show, stats and clean read the dependency cache directly. If it is empty, run rsconstruct analyzer build (or a build) first to populate it.

These commands are useful for:

• Debugging why a file is being rebuilt
• Understanding the include/import structure of your project
• Verifying that dependency analyzers are finding the right files
• Clearing dependencies for a specific analyzer without affecting others

rsconstruct smart

Smart config manipulation commands for managing processor sections in rsconstruct.toml.

rsconstruct smart enable pylint          # Add [processor.checker.pylint] section
rsconstruct smart disable pylint         # Remove [processor.checker.pylint] section
rsconstruct smart enable-all             # Add sections for all builtin processors
rsconstruct smart disable-all            # Remove all processor sections
rsconstruct smart enable-detected        # Add sections for auto-detected processors
rsconstruct smart enable-if-available    # Add sections for detected processors with tools installed
rsconstruct smart minimal                # Remove all, then add only detected processors
rsconstruct smart only ruff pylint       # Remove all, then add only listed processors
rsconstruct smart reset                  # Remove all processor sections
rsconstruct smart remove-no-file-processors  # Remove processors that don't match any files (skips enabled = false)

rsconstruct processor

rsconstruct processor list              # List all built-in processors with type and description
rsconstruct processor list --type checker  # ...only one processor type
rsconstruct --json processor list       # Same list as JSON
rsconstruct processor info processor.checker.ruff         # Describe a processor and every config field
rsconstruct processor info              # ...every processor
rsconstruct --json processor info       # Same as JSON
rsconstruct processor types             # List the processor types
rsconstruct processor search yaml       # Search processors by name, description or keywords
rsconstruct processor recommend         # Show the recommended processor for each file extension
rsconstruct processor used              # Show which processors are enabled and detected
rsconstruct processor names             # Print the iname of every enabled processor, one per line
rsconstruct processor files             # Show source and target files for each declared processor
rsconstruct processor files processor.checker.ruff        # Show files for a specific processor
rsconstruct processor config processor.checker.ruff       # Show resolved configuration for a processor
rsconstruct processor config --diff     # Show only fields that differ from defaults
rsconstruct processor defconfig processor.checker.ruff    # Show default configuration for a processor
rsconstruct processor add processor.checker.ruff          # Append [processor.checker.ruff] to rsconstruct.toml (fields pre-populated + comments)
rsconstruct processor add processor.checker.ruff --dry-run  # Preview the snippet without writing
rsconstruct processor enable processor.checker.ruff       # Set enabled = true on the stanza
rsconstruct processor disable processor.checker.ruff      # Set enabled = false on the stanza
rsconstruct processor delete processor.checker.ruff       # Remove the stanza entirely
rsconstruct processor allowlist         # Show the current processor allowlist
rsconstruct processor graph             # Show inter-processor dependencies
rsconstruct processor graph --format dot    # Graphviz DOT format
rsconstruct processor graph --format mermaid # Mermaid format
rsconstruct processor files --headers   # Show files with processor headers

list prints one row per processor with its type and four flags: Native (pure Rust inside rsconstruct, or external when it runs another program), Rust (whether the code that does the work is written in Rust — every native processor, plus external ones whose tool is Rust: ruff, taplo, rumdl, clippy, cargo, mdbook, pyrefly, rustc), Batch (whether the processor can take several input files in one tool invocation — a linter that accepts a file list can, a converter that writes one output per input such as pandoc or marp cannot) and Cache (whether a cache hit stands in for a run: it restores a generator’s outputs or proves a checker’s pass, so nothing is lost by skipping the run; No for pip, npm and gem, which install into an environment and write only a stamp — the stamp is cached while the installed packages may be gone). The JSON form carries the same as native, rust, supports_batch and caches_outputs booleans. rust is what to read when the question is “how much of this project’s toolchain is Rust”; native is what to read when the question is “which processors need no tool installed”; supports_batch is what decides whether a stanza’s batch field and the build’s --batch-size have any effect on it (a processor that cannot batch runs one file per invocation whatever they say).

In every table, processor names drop the processor. prefix that all of them carry (checker.ruff, not processor.checker.ruff): it says nothing in a column of processors and costs a word of width on every row. JSON output, error messages and processor info keep the full name, which is what rsconstruct.toml and scripts use.

A fifth column, Rust alternative, names the Rust processors that can replace a non-Rust one (ishellcheck for shellcheck, iluacheck and selene for luacheck); the JSON form has them as a rust_alternatives array, empty where there is none. Each Rust processor declares what it replaces in its own file, and its alternative’s docs page links it.

recommend maps file extensions to the processor for them. Where a Rust processor can replace the classic recommendation, the Rust one is listed and the classic one moves to the Also column (also in the JSON, next to processors, every Rust option, and processor, the first of them).

info is the long form of one processor (or, without a name, of every processor): its description, type, keywords, the same flags as list, the max_jobs cap and the implementation version, then a table of every config field it accepts — type, default, whether it is required, whether it is part of the cache key (Checksum), and what it does. It is defconfig -v with the processor’s own description on top, and reads only the processors’ built-in metadata, so it needs no rsconstruct.toml.

rsconstruct tool

List or check external tools required by declared processors. All subcommands use config if available; without config, they operate on all built-in processors.

rsconstruct tool list              # List all tools known to rsconstruct (from the central registry)
rsconstruct tool list -M           # ...with every install method for each tool
rsconstruct tool list-configured   # List tools this project's processors require, and which needs them
rsconstruct tool list-configured -a   # Include tools from disabled processors
rsconstruct tool check             # Verify tool versions against .tools.versions lock file
rsconstruct tool lock              # Lock tool versions to .tools.versions
rsconstruct tool install           # Install missing external tools for enabled processors
rsconstruct tool install ruff      # Install a specific tool by name
rsconstruct tool install --all     # Install every tool in the registry, ignoring the config (no config needed)
rsconstruct tool install -i        # Ask for confirmation first (default: install without asking)
rsconstruct tool install --no-eatmydata        # Don't wrap apt/dnf/pacman with eatmydata
rsconstruct tool install-deps      # Install declared [dependencies] (pip set from uv.lock, npm set from package-lock.json by default) in fixed order: system → pip → npm → gem → cargo
rsconstruct tool install-deps -i   # Ask for confirmation first (default: install without asking)
rsconstruct tool install-deps --no-eatmydata   # Don't wrap apt/dnf/pacman with eatmydata
rsconstruct tool stats             # Show tool availability and language runtime breakdown
rsconstruct tool stats --json      # Show tool stats in JSON format
rsconstruct tool graph             # Show tool-to-processor dependency graph (DOT format)
rsconstruct tool graph --format mermaid  # Mermaid format
rsconstruct tool graph --view      # Open tool graph in browser

install --all walks the central registry instead of the project config, so it needs no rsconstruct.toml. It never skips: a tool with no automatable install method is a hard error, not a warning. This makes it the intended way to provision CI — one command covers the whole matrix, and a registry entry that loses its install method fails the provisioning step instead of quietly shrinking the matrix. --all cannot be combined with a tool name.

Ruby gems without a writable gem dir

Only system package managers (apt/dnf/pacman/snap) are sudo-wrapped; pip, npm, cargo, and gem run unprivileged. With a distro ruby, that would make gem install die on the root-owned system gem dir (/var/lib/gems on Debian/Ubuntu), so when the default gem dir isn’t writable, gem installs get --user-install appended automatically. To make the resulting executables resolvable, every rsconstruct invocation appends the user gem bin dirs that exist ($GEM_HOME/bin, ~/.gem/ruby/*/bin, ~/.local/share/gem/ruby/*/bin) to its own PATH at startup — tool probes and spawned processors see them without any workflow- or shell-level GEM_HOME/PATH setup.

Node.js packages from the project’s node_modules

The same startup step prepends the project’s node_modules/.bin, when it exists, so the packages install-deps put there from package.json (with npm ci, see [dependencies] in the configuration reference) resolve ahead of any global copy. tool install therefore finds a locked tool already installed and does not add a global one on top.

rsconstruct tag

Search and query frontmatter tags from markdown files.

rsconstruct tag list                        # List all unique tags
rsconstruct tag count                       # Show each tag with file count, sorted by frequency
rsconstruct tag tree                        # Show tags grouped by prefix/category
rsconstruct tag stats                       # Show statistics about the tags database
rsconstruct tag files docker                # List files matching a tag (AND semantics)
rsconstruct tag files docker --or k8s       # List files matching any tag (OR semantics)
rsconstruct tag files level:advanced        # Match key:value tags
rsconstruct tag grep deploy                 # Search for tags containing a substring
rsconstruct tag grep deploy -i              # Case-insensitive tag search
rsconstruct tag for-file src/main.md        # List all tags for a specific file
rsconstruct tag frontmatter src/main.md     # Show raw frontmatter for a file
rsconstruct tag validate                    # Validate tags against tags_dir allowlist
rsconstruct tag unused                      # List tags in tags_dir not used by any file
rsconstruct tag unused --strict             # Exit with error if unused tags found (CI)
rsconstruct tag check                       # Run all tag validations without building
rsconstruct tag suggest src/main.md         # Suggest tags for a file based on similarity
rsconstruct tag coverage                    # Show percentage of files with each tag category
rsconstruct tag matrix                      # Show coverage matrix of tag categories per file
rsconstruct tag orphans                     # Find markdown files with no tags
rsconstruct tag merge ../other/tags         # Merge tags from another project
rsconstruct tag collect                     # Add missing tags from source files to tag collection

rsconstruct complete

Generate shell completions. No config needed when shell is specified as argument; uses config to read default shells if no argument given.

rsconstruct complete bash    # Generate bash completions
rsconstruct complete zsh     # Generate zsh completions
rsconstruct complete fish    # Generate fish completions

rsconstruct term

Manage term checking and fixing in markdown files.

rsconstruct term fix

Add backticks around terms from the terms directory that appear unquoted in markdown files.

rsconstruct term fix
rsconstruct term fix --remove-non-terms   # also remove backticks from non-terms

rsconstruct term merge

Merge terms from another project’s terms directory. Unions matching files and copies missing files in both directions.

rsconstruct term merge ../other-project/terms

rsconstruct doctor

Requires config. (no subcommands)

Diagnose build environment — checks config, tools, versions, and declared [dependencies] (Python deps declared in pyproject.toml are checked too; see the [dependencies] section in Configuration). Tools are probed by running them; system dependencies are packages, not tools, so they are probed through the platform’s package manager (dpkg-query/rpm/pacman/brew) — a binary-less package like aspell-en counts as installed even though no binary carries its name.

rsconstruct doctor

rsconstruct info

Show project information.

rsconstruct info source          # Show source file counts by extension

rsconstruct page

Query GitHub Pages publishing settings from the [pages] config section.

rsconstruct page dir            # Print the published directory ([pages].dir)
rsconstruct --json page dir      # {"configured": true, "dir": "out/web"}

page dir prints nothing and still exits 0 when [pages] is not configured — CI branches on the output being empty, not on exit codes. See GitHub Actions for the workflow pattern this enables.

rsconstruct sloc

No config needed. (no subcommands)

Count source lines of code (SLOC) by language, with optional COCOMO effort/cost estimation.

rsconstruct sloc                 # Show SLOC by language
rsconstruct sloc --cocomo        # Include COCOMO effort/cost estimation
rsconstruct sloc --cocomo --salary 80000  # Custom annual salary for COCOMO

rsconstruct toml

rsconstruct toml check   # validate rsconstruct.toml (unknown fields, types, required fields)
rsconstruct toml files   # list every config file rsconstruct may read and whether it exists

toml files needs no config. It prints the merge chain lowest precedence first — the user config ($XDG_CONFIG_HOME/rsconstruct/config.toml, see User config), rsconstruct.toml and rsconstruct.local.toml — followed by the other project files rsconstruct reads (.rsconstructignore, .tools.versions), each with its resolved path and whether it is present. Use it to find out which file a setting is coming from, or where the user config lives on a given machine. With --json the same list is emitted as an array of {precedence, role, path, exists, note} objects.

rsconstruct error

No config needed. (no subcommands)

List every exit code rsconstruct can return and its name. Errors are printed as Error [EXIT_...]: ..., so the name in a message maps back to the code here.

rsconstruct error

rsconstruct function

No config needed.

Inspect the built-in functions rsconstruct exposes to Tera templates (load_python, load_lua, load_toml, toml_get, …).

rsconstruct function list   # Signature, return value, dependency tracking and an example for each function

Example entry:

load_toml(path: string)
  Parse a TOML file and expose its top-level table to the template.
  returns:       object (key → value, nested tables preserved)
  dep tracking:  The file at `path` is added as an input (content-tracked).
  example:       {% set cfg = load_toml(path="pyproject.toml") %}{{ cfg.project.version }}

rsconstruct hook

No config needed. (no subcommands)

List the post-config hooks: built-in adjustments applied to the configuration after it is loaded, such as defaults that change when running under CI (CI=true).

rsconstruct hook

╭──────────────────────┬─────────────────────────────────────────────────────────────────────╮
│ Hook                 │ Description                                                         │
├──────────────────────┼─────────────────────────────────────────────────────────────────────┤
│ eatmydata_ci_default │ When CI=true, enable eatmydata wrapping for apt/dnf/pacman installs │
│ marp_ci_cap          │ When CI=true and marp.max_jobs is unset, cap it at 2                │
╰──────────────────────┴─────────────────────────────────────────────────────────────────────╯

rsconstruct product

Requires config.

Inspect a single product in the build graph: everything that goes into its cache key and whether it would be rebuilt. Use it to answer “why is this file rebuilding?”.

rsconstruct product show out/processor.generator.cc_single_file/src/main.elf  # By output path
rsconstruct product show src/main.c                                            # By primary input

The path is looked up as an output first; if no product owns it, products that have it as their primary input are shown. Example output:

processor: processor.generator.cc_single_file
outputs:
  out/processor.generator.cc_single_file/src/test.elf
inputs:
  primary src/test.c
  analyzer [icpp]
    src/utils.h
    src/config.h
cache_key: 7b1eccc2...
  config b884aa0c...
  tool 2a4d5d7d...
hash_pieces: (none)
input_checksum: 71e9982e...
descriptor_key: 8c2a5920...
cache_state: BUILD (no cache entry)

rsconstruct symlink-install

Requires config. (no subcommands)

Symlink every file under one or more source folders into target folders, recreating the directory structure. Configure the folder pairs in rsconstruct.toml; sources[i] is installed into targets[i], so both arrays must have the same length. A leading ~/ in a target is expanded to $HOME.

[command.symlink_install]
sources = ["dotfiles", "bin"]
targets = ["~/", "~/.local/bin"]

rsconstruct symlink-install

dotfiles → /home/user/
  created .bashrc
  created .config/git/config
Symlink install: 2 created, 0 updated, 0 unchanged

Each link points to the absolute path of the source file. Running it again is safe: links that already point to the right file are left alone (unchanged), and links pointing elsewhere are replaced (updated). A regular file at a target path is deleted and replaced by the link, so make sure the target folders hold nothing you want to keep under the same names.

rsconstruct version

No config needed. (no subcommands)

Print version information.

rsconstruct version

Shell Completions

RSConstruct generates shell completion scripts that provide tab-completion for commands, subcommands, flags, and argument values.

Generating Completions

# Generate for the default shell (configured in rsconstruct.toml)
rsconstruct complete

# Generate for a specific shell
rsconstruct complete bash
rsconstruct complete zsh
rsconstruct complete fish

To install, source the output in your shell profile:

# Bash (~/.bashrc)
eval "$(rsconstruct complete bash)"

# Zsh (~/.zshrc)
eval "$(rsconstruct complete zsh)"

# Fish (~/.config/fish/config.fish)
rsconstruct complete fish | source

Configuration

The default shell(s) for rsconstruct complete (with no argument) are configured in rsconstruct.toml:

[completions]
shells = ["bash"]

What Gets Completed

Commands and subcommands

All top-level commands (build, processor, analyzer, config, etc.) and their subcommands complete automatically via clap.

Processor type names (pnames)

These commands complete with processor type names from the plugin registry (e.g., ruff, pylint, cc_single_file):

• rsconstruct processor defconfig <TAB>
• rsconstruct build --processor <TAB> / rsconstruct build -p <TAB>
• rsconstruct watch --processor <TAB> / rsconstruct watch -p <TAB>

The list is drawn from the plugin registry at compile time.

Processor instance names (inames)

These commands complete with instance names declared in the current project’s rsconstruct.toml (e.g., pylint, pylint.tests, cc_single_file):

• rsconstruct processor config <TAB>
• rsconstruct processor files <TAB>

Instance names are extracted from [processor.TYPE.NAME] and [processor.TYPE.NAME.INSTANCE] headings in rsconstruct.toml at tab-completion time. Requires a project config in the current directory. Bash only.

Analyzer names

These commands complete analyzer names (every registered analyzer, as listed by rsconstruct analyzer list):

• rsconstruct analyzer config <TAB>
• rsconstruct analyzer clean --analyzer <TAB>

Analyzer names are specified via clap’s value_parser attribute, so they work in all shells without post-processing.

Flags and options

All --flags and -f short flags complete in all shells via clap’s built-in generation.

Implementation

Completions are generated by clap_complete in src/cli.rs. Two mechanisms provide argument-value completions:

1. clap value_parser (preferred)

For arguments with a small, fixed set of values, use #[arg(value_parser = [...])] on the field. This works in all shells automatically because clap embeds the values in the generated script.

Example from AnalyzersAction::Config:

#![allow(unused)]
fn main() {
#[arg(value_parser = ["cpp", "markdown", "python", "tera"])]
name: Option<String>,
}

2. Bash post-processing (processor names)

Processor names are not known to clap at derive time because they come from the inventory plugin registry. The function inject_bash_processor_completions() post-processes the generated bash script to inject processor names into the opts variable for specific command sections.

This only works for bash. Other shells get the base clap completions without processor name injection.

The targets for injection are identified by their case labels in the generated bash script:

• rsconstruct__processor__config)
• rsconstruct__processor__defconfig)
• rsconstruct__processor__files)

The function also patches --processor / -p flag completions in build and watch commands to suggest processor names instead of file paths.

Adding Completions for New Arguments

• Fixed set of values (analyzer names, enum variants): Use #[arg(value_parser = [...])]. Works in all shells.
• Dynamic set from registry (processor names): Add the case label to inject_bash_processor_completions() targets. Only works in bash.
• Enum types: Use #[arg(value_enum)] on a clap-derived enum. Works in all shells.

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. An optional user-level file can set [build] defaults underneath both and choose the columns the CLI’s tables show — see User config.

Full reference

[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]
pip = ["pyyaml", "jinja2"]    # Python packages
npm = ["eslint", "prettier"]  # Node.js packages
gem = ["mdl"]                 # Ruby gems
cargo = ["cargo-deny"]        # Crates from crates.io (cargo install --locked)
system = ["pandoc", "graphviz"]  # System packages (checked but not auto-installed)

[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.

Processor instances

Processors are declared by adding a [processor.TYPE.NAME] section to rsconstruct.toml. An empty section enables the processor with default settings:

[processor.checker.pylint]

Customize with config fields:

[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:

[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, creator, explicit, mass_generator and lua; the name is unique only within its type, which is why the config-driven processors share one name: processor.creator.generic, 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 creator 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). The full-name scheme is a one-shot, mechanical rewrite of every rsconstruct.toml:

scripts/migrate_processor_names.py in the rsconstruct repository performs the rewrite for one or more repositories (python3 scripts/migrate_processor_names.py ~/git/*/rsconstruct.toml): it renames every section header, rewrites out/<name> references to processors whose default output directory moved, and reports any other file in the repository that still mentions an old out/<name> path, so Makefiles and CI that point into out/ can be fixed by hand. It asks the installed rsconstruct processor list --json which type each name has, so it needs a rsconstruct that already speaks full names. 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 missed file fails loudly rather than silently building nothing.

Every cache entry is keyed by the processor name, so the first build after migrating rebuilds everything 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:

[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); 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] 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:

# ~/.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.

# ~/.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:

Section details

[build]

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 and 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, creator, 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:

Processor-specific fields are documented on each processor’s page under Processors.

[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]

[graph]

[completions]

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:

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 rsconstruct tool install-deps to install missing packages.

Python dependencies come from uv.lock by default

In the default pip_source = "uv-lock" mode, install-deps and doctor take the Python package set from uv.lock: the exact pinned closure — including transitive dependencies — that uv lock resolved, so CI installs are reproducible instead of floating to whatever pip resolves that day. Only registry packages are read from the lock; the project’s own entry is skipped, and any other source kind (git, path) is an error. A project whose pyproject.toml declares Python dependencies but has no uv.lock is an error: run uv lock, or opt out per repo with pip_source = "pyproject".

In pip_source = "pyproject" mode the set is instead the dependency names pyproject.toml declares, resolved by pip at install time:

• [project].dependencies
• every list in [project.optional-dependencies]
• every PEP 735 [dependency-groups] list (entries that are {include-group = "..."} tables are skipped, since every group is read anyway)

In both modes [dependencies].pip entries merge in front and the result is deduplicated by PEP 503-normalized distribution name plus extras, so a [dependencies].pip entry wins over a lock or pyproject one. Use [dependencies].pip for repos without a pyproject.toml and for packages CI needs that the project itself does not declare.

uv installs the Python set by default

With the default python_installer = "uv", install-deps hands the Python set to uv pip install --python python3 — targeting whichever interpreter python3 on PATH resolves to, the same environment a bare pip install would touch. Installing a uv-produced lock with uv matters for two reasons:

• Requires-Python upper bounds. uv deliberately ignores a package’s declared upper Requires-Python bound when resolving (upper bounds are almost always stale metadata), so uv lock can pin a version whose bound excludes the running interpreter. uv installs that pin; pip enforces the bound and refuses it with “No matching distribution found”.
• Environment markers. In uv-lock mode the pins come from uv export (run with --frozen, so an out-of-sync lock is an error, not a silent re-resolve), which annotates platform-conditional packages with markers like pywin32==312 ; sys_platform == 'win32'. uv skips a pin whose marker does not match the current platform, where the flattened lock closure would ask for another platform’s package and fail.

uv also audits the whole installed set itself in one pass, so uv mode skips the per-package pip show preflight probing.

When uv is not on PATH and there is Python work to do, install-deps bootstraps it with pip install uv first — CI runner images ship pip but not necessarily uv, and the consuming repo’s workflow should not need to know which installer rsconstruct uses.

Set python_installer = "pip" to keep the pre-uv behavior: per-package pip show probing followed by pip install of the flattened set.

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, install-deps 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 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 sees the locked copy and does not install a global one. This is what npm run does for scripts.

[dependencies].npm remains for a package that must be global; it is installed with npm install -g alongside, and is not the place for a project’s own tools.

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. install-deps installs the missing ones in one cargo install --locked call: --locked builds each crate with the Cargo.lock it was published with, so a given crate version yields the same binary everywhere, while the version itself floats to the latest release — the manifest carries bare names, as everywhere else in the fleet.

Presence is judged by cargo install --list, by crate name, not by a binary on PATH. That is exact (a crate’s binary need not carry its name: ripgrep ships rg) and it is cheap, where an unconditional cargo install would rebuild every crate that has a newer release on each run. The flip side is that a binary obtained any other way — a prebuilt tarball, a distro package — is not in the listing and is treated as missing; the install passes --force so such a binary is replaced rather than refused with “binary already exists in destination” (a CI cache holding a prebuilt nextest did exactly that). doctor reports each declared crate the same way.

Components rustup manages (rustfmt, clippy) are not crates and do not belong in this list.

Install order

rsconstruct tool install-deps always installs in this fixed order:

1. system — OS packages (apt, dnf, pacman, brew)
2. pip — Python packages
3. npm — Node.js packages (the global npm list, then the project’s npm ci)
4. gem — Ruby gems
5. cargo — crates from crates.io

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 via pip 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 pip install runs. Running pip (or gem, or npm) before system causes wheel/extension builds to fail with messages like Package 'pangocairo' was not found.

The keys inside [dependencies] may appear in any order in rsconstruct.toml; the install order is enforced by install-deps regardless.

eatmydata wrapping

When eatmydata is installed on the system and CI=true is in the environment, both rsconstruct tool install and rsconstruct tool install-deps wrap their 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

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: 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 for the workflow pattern.

[command.symlink_install]

Configures 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.

Remote Caching

RSConstruct supports sharing build artifacts across machines via remote caching. When enabled, build outputs are pushed to a remote store and can be pulled by other machines, avoiding redundant rebuilds.

Configuration

Add a remote URL to your [cache] section in rsconstruct.toml:

[cache]
remote = "s3://my-bucket/rsconstruct-cache"

Supported Backends

Amazon S3

[cache]
remote = "s3://bucket-name/optional/prefix"

Requires:

• AWS CLI installed (aws command)
• AWS credentials configured (~/.aws/credentials or environment variables)

The S3 backend uses aws s3 cp and aws s3 ls commands.

HTTP/HTTPS

[cache]
remote = "http://cache-server.example.com:8080/rsconstruct"
# or
remote = "https://cache-server.example.com/rsconstruct"

Requires:

• curl command
• Server that supports GET and PUT requests

The HTTP backend expects:

• GET /path to return the object or 404
• PUT /path to store the object
• HEAD /path to check existence (returns 200 or 404)

Local Filesystem

[cache]
remote = "file:///shared/cache/rsconstruct"

Useful for:

• Network-mounted filesystems (NFS, CIFS)
• Testing remote cache behavior locally

Control Options

You can control push and pull separately:

[cache]
remote = "s3://my-bucket/rsconstruct-cache"
remote_push = true   # Push local builds to remote (default: true)
remote_pull = true   # Pull from remote on cache miss (default: true)

Pull-only mode

To share a read-only cache (e.g., from CI):

[cache]
remote = "s3://ci-cache/rsconstruct"
remote_push = false
remote_pull = true

Push-only mode

To populate a cache without using it (e.g., in CI):

[cache]
remote = "s3://ci-cache/rsconstruct"
remote_push = true
remote_pull = false

How It Works

Cache Structure

Remote cache stores two types of objects, mirroring the local layout:

1. Descriptors at descriptors/{descriptor_key}

   • JSON describing what a product build produced: a marker (a check passed), a blob (one output), or a tree (a list of output paths and their content checksums)
   • One entry per product build — see Cache keys

2. Objects at objects/{xx}/{rest_of_checksum}

   • Content-addressed storage (like git)
   • Actual file contents identified by SHA-256

On Build

1. RSConstruct computes the cache key and input checksum

2. Checks local cache first

3. If local miss and remote_pull = true:

   • Fetches the descriptor from remote (and caches it locally)
   • Fetches the objects the descriptor names
   • Restores outputs locally

   Fetched objects are verified against their checksum before being admitted to the local content-addressed store, and fetched descriptors must parse; a corrupt remote cannot poison the local cache. A remote miss, or an unreachable remote, simply degrades to a local rebuild.

4. If rebuild required:

   • Executes the processor
   • Stores outputs in local cache
   • If remote_push = true, pushes the objects and the descriptor to remote

Cache Hit Flow

Local cache hit → Restore from local → Done
       ↓ miss
Remote cache hit → Download descriptor + objects → Restore → Done
       ↓ miss
Execute processor → Cache locally → Push to remote → Done

Best Practices

CI/CD Integration

In your CI pipeline:

# .github/workflows/build.yml
env:
  AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
  AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

steps:
  - run: rsconstruct build

Separate CI and Developer Caches

Use different prefixes to avoid conflicts:

# CI: rsconstruct.toml.ci
[cache]
remote = "s3://cache/rsconstruct/ci"
remote_push = true
remote_pull = true

# Developers: rsconstruct.toml
[cache]
remote = "s3://cache/rsconstruct/ci"
remote_push = false  # Read from CI cache only
remote_pull = true

Cache Invalidation

Cache entries are keyed by:

• Processor name
• Source file path
• Processor configuration hash

To force a full rebuild ignoring caches:

rsconstruct build --force

To clear only the local cache:

rsconstruct cache clear

Troubleshooting

S3 Access Denied

Check your AWS credentials:

aws s3 ls s3://your-bucket/

HTTP Upload Failures

Ensure your server accepts PUT requests. Many static file servers are read-only.

Slow Remote Cache

Consider:

• Using a closer region for S3
• Enabling S3 Transfer Acceleration
• Using a caching proxy

Debug Mode

Use verbose output to see cache operations:

rsconstruct build -v

This shows which products are restored from local cache, remote cache, or rebuilt.

Project Structure

RSConstruct follows a convention-over-configuration approach. The directory layout determines how files are processed.

Directory layout

project/
├── rsconstruct.toml          # Configuration file
├── .rsconstructignore        # Glob patterns for files to exclude
├── config/           # Python config files (loaded by templates)
├── tera.templates/   # .tera template files
├── templates.mako/   # .mako template files
├── src/              # C/C++ source files
├── out/
│   ├── cc_single_file/ # Compiled executables
│   ├── ruff/         # Ruff lint stub files
│   ├── pylint/       # Pylint lint stub files
│   ├── cppcheck/      # C/C++ lint stub files
│   ├── zspell/   # Zspell stub files
│   └── make/         # Make stub files
└── .rsconstruct/             # Cache directory
    ├── index.json    # Cache index
    ├── objects/       # Cached build artifacts
    └── deps/          # Dependency files

Conventions

Templates

Files in tera.templates/ with configured extensions (default .tera) are rendered to the project root:

• tera.templates/Makefile.tera produces Makefile
• tera.templates/config.toml.tera produces config.toml

Similarly, files in templates.mako/ with .mako extensions are rendered via the Mako processor:

• templates.mako/Makefile.mako produces Makefile
• templates.mako/config.toml.mako produces config.toml

C/C++ sources

Files in the source directory (default src/) are compiled to executables under out/processor.generator.cc_single_file/, preserving the directory structure:

• src/main.c produces out/processor.generator.cc_single_file/main.elf
• src/utils/helper.cc produces out/processor.generator.cc_single_file/utils/helper.elf

Python files

Python files are linted by processor.checker.ruff or processor.checker.pylint. Checkers write no files: a passing check is recorded in the cache, so an unchanged file is not checked again.

Build artifacts

All build outputs go into out/. The cache lives in .rsconstruct/. Use rsconstruct clean to remove every declared output (preserving the cache) — directories left empty afterward are also pruned, so out/ typically disappears too. Use rsconstruct clean all to remove out/ and .rsconstruct/ outright. See rsconstruct clean for the full breakdown of clean behavior.

Dependency Analyzers

rsconstruct uses dependency analyzers to scan source files and discover dependencies between files. Analyzers run after processors discover products and add dependency information to the build graph.

How analyzers work

1. Product discovery: Processors discover products (source → output mappings).
2. Dependency analysis: Analyzers scan source files to find dependencies.
3. Graph resolution: Dependencies are added to products for correct build ordering.

Analyzers are decoupled from processors — they operate on any product with matching source files, regardless of which processor created it.

Built-in analyzers

Per-analyzer reference pages:

• cpp — C/C++ #include scanning (invokes gcc/pkg-config)
• icpp — C/C++ #include scanning, pure Rust (no subprocess)
• python — Python import / from ... import resolution
• markdown — Markdown image and link references
• sass — Sass/SCSS @use, @forward and @import resolution
• tera — Tera {% include %}, {% import %}, {% extends %} references

Configuration

Analyzers are configured in rsconstruct.toml:

[analyzer]
auto_detect = true                                  # default: true
enabled     = ["cpp", "markdown", "python", "tera"] # instances to run

[analyzer.cpp]
include_paths = ["include", "src"]

Only analyzers listed under [analyzer.X] (or enabled) are instantiated — there is no global “all analyzers always run” mode.

Auto-detection

An analyzer runs if:

1. It is declared (listed in enabled or configured via [analyzer.X]).
2. AND either auto_detect = false, OR the analyzer detects relevant files in the project.

This mirrors how processors work.

Caching

Analyzer results are cached in the dependency cache (.rsconstruct/deps.redb). On subsequent builds:

• If neither a source file nor any of its cached dependencies has changed, the cached dependencies are used.
• If the source or any dependency has changed, or a dependency is gone, the source is re-scanned. Checking the dependencies is what catches a header that gains a new #include: the sources that include it are rescanned and pick up the new header.
• If a file appears where resolution previously found nothing — a src/x.h that now shadows the include/x.h an #include "x.h" used to resolve to, or a local foo.py for an import foo that used to be external — the source is re-scanned. Analyzers record the paths they probed and found missing.
• If the analyzer’s configuration changes (include_paths, load_paths, pkg-config output, …), every source it scanned is re-scanned: an entry is only trusted under the configuration it was scanned with.
• The sass and tera analyzers do not use the cached list at all: they rescan every source on every build.
• The cache is shared across all analyzers.

Generated files

A reference to a file that another product generates is a dependency even before the file exists: analyzers resolve references against the project’s files plus every declared output. The product that references it is ordered after the product that generates it.

A source that is itself generated (or that includes a generated header) is analyzed again during the build, right after the product generating it ran. On a clean checkout that is the first time its content can be read; on an incremental build it replaces the analysis of the stale copy that was on disk when the graph was built. Either way the products reading it are ordered, checksummed and cached against what they will actually read, and the build after a clean build finds everything up to date.

The cpp analyzer asks the compiler (-MM), which only sees files on disk, so it cannot resolve an include of a header that has not been generated yet; use icpp for projects that generate headers. The icpp, markdown, sass and tera analyzers all resolve generated files. The tera functions that query a directory (glob, grep_count, shell_output’s depends_on, workflow_names) see only the files on disk.

Use the analyzer command to manage analyzers and inspect the cache (full reference in Commands):

rsconstruct analyzer list                   # list available analyzers
rsconstruct analyzer defconfig cpp          # show default config for an analyzer
rsconstruct analyzer add cpp                # append [analyzer.cpp] to rsconstruct.toml with comments
rsconstruct analyzer add cpp --dry-run      # preview without writing
rsconstruct analyzer show all               # show all cached dependencies
rsconstruct analyzer show files src/main.c  # show dependencies for specific files
rsconstruct analyzer clean                  # clear the dependency cache

Build phases

With --phases, you can see when analyzers run:

rsconstruct --phases build

Output:

Phase: Building dependency graph...
  Phase: discover
  Phase: add_dependencies    # Analyzers run here
  Phase: apply_tool_version_hashes
  Phase: resolve_dependencies

Use --stop-after add-dependencies to stop after dependency analysis:

rsconstruct build --stop-after add-dependencies

Adding a custom analyzer

Analyzers implement the DepAnalyzer trait:

#![allow(unused)]
fn main() {
pub trait DepAnalyzer: Sync + Send {
    fn description(&self) -> &str;
    fn auto_detect(&self, file_index: &FileIndex) -> bool;
    fn match_product(&self, product: &Product) -> Option<PathBuf>;
    fn scan(&self, ctx: &BuildContext, source: &Path, file_index: &FileIndex)
        -> Result<ScanResult>;
    fn fingerprint_parts(&self, ctx: &BuildContext) -> Result<Vec<String>>;
    fn always_rescan(&self) -> bool { false }
}
}

An analyzer only answers two questions: which source a product’s dependencies come from (match_product), and what one source depends on (scan). Everything else — grouping products by source, the dependency cache, adding inputs to the graph, re-analysis of generated sources — is done by the framework (analyzers::Analysis), the same way for every analyzer.

scan returns a ScanResult:

• deps — the files the source depends on. Resolve against file_index as well as the disk: it lists files other products will generate.
• absent — every path resolution probed and found missing before its answer. If one of them appears later, the cached result is dropped.
• hash_pieces — non-file state to mix into the cache key (glob results, command text). Only allowed with always_rescan, since it is never cached.

fingerprint_parts returns everything besides file contents that decides what scan resolves — normally the serialized config (analyzers::config_fingerprint), plus any search paths resolved at run time.

cpp

Scans C/C++ source files for #include directives and adds header file dependencies to the build graph.

Native: No (may invoke gcc, pkg-config).

Auto-detects: Projects with .c, .cc, .cpp, .cxx, .h, .hh, .hpp, or .hxx files.

Features

• Recursive header scanning (follows includes in header files)
• Queries compiler for system include paths (only tracks project-local headers)
• Handles both #include "file" (relative to source) and #include <file> (searches include paths)
• Supports native regex scanning and compiler-based scanning (gcc -MM)
• Uses the dependency cache for incremental builds

System header detection

The cpp analyzer queries the compiler for its include search paths using gcc -E -Wp,-v -xc /dev/null. This allows it to properly identify which headers are system headers vs project-local headers. Only headers within the project directory are tracked as dependencies.

Configuration

[analyzer.cpp]
include_scanner       = "native"          # or "compiler" for gcc -MM
include_paths         = ["include", "src"]
pkg_config            = ["gtk+-3.0", "libcurl"]
include_path_commands = ["gcc -print-file-name=plugin"]
src_exclude_dirs      = ["/kernel/", "/vendor/"]
cc                    = "gcc"
cxx                   = "g++"
cflags                = ["-I/usr/local/include"]
cxxflags              = ["-std=c++17"]

include_path_commands

Shell commands whose stdout (trimmed) is added to the include search paths. Useful for compiler-specific include directories:

[analyzer.cpp]
include_path_commands = [
    "gcc -print-file-name=plugin",  # GCC plugin development headers
    "llvm-config --includedir",     # LLVM headers
]

pkg_config integration

Runs pkg-config --cflags-only-I for each package and adds the resulting include paths to the search path. Useful when your code includes headers from system libraries:

[analyzer.cpp]
pkg_config = ["gtk+-3.0", "glib-2.0"]

This automatically finds headers like <gtk/gtk.h> and <glib.h> without manually specifying their include paths.

Failures are errors

Both are resolved once, when the analyzer is set up, before any file is scanned. Any failure stops the build with an error naming the analyzer and the package or command: pkg-config missing, an unknown package, a command that exits non-zero, prints nothing, or prints something that is not a directory. (They used to be printed and skipped. The analyzer then ran without those include directories, headers found through them dropped out of the dependency lists, and editing one rebuilt nothing — with the build still green.) A package that resolves to no -I flags at all is not an error: its headers live in a default directory.

See also

• icpp — native (no-subprocess) C/C++ dependency analyzer

icpp

Native C/C++ dependency analyzer. Scans #include directives by parsing source files directly in Rust, without invoking gcc. It runs no subprocess unless pkg_config or include_path_commands is set; those run once, at setup, to find extra include directories.

Native: Yes.

Auto-detects: Projects with .c, .cc, .cpp, .cxx, .h, .hh, .hpp, or .hxx files.

When to use

• You want faster analysis without the overhead of launching gcc per file.
• You don’t need compiler-driven include path discovery.
• You’re happy to enumerate include paths explicitly in rsconstruct.toml.

Prefer cpp if you need the compiler’s own include resolution (macros, conditional includes, built-in system paths).

Configuration

[analyzer.icpp]
include_paths          = ["include", "src"]
pkg_config             = ["gtk+-3.0"]
include_path_commands  = ["gcc -print-file-name=plugin"]
src_exclude_dirs       = ["/kernel/", "/vendor/"]
follow_angle_brackets  = false
skip_not_found         = false

pkg_config and include_path_commands

The same as for cpp: directories from pkg-config --cflags-only-I and from shell commands that each print one directory are searched after include_paths. Any failure — pkg-config missing, an unknown package, a command that fails, prints nothing, or prints something that is not a directory — stops the build with an error naming the package or command (see cpp).

follow_angle_brackets (default: false)

Controls whether #include <foo.h> directives are followed.

• false (default) — angle-bracket includes are skipped entirely. System headers never enter the dependency graph, even when they resolve through configured include paths.
• true — angle-bracket includes are resolved and followed the same way as quoted includes. Unresolved angles are still tolerated (not an error), so missing system headers don’t break analysis.

Quoted includes (#include "foo.h") always resolve and must be found — this setting does not affect them (see skip_not_found below).

skip_not_found (default: false)

Controls what happens when an include cannot be resolved.

• false (default) — a quoted include (#include "foo.h") that cannot be resolved is a hard error. Unresolved angle-bracket includes are silently ignored (when follow_angle_brackets = true).
• true — unresolved includes of any kind are silently skipped.

Use true for partial / work-in-progress codebases where some headers aren’t generated yet.

See also

• cpp — compiler-aware (external) C/C++ dependency analyzer

python

Scans Python source files for import and from ... import statements and adds dependencies on local Python modules.

Native: Yes.

Auto-detects: Projects with .py files.

Features

• Follows imports transitively: running main.py runs what its imports import, so a module two imports away is a dependency, and editing it rebuilds main.py’s products. Import cycles are fine; a module is never its own dependency.
• Resolves imports to local files and ignores stdlib and third-party packages. A module name is looked up as name.py or name/__init__.py under each root in turn: the importing file’s directory, the project root, then each entry of search_paths (default src, for the src/ package layout). The first root that has it wins.
• Depends on the __init__.py of every package above an imported module: importing app.util.fs runs app/__init__.py and app/util/__init__.py.
• from pkg import name also resolves pkg.name, so importing a submodule by name (from app.util import fs) depends on app/util/fs.py. A name that is not a module resolves nowhere and adds nothing.
• Parses import a, b, import a.b as c, from x import ( … ) across lines, and imports indented inside functions or try blocks. Comments are skipped.
• Every path probed and found missing is recorded, so a local module that appears later, or one that would now win in an earlier root, triggers a rescan.

Relative imports (from . import x) are not resolved.

Configuration

[analyzer.python]
search_paths = ["src"]   # extra roots for absolute imports, relative to the project root

markdown

Scans Markdown source files for image and link references (![alt](path), [text](path)) and adds referenced local files as dependencies.

Native: Yes.

Auto-detects: Projects with .md files.

Features

• Extracts ![alt](path) image references and [text](path) link references
• Resolves paths relative to the source file’s directory
• Skips URLs (http://, https://, ftp://), data URIs, and anchor-only links
• Strips title text and anchor fragments from paths

This ensures that when an image or linked file changes, any Markdown product that references it is rebuilt.

Configuration

[analyzer.markdown]
# currently no tunables

sass

Scans Sass and SCSS files for @use, @forward and @import rules and adds every local file they load as a dependency, following imports transitively. Declare it whenever a project compiles Sass with isass or sass: without it, a stylesheet’s only input is its own file, so editing a partial it @uses does not rebuild it and the old CSS stays in out/.

Native: Yes.

Auto-detects: Projects with .scss or .sass files.

Features

• Follows @use "x", @forward "x" and @import "a", "b", in both SCSS and the indented syntax (where @import a, b may be unquoted).
• Resolves URLs the way the Sass compiler does: relative to the importing file, then each of load_paths; a URL without an extension is tried as .scss, .sass and .css, each also as a partial (_name), then as a directory’s index / _index file.
• Follows imports transitively: a partial that @uses another partial makes both inputs of every stylesheet that loads it.
• Ignores what loads no project file: built-in modules (@use "sass:math"), pkg: and remote URLs, and plain CSS imports (@import "x.css", @import url(...)). A @use "x.css" does load the file and is tracked.
• Ignores rules inside // and /* */ comments.
• Resolves a partial that another product generates, before it exists: the stylesheet is built after the partial’s producer (see Generated files).

Every source is rescanned on every build rather than read from the dependency cache. The cache is keyed by the importing file’s own contents, so it cannot see a @use added inside a partial; scanning is cheap enough that always rescanning costs nothing noticeable.

Configuration

[analyzer.sass]
load_paths     = ["node_modules", "vendor/styles"]
skip_not_found = false

skip_not_found (default: false)

• false (default) — an import of a local file that resolves nowhere is a hard error naming the file, the URL and the directories searched:

  Sass import not found: "nope" in sass/style.scss (searched sass and load_paths []). Add its directory to load_paths, or set skip_not_found = true.
  

• true — such imports are skipped. Use it when the compiler finds files through a mechanism the analyzer does not model (a custom importer, say); the imports it skips are then not tracked.

See also

• isass — in-process Sass compiler
• sass — Sass compiler (external sass command)

tera

Scans Tera template files for {% include %}, {% import %}, and {% extends %} directives and adds referenced template files as dependencies.

Native: Yes.

Auto-detects: Projects with .tera files.

Features

• Extracts paths from {% include "path" %}, {% import "path" %}, and {% extends "path" %}
• Handles both double- and single-quoted paths
• Resolves paths relative to the source file’s directory and the project root
• Resolves a template or data file that another product generates, before it exists: the template is rendered after its producer (see Generated files)

This ensures that when an included template changes, any template that includes it is rebuilt.

Configuration

[analyzer.tera]
# currently no tunables

Processors

RSConstruct uses processors to discover and build products. Each processor scans for source files matching its conventions and produces output files.

Processor Types

There are four processor types: checker, generator, explicit, and mass generator. They differ in how inputs are discovered, how outputs are declared, and how results are cached.

See Processor Types for full descriptions, examples, and a comparison table.

Configuration

Declare processors by adding [processor.TYPE.NAME] sections to rsconstruct.toml:

[processor.checker.ruff]

[processor.checker.pylint]
args = ["--disable=C0114"]

[processor.generator.cc_single_file]

Only declared processors run — no processors are enabled by default. Use rsconstruct smart auto to auto-detect and add relevant processors.

Use rsconstruct processor list to see declared processors and descriptions. Use rsconstruct processor list --all to show all built-in processors, not just those enabled in the project. Use rsconstruct processor files to see which files each processor discovers.

Available Processors

• Tera — renders Tera templates into output files
• Ruff — lints Python files with ruff
• Pylint — lints Python files with pylint
• Mypy — type-checks Python files with mypy
• Pyrefly — type-checks Python files with pyrefly
• CC — builds full C/C++ projects from cc.yaml manifests
• CC Single File — compiles C/C++ source files into executables (single-file)
• Linux Module — builds Linux kernel modules from linux-module.yaml manifests
• Cppcheck — runs static analysis on C/C++ source files
• Clang-Tidy — runs clang-tidy static analysis on C/C++ source files
• Shellcheck — lints shell scripts using shellcheck
• Zspell — checks documentation files for spelling errors
• Rumdl — lints Markdown files with rumdl
• Oxlint — lints JavaScript/TypeScript files with oxlint
• Selene — lints Lua files with selene
• Iluacheck — lints Lua files with luacheck’s analysis (native)
• Biome — lints CSS/JavaScript/TypeScript/JSON files with biome
• Make — runs make in directories containing Makefiles
• Cargo — builds Rust projects using Cargo
• Yamllint — lints YAML files with yamllint
• Jq — validates JSON files with jq
• Jsonlint — lints JSON files with jsonlint
• Taplo — checks TOML files with taplo
• Terms — checks that technical terms are backtick-quoted in Markdown files
• Json Schema — validates JSON schema propertyOrdering
• Iyamlschema — validates YAML files against JSON schemas (native)
• Yaml2json — converts YAML files to JSON (native)
• Markdown2html — converts Markdown to HTML using markdown CLI
• Imarkdown2html — converts Markdown to HTML (native)
• Mass Generator — runs a tool that enumerates its outputs in advance, one cached product per predicted file
• Zola — builds a zola site, one cached product per file zola writes, planned natively

Clean behavior

rsconstruct clean outputs calls each product’s processor-defined clean(). What gets removed depends on the processor type:

Recursive directory removal is reserved for the user-declared output_dirs of Explicit. All other processor types remove individually-declared files and nothing else. A mass generator’s output_dirs only bound where its predicted files may live; the directory itself is never removed directly, though the empty-directory sweep removes directories that become empty.

After every product’s clean() completes, the orchestrator runs an empty-directory sweep: every parent of every removed output (and every parent of every removed output_dir) is tried with fs::remove_dir (non-recursive — succeeds only on already-empty directories), walking upward until a non-empty directory or the project root. The sweep does not special-case out/ — any ancestor of a cleaned output is eligible.

See rsconstruct clean for the full command reference, the --no-empty-dirs flag, the -p filter, and the other clean variants (all, git, unknown).

Worked example

Consider this project:

# rsconstruct.toml

[processor.checker.ruff]                     # Checker — no outputs
src_dirs = ["src"]

[processor.generator.tera]                   # Generator — declared file outputs
src_dirs = ["templates"]
src_extensions = [".tera"]

[processor.mass_generator.mdbook]            # Mass generator — planned file outputs
src_dirs = ["docs"]

Layout:

project/
├── rsconstruct.toml
├── src/main.py                      # ruff lints this
├── templates/index.html.tera        # tera renders to → out/processor.generator.tera/index.html
├── docs/
│   ├── book.toml
│   └── src/SUMMARY.md
└── book/                            # mdbook output_dir; each file is a planned product
    ├── index.html
    ├── css/general.css
    └── ...

After rsconstruct build, both out/processor.generator.tera/index.html and the planned files under book/ exist.

Now run rsconstruct clean outputs:

1. ruff — Checker. clean() is a no-op. Nothing removed.
2. tera — Generator. clean() calls fs::remove_file("out/processor.generator.tera/index.html"). The file goes; out/processor.generator.tera/ and out/ are not yet touched.
3. mdbook — Mass generator. clean() removes each planned output file under book/.
4. Empty-directory sweep. The orchestrator collects parents of every removed path (out/processor.generator.tera, out, book/css, book) and removes those that are now empty, deepest-first.

Final state: src/main.py, templates/index.html.tera, docs/..., and rsconstruct.toml remain untouched. The cache (.rsconstruct/) is untouched. out/ and book/ are gone.

If you instead ran rsconstruct clean outputs --no-empty-dirs, the only difference is step 4 is skipped — out/processor.generator.tera/ and out/ would remain as empty directories.

If you ran rsconstruct clean outputs -p processor.generator.tera, only step 2 + the sweep of its parents runs. book/ is left intact because mdbook is filtered out.

Custom Processors

A command of your own runs through a config-driven processor: [processor.checker.script] for a check, [processor.generator.generic] for one output per input, [processor.explicit.generic] for declared inputs and outputs, and [processor.mass_generator.generic] for a tool that can predict its outputs. A new tool with its own discovery or output rules is a new processor file under src/processor/.

Processor Types

Every processor in RSConstruct has a type that determines how it discovers inputs, produces outputs, and interacts with the cache. There are four types.

Run rsconstruct processor types to list them. Its Batch column is the type’s contract on taking more than one input in one tool invocation: optional for checkers and generators, where each processor decides (processor list shows which do), and always for explicit processors and mass generators, which take every input in one invocation by construction. --verbose adds the one-line contract behind each value.

Checker

A checker validates input files without producing any output. If the check passes, the result is cached — if the inputs haven’t changed on the next build, the check is skipped entirely.

How it works

1. Scans for files matching src_extensions in src_dirs
2. Creates one product per input file
3. Runs the tool on each file (or batch of files)
4. If the tool exits successfully, records a marker in the cache
5. On the next build, if inputs are unchanged, the check is skipped

What gets cached

A marker entry — no files, no blobs. The marker’s presence means “this check passed with these inputs.”

Examples

Lint Python files with ruff:

[processor.checker.ruff]

Scans for .py files, runs ruff check on each. No output files produced.

src/main.py → (checker)
src/utils.py → (checker)

Lint shell scripts:

[processor.checker.shellcheck]

Scans for .sh and .bash files, runs shellcheck on each.

Validate YAML files:

[processor.checker.yamllint]

Scans for .yml and .yaml files, runs yamllint on each.

Validate JSON files with jq:

[processor.checker.jq]

Scans for .json files, validates each with jq.

Spell check Markdown files:

[processor.checker.zspell]

Scans for .md files, checks spelling with the built-in zspell engine.

Built-in checkers

actionlint, ascii, aspell, biome, black, checkpatch, checkstyle, clang_tidy, clippy, cmake, cppcheck, cpplint, doctest, duplicate_files, encoding, eslint, hadolint, htmlhint, htmllint, iactionlint, icpplint, idockerfile, ijq, ijsonlint, iluacheck, isvglint, itaplo, itidy, ixmllint, iyamllint, iyamlschema, iyq, jq, jshint, jslint, json_schema, jsonlint, license_header, luacheck, make, markdownlint, marp_images, mdl, mypy, oxlint, perlcritic, php_lint, prettier, pylint, pyrefly, pytest, ruff, rumdl, script, selene, shellcheck, slidev, standard, stylelint, svglint, svgo, taplo, terms, tidy, xmllint, yamllint, yq, zspell

Generator

A generator transforms each input file into one or more output files. It creates one product per input file (or one per input x format pair for multi-format generators like pandoc).

How it works

1. Scans for files matching src_extensions in src_dirs
2. For each input file, computes the output path from the input path, output directory, and format
3. Creates one product per input x format pair
4. Runs the tool to produce the output file
5. Stores the output as a content-addressed blob in the cache

What gets cached

One blob per output file. The blob is the raw file content, stored by its SHA-256 hash. On restore, the blob is hardlinked (or copied) to the output path.

Examples

Render Tera templates:

[processor.generator.tera]

Scans tera.templates/ for .tera files, renders each template. The output path is the template path with the .tera extension stripped:

tera.templates/config.py.tera → config.py
tera.templates/README.md.tera → README.md

Convert Marp slides to PDF:

[processor.generator.marp]

Scans marp/ for .md files, converts each to PDF (and optionally other formats):

marp/slides.md → out/processor.generator.marp/slides.pdf
marp/intro.md → out/processor.generator.marp/intro.pdf

Convert documents with pandoc (multi-format):

[processor.generator.pandoc]

Scans pandoc/ for .md files, converts each to PDF, HTML, and DOCX. Each format is a separate product with its own cache entry:

pandoc/syllabus.md → out/processor.generator.pandoc/syllabus.pdf
pandoc/syllabus.md → out/processor.generator.pandoc/syllabus.html
pandoc/syllabus.md → out/processor.generator.pandoc/syllabus.docx

Compile single-file C programs:

[processor.generator.cc_single_file]

Scans src/ for .c and .cc files, compiles each into an executable:

src/main.c → out/processor.generator.cc_single_file/src/main.elf
src/test.c → out/processor.generator.cc_single_file/src/test.elf

Convert Mermaid diagrams:

[processor.generator.mermaid]

Scans for .mmd files, converts each to PNG (configurable formats):

diagrams/flow.mmd → out/processor.generator.mermaid/diagrams/flow.png

Compile SCSS to CSS:

[processor.generator.sass]

Scans sass/ for .scss and .sass files, compiles each to CSS:

sass/styles.scss → out/processor.generator.sass/styles.css

Built-in generators

a2x, cc_single_file, chromium, drawio, generic, ijinja2, imarkdown2html, ipdfunite, iprotobuf, isass, jinja2, libreoffice, mako, markdown2html, marp, mermaid, objdump, pandoc, pdflatex, pdfunite, protobuf, requirements, rust_single_file, sass, tags, tera, yaml2json

Explicit

An explicit processor aggregates many inputs into (possibly) many output files and/or directories. Unlike other types which create one product per discovered file, explicit creates a single product with all declared inputs and outputs.

How it works

1. Inputs are listed explicitly via inputs and input_globs in the config
2. Creates a single product with all inputs and all outputs
3. Runs the command, passing --inputs and --outputs on the command line
4. Stores each output file as a content-addressed blob

What gets cached

One blob per output file (like generator).

Examples

Build a static site from generated HTML:

[processor.explicit.generic.site]
command = "python3"
args = ["build_site.py"]
input_globs = ["out/processor.generator.pandoc/*.html", "templates/*.html"]
inputs = ["site.yaml"]
outputs = ["out/site/index.html", "out/site/style.css"]

Waits for pandoc to produce HTML files, then combines them with templates into a site. All inputs are aggregated into one product:

out/processor.generator.pandoc/page1.html, out/processor.generator.pandoc/page2.html, templates/base.html, site.yaml → out/site/index.html, out/site/style.css

Merge PDFs into a course bundle:

[processor.explicit.generic.course]
command = "pdfunite"
input_globs = ["out/processor.generator.pdflatex/*.pdf"]
outputs = ["out/course/full-course.pdf"]

Aggregates all PDF outputs from pdflatex into a single merged PDF.

Built-in explicit processors

generic

Mass Generator

A mass generator runs a tool that produces many files in one invocation and enumerates them in advance. Every planned file becomes a product of its own with its own inputs and blob cache entry, while the underlying build tool runs at most once per manifest per build: once for the whole instance when the tool has a single plan (generic), once per manifest file when the processor scans for them (one make per linux-module.yaml, one cargo build per Cargo.toml).

How it works

1. At graph-build time, computes the output plan (natively or via a planner command)
2. Creates one product per planned file: inputs = the entry’s sources, outputs = its path
3. Classifies each product individually (skip, restore, or build)
4. The first product that needs building runs command; the rest find the tool already run
5. Compares the files the tool wrote against the plan — a missing predicted file or an off-plan write fails the build. Files another product declares, as output_files or under its output_dirs, are that product’s and are not reported even when it writes them during the tool’s run
6. Stores each predicted file as a content-addressed blob

What gets cached

One blob per predicted file (like generator). When every product is clean the tool does not run at all; when some are, the tool runs once and every dirty product caches its own file.

Examples

A static site generator with a plan mode:

[processor.mass_generator.generic.site]
command         = "rssite"
args            = ["build"]
predict_command = "rssite"
predict_args    = ["plan"]
output_dirs     = ["_site"]

rssite plan prints which _site/*.html files rssite build will write and which sources each depends on. Changing docs/about.md dirties only _site/about/index.html; a linter scanning _site/ depends on each page individually.

docs/index.md, templates/default.html → _site/index.html
docs/about.md, templates/default.html → _site/about/index.html

Build documentation with Sphinx:

[processor.mass_generator.sphinx]
dep_inputs = ["src/mypkg/**/*.py", "pyproject.toml", "uv.lock"]

Asks Sphinx itself which files sphinx-build -b html will write (a planner runs Sphinx’s read phase, nothing more), builds sphinx/ into docs/ through a staging directory, and caches every page, static file and index as a product of its own.

sphinx/*, src/mypkg/**/*.py → docs/index.html, docs/mypkg.html, docs/_static/basic.css, …

Built-in mass generators

cargo, cc, gem, generic, jekyll, linux_module, mdbook, npm, pip, sphinx, zola

Any tool that honors the manifest contract plugs into the config-driven generic mass generator via [processor.mass_generator.generic.NAME]; see Mass Generator.

Comparison

Checkers

A checker validates its input files and produces no output. A passing check is recorded as a cache marker, so unchanged inputs are not checked again. See Processor Types for how checkers work.

The pages in this section document the built-in checkers. These checkers have no dedicated page yet: duplicate_files, encoding, ijq, ijsonlint, itaplo, iyamllint, license_header, marp_images, prettier, svglint, svgo.

Run rsconstruct processor list for the full list with each processor’s type.

Actionlint Processor

Purpose

Lints GitHub Actions workflow files using actionlint.

The Rust alternative is iactionlint: the same rules, the same .github/actionlint.yaml, the same messages, in-process. Switching is actionlint → iactionlint in the stanza header. It does not run shellcheck or pyflakes over run: scripts; a repository that relies on that stays here.

How It Works

Discovers .yml/.yaml files in the configured directories, runs actionlint on each file, and records success in the cache. A non-zero exit code from actionlint fails the product.

actionlint validates workflow syntax against the GitHub Actions schema, type-checks ${{ }} expressions, checks runs-on labels and cron syntax, flags untrusted-input injection in run: steps, and (when shellcheck is installed) lints the shell scripts inside run: blocks.

actionlint reads its own configuration from .github/actionlint.yaml (or .yml) in the repository — e.g. a self-hosted-runner.labels allowlist for runner labels its built-in database doesn’t know. Both paths are tracked via dep_auto, so editing the config retriggers the check.

This processor supports batch mode.

Source Files

• Input: **/*.yml, **/*.yaml (point src_dirs at .github/workflows)
• Output: none (checker)

Configuration

[processor.checker.actionlint]
src_dirs = [".github/workflows"]
args = []
dep_inputs = []

Scoping src_dirs to .github/workflows matters: actionlint treats every file it is given as a workflow file, so pointing it at a directory of ordinary YAML would report false errors.

Batch support

The tool accepts multiple files on the command line. When batching is enabled (default), rsconstruct passes all files in a single invocation for better performance.

Clean behavior

This processor is a Checker — rsconstruct clean outputs is a no-op for it (checkers produce no outputs). See Clean behavior and rsconstruct clean.

Ascii Check Processor

Purpose

Validates that files contain only ASCII characters.

How It Works

Discovers .md files in the project and checks each for non-ASCII characters. Files containing non-ASCII bytes fail the check. This is a built-in processor that does not require any external tools.

This processor supports batch mode, allowing multiple files to be checked in a single invocation.

Source Files

• Input: **/*.md
• Output: none (checker)

Configuration

[processor.checker.ascii]
args = []                              # Additional arguments (unused, for consistency)
dep_inputs = []                      # Additional files that trigger rebuilds when changed

Batch support

The tool accepts multiple files on the command line. When batching is enabled (default), rsconstruct passes all files in a single invocation for better performance.

Clean behavior

This processor is a Checker — rsconstruct clean outputs is a no-op for it (checkers produce no outputs). See Clean behavior and rsconstruct clean.

Aspell Processor

Purpose

Checks spelling in Markdown files using aspell.

How It Works

Discovers .md files in the project and runs aspell on each file using the configured aspell configuration file. A non-zero exit code fails the product.

Source Files

• Input: **/*.md
• Output: none (checker)

Configuration

[processor.checker.aspell]
command = "aspell"                     # The aspell command to run
conf = ".aspell.conf"                  # Aspell configuration file
args = []                              # Additional arguments to pass to aspell
dep_inputs = []                      # Additional files that trigger rebuilds when changed

Batch support

The tool accepts multiple files on the command line. When batching is enabled (default), rsconstruct passes all files in a single invocation for better performance.

Clean behavior

This processor is a Checker — rsconstruct clean outputs is a no-op for it (checkers produce no outputs). See Clean behavior and rsconstruct clean.

Biome Processor

Purpose

Lints CSS, JavaScript, TypeScript and JSON files using biome. It is the Rust alternative to the Stylelint processor, and a second alternative, next to oxlint, to ESLint: a single static binary that needs no node runtime and no node_modules/.

biome does not parse SCSS, Sass or Less. A repo with those stays on stylelint for them.

How It Works

Discovers .css, .js, .jsx, .ts, .tsx, .mjs, .cjs, .json and .jsonc files in the project (excluding common build tool directories), runs biome lint on each file, and records success in the cache. A non-zero exit code from biome fails the product.

This processor supports batch mode, allowing multiple files to be checked in a single biome invocation for better performance.

If a biome config file exists (biome.json, biome.jsonc, .biome.json or .biome.jsonc), it is automatically added as an extra input so that configuration changes trigger rebuilds.

Choosing what biome lints

biome has one linter switch per language in its config (javascript.linter.enabled, json.linter.enabled, …). A repo that lints JavaScript with oxlint turns biome’s JavaScript linter off in .biome.jsonc and narrows this processor to stylesheets:

[processor.checker.biome]
src_dirs = ["src"]
src_extensions = [".css"]

Keep the two in step: biome exits non-zero when every file it was handed belongs to a language whose linter is off (“No files were processed”).

Migrating from stylelint

Rule names differ but the coverage is close. Of stylelint’s standard correctness rules, three need no biome rule because biome’s CSS parser rejects the construct outright (color-no-invalid-hex, no-invalid-double-slash-comments, string-no-newline), one has no equivalent (function-calc-no-unspaced-operator), and no-empty-source differs in that biome’s noEmptySource flags a comment-only stylesheet where stylelint does not. no-duplicate-selectors maps to noDuplicateSelectors, still a nursery rule that has to be enabled explicitly. biome explain <rule> shows any rule’s group and options.

Source Files

• Input: **/*.css, **/*.js, **/*.jsx, **/*.ts, **/*.tsx, **/*.mjs, **/*.cjs, **/*.json, **/*.jsonc
• Output: none (checker)

Configuration

[processor.checker.biome]
command = "biome"
args = []
dep_inputs = []

Installation

rsconstruct tool install downloads the static Linux binary from the latest biome GitHub release. The npm package is the fallback.

Batch support

The tool accepts multiple files on the command line. When batching is enabled (default), rsconstruct passes all files in a single invocation for better performance.

Clean behavior

This processor is a Checker — rsconstruct clean outputs is a no-op for it (checkers produce no outputs). See Clean behavior and rsconstruct clean.

Black Processor

Purpose

Checks Python file formatting using Black, the uncompromising code formatter. Runs black --check which verifies files are already formatted without modifying them.

How It Works

Python files matching configured extensions are checked via black --check. The command exits with a non-zero status if any file would be reformatted, causing the build to fail.

Source Files

• Input: **/*{src_extensions} (default: *.py)

Configuration

[processor.checker.black]
src_extensions = [".py"]                      # File extensions to check (default: [".py"])
dep_inputs = []                         # Additional files that trigger rechecks when changed
args = []                                 # Extra arguments passed to black

Batch support

The tool accepts multiple files on the command line. When batching is enabled (default), rsconstruct passes all files in a single invocation for better performance.

Clean behavior

This processor is a Checker — rsconstruct clean outputs is a no-op for it (checkers produce no outputs). See Clean behavior and rsconstruct clean.

Checkpatch Processor

Purpose

Checks C source files using the Linux kernel’s checkpatch.pl script.

The Rust alternative is icheckpatch: checkpatch’s file-mode checks, in-process, with checkpatch’s report. Switching is checkpatch → icheckpatch in the stanza header.

How It Works

Discovers .c and .h files under src/ (excluding common C/C++ build directories), runs checkpatch.pl on each file, and records success in the cache. A non-zero exit code from checkpatch fails the product.

This processor supports batch mode.

Source Files

• Input: src/**/*.c, src/**/*.h
• Output: none (checker)

Configuration

[processor.checker.checkpatch]
args = []
dep_inputs = []

Batch support

The tool processes one file at a time. Each file is checked in a separate invocation.

Clean behavior

This processor is a Checker — rsconstruct clean outputs is a no-op for it (checkers produce no outputs). See Clean behavior and rsconstruct clean.

Checkstyle Processor

Purpose

Checks Java code style using Checkstyle.

The Rust alternative is icheckstyle: checkstyle’s grammar and the checks of the fleet’s checkstyle.xml, in-process, with checkstyle’s messages and positions. Switching is checkstyle → icheckstyle in the stanza header, dropping args = ["-c", "checkstyle.xml"].

How It Works

Discovers .java files in the project (excluding common build tool directories), runs checkstyle on each file, and records success in the cache. A non-zero exit code from checkstyle fails the product.

This processor supports batch mode.

If a checkstyle.xml file exists, it is automatically added as an extra input so that configuration changes trigger rebuilds.

Source Files

• Input: **/*.java
• Output: none (checker)

Configuration

[processor.checker.checkstyle]
args = []
dep_inputs = []

Batch support

The tool accepts multiple files on the command line. When batching is enabled (default), rsconstruct passes all files in a single invocation for better performance.

Clean behavior

This processor is a Checker — rsconstruct clean outputs is a no-op for it (checkers produce no outputs). See Clean behavior and rsconstruct clean.

Clang-Tidy Processor

Purpose

Runs clang-tidy static analysis on C/C++ source files.

How It Works

Discovers .c and .cc files under the configured source directory, runs clang-tidy on each file individually, and creates a stub file on success. A non-zero exit code from clang-tidy fails the product.

Note: This processor does not support batch mode. Each file is checked separately to avoid cross-file analysis issues with unrelated files.

Source Files

• Input: {source_dir}/**/*.c, {source_dir}/**/*.cc
• Output: none (checker — a passing check is recorded in the cache, no file is written)

Configuration

[processor.checker.clang_tidy]
args = ["-checks=*"]                        # Arguments passed to clang-tidy
compiler_args = ["-std=c++17"]              # Arguments passed after -- to the compiler
dep_inputs = [".clang-tidy"]              # Additional files that trigger rebuilds when changed

Batch support

The tool processes one file at a time. Each file is checked in a separate invocation.

Compiler Arguments

Clang-tidy requires knowing compiler flags to properly parse the source files. Use compiler_args to specify include paths, defines, and language standards:

[processor.checker.clang_tidy]
compiler_args = ["-std=c++17", "-I/usr/include/mylib", "-DDEBUG"]

Using .clang-tidy File

Clang-tidy automatically reads configuration from a .clang-tidy file in the project root. Add it to dep_inputs so changes trigger rebuilds:

[processor.checker.clang_tidy]
dep_inputs = [".clang-tidy"]

Clean behavior

This processor is a Checker — rsconstruct clean outputs is a no-op for it (checkers produce no outputs). See Clean behavior and rsconstruct clean.

Clippy Processor

Purpose

Lints Rust projects using Cargo Clippy. Each Cargo.toml produces a cached success marker, allowing RSConstruct to skip re-linting when source files haven’t changed.

How It Works

Discovers files named Cargo.toml in the project. For each Cargo.toml found, the processor runs cargo clippy in that directory. A non-zero exit code fails the product.

Input Tracking

The clippy processor tracks all .rs and .toml files, plus Cargo.lock, in the Cargo.toml’s directory tree as inputs. This includes:

• Cargo.toml and Cargo.lock
• All Rust source files (src/**/*.rs)
• Test files, examples, benches
• Workspace member Cargo.toml files

When any tracked file changes, rsconstruct will re-run clippy.

Source Files

• Input: Cargo.toml plus all .rs and .toml files and Cargo.lock in the project tree
• Output: None (checker-style caching)

Configuration

[processor.checker.clippy]
cargo = "cargo"          # Cargo binary to use
command = "clippy"       # Cargo command (usually "clippy")
args = []                # Extra arguments passed to cargo clippy
src_dirs = [""]            # Directory to scan ("" = project root)
src_extensions = ["Cargo.toml"]
dep_inputs = []        # Additional files that trigger rebuilds

Batch support

The tool processes one file at a time. Each file is checked in a separate invocation.

Examples

Basic Usage

[processor.checker.clippy]

Deny All Warnings

[processor.checker.clippy]
args = ["--", "-D", "warnings"]

Use Both Cargo Build and Clippy

[processor.mass_generator.cargo]

[processor.checker.clippy]

Notes

• Clippy uses the cargo binary which is shared with the cargo processor
• The target/ directory is automatically excluded from input scanning
• For monorepos with multiple Rust projects, each Cargo.toml is linted separately

Clean behavior

This processor is a Checker — rsconstruct clean outputs is a no-op for it (checkers produce no outputs). See Clean behavior and rsconstruct clean.

CMake Processor

Purpose

Lints CMake files using cmakelint.

How It Works

Discovers CMakeLists.txt files in the project (excluding common build tool directories), runs cmakelint on each file, and records success in the cache. A non-zero exit code from cmakelint fails the product.

This processor supports batch mode.

Source Files

• Input: **/CMakeLists.txt
• Output: none (checker)

Configuration

[processor.checker.cmake]
args = []
dep_inputs = []

Batch support

The tool accepts multiple files on the command line. When batching is enabled (default), rsconstruct passes all files in a single invocation for better performance.

Clean behavior

This processor is a Checker — rsconstruct clean outputs is a no-op for it (checkers produce no outputs). See Clean behavior and rsconstruct clean.

Cppcheck Processor

Purpose

Runs cppcheck static analysis on C/C++ source files.

How It Works

Discovers .c and .cc files under the configured source directory, runs cppcheck on each file individually, and creates a stub file on success. A non-zero exit code from cppcheck fails the product.

Note: This processor does not support batch mode. Each file is checked separately because cppcheck performs cross-file analysis (CTU - Cross Translation Unit) which produces false positives when unrelated files are checked together. For example, standalone example programs that define classes with the same name will trigger ctuOneDefinitionRuleViolation errors even though the files are never linked together. Cppcheck has no flag to disable this cross-file analysis (--max-ctu-depth=0 does not help), so files must be checked individually.

Source Files

• Input: {source_dir}/**/*.c, {source_dir}/**/*.cc
• Output: none (checker — a passing check is recorded in the cache, no file is written)

Configuration

[processor.checker.cppcheck]
args = ["--error-exitcode=1", "--enable=warning,style,performance,portability"]
dep_inputs = [".cppcheck-suppressions"]   # Additional files that trigger rebuilds when changed

To use a suppressions file, add "--suppressions-list=.cppcheck-suppressions" to args.

Batch support

The tool processes one file at a time. Each file is checked in a separate invocation.

Clean behavior

This processor is a Checker — rsconstruct clean outputs is a no-op for it (checkers produce no outputs). See Clean behavior and rsconstruct clean.

Cpplint Processor

Purpose

Lints C/C++ files using cpplint (Google C++ style checker).

The Rust alternative is icpplint: cpplint 2.0.2’s checks, CPPLINT.cfg chain and NOLINT handling, in-process, with cpplint’s messages and exit rule. Switching is cpplint → icpplint in the stanza header, with args = ["--config=NAME"] becoming config_file = "NAME".

How It Works

Discovers .c, .cc, .h, and .hh files under src/ (excluding common C/C++ build directories), runs cpplint on each file, and records success in the cache. A non-zero exit code from cpplint fails the product.

This processor supports batch mode.

Source Files

• Input: src/**/*.c, src/**/*.cc, src/**/*.h, src/**/*.hh
• Output: none (checker)

Configuration

[processor.checker.cpplint]
args = []
dep_inputs = []

Batch support

The tool processes one file at a time. Each file is checked in a separate invocation.

Clean behavior

This processor is a Checker — rsconstruct clean outputs is a no-op for it (checkers produce no outputs). See Clean behavior and rsconstruct clean.

Doctest Processor

Purpose

Runs Python doctests embedded in .py files using python3 -m doctest.

How It Works

Python files (.py) are checked for embedded doctests. Each file is run through python3 -m doctest — failing doctests cause the build to fail.

Source Files

• Input: **/*.py
• Output: none (checker — pass/fail only)

Configuration

[processor.checker.doctest]
src_extensions = [".py"]                      # File extensions to process (default: [".py"])
dep_inputs = []                         # Additional files that trigger rebuilds

Batch support

The tool accepts multiple files on the command line. When batching is enabled (default), rsconstruct passes all files in a single invocation for better performance.

Clean behavior

This processor is a Checker — rsconstruct clean outputs is a no-op for it (checkers produce no outputs). See Clean behavior and rsconstruct clean.

Duplicate Files Processor

Purpose

Finds files with identical content. Native (in-process, SHA-256; no external tools required).

How It Works

Unlike most checkers, this processor creates one product for the whole set of scanned files, because duplication is a property of the set, not of a single file. Every file is hashed with SHA-256, and the product fails if two or more files share a hash, listing each group:

src/__init__.py: [processor.checker.duplicate_files] 2 set(s) of duplicate files found:
  src/__init__.py, src/empty.py
  src/b.sh, src/c.sh

The error is reported under the first file of the product. Since any change to any scanned file changes the product’s inputs, the whole set is re-checked whenever one file changes.

All empty files have the same hash, so two empty files are duplicates (for example two empty __init__.py files in different packages). Exclude them with src_exclude_files, or narrow src_dirs.

Source Files

• Input: files under src_dirs with one of the default extensions: .py .rs .js .ts .c .cc .h .hh .java .rb .go .sh .md .yaml .yml .json .toml .xml .html .css
• Output: none (checker)

The default src_dirs is empty, so a stanza with no src_dirs or src_files checks nothing: name the directories ([""] for the whole project) or files to check.

Configuration

[processor.checker.duplicate_files]
src_dirs = ["src"]
src_exclude_files = ["__init__.py"]

Batch support

Not applicable: all scanned files form a single product.

Clean behavior

This processor is a Checker — rsconstruct clean outputs is a no-op for it (checkers produce no outputs). See Clean behavior and rsconstruct clean.

Encoding Processor

Purpose

Checks that text files are valid UTF-8 without a byte order mark. Native (in-process; no external tools required).

How It Works

Each file is read as bytes and rejected if it:

• starts with a UTF-8 BOM (EF BB BF): file has UTF-8 BOM (byte order mark)
• starts with a UTF-16 BOM (FF FE or FE FF): file appears to be UTF-16 encoded
• contains bytes that are not valid UTF-8: invalid UTF-8 at byte 5 (line 1)

src/bom.py: [processor.checker.encoding] Encoding errors found:
src/bom.py: file has UTF-8 BOM (byte order mark)

Source Files

• Input: files under src_dirs with one of the default text extensions: .py .rs .js .ts .c .cc .h .hh .java .rb .go .sh .bash .lua .pl .pm .php .md .yaml .yml .json .toml .xml .html .htm .css .scss .sass .tex .txt
• Output: none (checker)

The default src_dirs is empty, so a stanza with no src_dirs or src_files checks nothing: name the directories ([""] for the whole project) or files to check.

Configuration

[processor.checker.encoding]
src_dirs = ["src", "docs"]

Batch support

Files are checked individually within a batch, so one bad file fails only its own product.

Clean behavior

This processor is a Checker — rsconstruct clean outputs is a no-op for it (checkers produce no outputs). See Clean behavior and rsconstruct clean.

ESLint Processor

Purpose

Lints JavaScript and TypeScript files using ESLint.

A Rust alternative is oxlint: a single static binary that reads an ESLint-style config and needs no node runtime. A second is biome, whose linter covers JavaScript and TypeScript too.

How It Works

Discovers .js, .jsx, .ts, .tsx, .mjs, and .cjs files in the project (excluding common build tool directories), runs eslint on each file, and records success in the cache. A non-zero exit code from eslint fails the product.

This processor supports batch mode, allowing multiple files to be checked in a single eslint invocation for better performance.

If an ESLint config file exists (.eslintrc* or eslint.config.*), it is automatically added as an extra input so that configuration changes trigger rebuilds.

Source Files

• Input: **/*.js, **/*.jsx, **/*.ts, **/*.tsx, **/*.mjs, **/*.cjs
• Output: none (checker)

Configuration

[processor.checker.eslint]
command = "eslint"
args = []
dep_inputs = []

Batch support

The tool accepts multiple files on the command line. When batching is enabled (default), rsconstruct passes all files in a single invocation for better performance.

Clean behavior

This processor is a Checker — rsconstruct clean outputs is a no-op for it (checkers produce no outputs). See Clean behavior and rsconstruct clean.

Hadolint Processor

Purpose

Lints Dockerfiles using Hadolint.

The Rust alternative is idockerfile: hadolint’s DL rules, pragmas and .hadolint.yaml, in-process, with hadolint’s messages and exit rule. Switching is hadolint → idockerfile in the stanza header. It does not run ShellCheck, so a repo that wants the SC findings on its RUN scripts stays here.

How It Works

Discovers Dockerfile files in the project (excluding common build tool directories), runs hadolint on each file, and records success in the cache. A non-zero exit code from hadolint fails the product.

This processor supports batch mode.

Source Files

• Input: **/Dockerfile
• Output: none (checker)

Configuration

[processor.checker.hadolint]
args = []
dep_inputs = []

Batch support

The tool accepts multiple files on the command line. When batching is enabled (default), rsconstruct passes all files in a single invocation for better performance.

Clean behavior

This processor is a Checker — rsconstruct clean outputs is a no-op for it (checkers produce no outputs). See Clean behavior and rsconstruct clean.

HTMLHint Processor

Purpose

Lints HTML files using HTMLHint.

How It Works

Discovers .html and .htm files in the project (excluding common build tool directories), runs htmlhint on each file, and records success in the cache. A non-zero exit code from htmlhint fails the product.

This processor supports batch mode.

If a .htmlhintrc file exists, it is automatically added as an extra input so that configuration changes trigger rebuilds.

Source Files

• Input: **/*.html, **/*.htm
• Output: none (checker)

Configuration

[processor.checker.htmlhint]
command = "htmlhint"
args = []
dep_inputs = []

Batch support

The tool accepts multiple files on the command line. When batching is enabled (default), rsconstruct passes all files in a single invocation for better performance.

Clean behavior

This processor is a Checker — rsconstruct clean outputs is a no-op for it (checkers produce no outputs). See Clean behavior and rsconstruct clean.

HTMLLint Processor

Purpose

Lints HTML files using htmllint.

How It Works

Discovers .html and .htm files in the project (excluding common build tool directories), runs htmllint on each file, and records success in the cache. A non-zero exit code from htmllint fails the product.

This processor supports batch mode.

Source Files

• Input: **/*.html, **/*.htm
• Output: none (checker)

Configuration

[processor.checker.htmllint]
args = []
dep_inputs = []

Batch support

The tool accepts multiple files on the command line. When batching is enabled (default), rsconstruct passes all files in a single invocation for better performance.

Clean behavior

This processor is a Checker — rsconstruct clean outputs is a no-op for it (checkers produce no outputs). See Clean behavior and rsconstruct clean.

Iactionlint Processor

Purpose

Lints GitHub Actions workflow files with actionlint’s rules. Native (in-process; no Go binary, no network). The Rust alternative to the actionlint processor: it reads the same .github/actionlint.yaml, runs the same checks, and reports the same problems at the same positions, in actionlint’s own words.

How It Works

Each workflow file is parsed into actionlint’s syntax tree and every rule actionlint runs is applied: the structure of the file (syntax-check), every ${{ }} expression parsed and type-checked with the contexts available where it sits (expression), on: events, activity types, filters and cron schedules (events, glob), runs-on labels (runner-label), needs graphs (job-needs), job and step IDs (id), permissions, shell, env, matrix combinations (matrix), credentials, deprecated workflow commands, constant if: conditions (if-cond), uses: of popular actions, local actions and reusable workflows (action, workflow-call). Problems are reported in actionlint’s format, one per line:

.github/workflows/ci.yml:4:14: label "ubuntu-lates" is unknown. available labels are ... [runner-label]
.github/workflows/ci.yml:6:25: property "foo" is not defined in object type {action: string; ...} [expression]
.github/workflows/ci.yml:3:3: "runs-on" section is missing in job "test" [syntax-check]

Any problem fails the file, as any problem makes actionlint exit 1.

What is not ported

actionlint can run shellcheck over run: scripts and pyflakes over Python steps when those tools are installed. Those two rules call external programs and are not part of this processor. A repository that wants its workflow scripts shell-checked keeps the actionlint processor, or checks the scripts another way.

Configuration file

actionlint’s configuration is found the way actionlint finds it: .github/actionlint.yaml, then .github/actionlint.yml, else none. config_file names a file explicitly instead. All of it is honoured: self-hosted-runner.labels (plain names or globs), config-variables (null disables the check, an empty list allows none), and paths with per-path ignore regular expressions matched against error messages.

Popular actions

actionlint knows the inputs and outputs of a few hundred widely used actions (actions/checkout@v4 and friends) and which old versions no longer run on GitHub’s runners. The same data set is embedded here, generated from actionlint’s popular_actions.go by scripts/gen-actionlint-popular-actions.py; re-run it when moving to a newer actionlint release. Local actions (uses: ./path) are read from action.yml in the project, as actionlint reads them; remote actions outside the data set are not fetched, by either tool.

Fidelity

The port follows actionlint v1.7.12 file by file (src/engines/actionlint/ mirrors parse.go, expr_*.go and rule_*.go). It was checked against actionlint’s own test corpus: every one of the 740 problems actionlint reports over its testdata/err, testdata/examples, testdata/ok and testdata/projects cases (local actions, reusable workflows, configuration files included) is reported at the same position with the same message, and nothing else is. Over the fleet’s 343 workflow files in 219 repositories both tools report nothing.

Source Files

• Input: .yml and .yaml files under src_dirs
• Output: none (checker)

The default src_dirs is empty, so a stanza with no src_dirs or src_files checks nothing: name .github/workflows.

The config files (.github/actionlint.yaml, .github/actionlint.yml) are dep_auto inputs: a change to one re-checks every file. A file named by config_file is not tracked automatically; add it to dep_inputs if it lives elsewhere. Local actions and reusable workflows a workflow refers to are read when the workflow is checked; list them in dep_inputs to re-check on their changes.

Configuration

[processor.checker.iactionlint]
src_dirs = [".github/workflows"]

Batch support

Files are checked individually within a batch, so one bad file fails only its own product.

Clean behavior

This processor is a Checker — rsconstruct clean outputs is a no-op for it (checkers produce no outputs). See Clean behavior and rsconstruct clean.

Icheckpatch Processor

Purpose

Checks C source files with the Linux kernel’s checkpatch.pl rules, in-process (no Perl script to download, no Perl). The Rust alternative to the checkpatch processor: a port of checkpatch.pl at kernel commit e5f92606156a, as checkpatch.pl --no-tree -f FILE runs it, so a file gets the same report, message for message, and passes or fails the way checkpatch would exit.

How It Works

Each file goes through what --no-tree -f does to it: the file becomes the new-file diff checkpatch reads (diff -u /dev/null FILE, including its handling of a missing final newline and of binary files), its lines are sanitised as checkpatch sanitises them (comments and the insides of strings blanked), and every check that file mode reaches runs in checkpatch’s order, with checkpatch’s patterns. Those patterns are Perl regular expressions built from each other ($Type, $Declare, $FuncArg, …) and rebuilt while a file is read, as checkpatch learns the file’s own type names: the engine carries a Perl-compatible matcher and interpolates the patterns the way Perl does, so they match what they match in Perl.

Any ERROR, WARNING or CHECK fails the product, with checkpatch’s report as the message:

ERROR: open brace '{' following function definitions go on the next line
#2: FILE: src/bad.c:2:
+int f(void) {

WARNING: space prohibited before semicolon
#3: FILE: src/bad.c:3:
+    return 0 ;

total: 3 errors, 2 warnings, 4 lines checked

As in checkpatch, CHECKs (its --strict messages) are reported only for files under net/, drivers/net/ and drivers/staging/, and long lines are a CHECK in file mode.

[processor.checker.icheckpatch]
src_dirs = ["src"]

Fidelity

Checked against checkpatch.pl (the pinned commit) file by file over the fleet’s 5666 C files, a 12005-file sample of the Linux 7.1.4 tree (C, headers, assembler, device trees, Kconfig, shell, MAINTAINERS, run from the tree’s root so the path-dependent checks apply) and 17117 mutated files: identical output, byte for byte, and the same verdict. That includes checkpatch dying: a macro argument that makes one of its interpolated patterns invalid kills checkpatch, and fails the file here. It also includes checkpatch’s slow corners: one mutant (static ##inline int f(void)) sends checkpatch’s patterns into exponential backtracking, and the port, matching the same patterns the same way, takes as long (that is, forever).

The engine’s unit tests (src/engines/checkpatch/tests.rs) keep it that way: they run checkpatch.pl itself (a missing one fails them) over the files in src/engines/checkpatch/testdata/ and deterministic mutants of them, check the pattern variables against the ones checkpatch builds, and check the matcher against Perl.

Faster than checkpatch.pl: about twice as fast on ordinary sources (the fleet in half the time), as fast on machine-generated register headers, where both spend their time trying type patterns at every identifier.

What is not ported, because --no-tree -f cannot reach it or the processor does not use it: patch and commit-message checks, --fix, the options (each file is checked with checkpatch’s defaults), .checkpatch.conf, spelling (spelling.txt is not installed with the script) and the checks that read a kernel tree. checkpatch’s CamelCase CHECK seeds its word list from a git checkout’s include/*.h; here it starts empty, as checkpatch does outside a git checkout. A file name the shell would split or reinterpret (a space, a quote, $, ;, …) makes checkpatch’s diff fail and the file pass unchecked; the port does the same.

Source Files

• Input: .c and .h files under src_dirs, or the files in src_files
• Output: none (checker)

Configuration

No fields beyond the standard ones.

Switching a repo from checkpatch: [processor.checker.checkpatch] → [processor.checker.icheckpatch].

Batch support

Not used: each file is checked on its own, as checkpatch.pl --no-tree -f FILE checks it, in parallel as separate products. (checkpatch given several files carries state from one to the next, and stops the whole run at an empty one.)

Clean behavior

This processor is a Checker — rsconstruct clean outputs is a no-op for it (checkers produce no outputs). See Clean behavior and rsconstruct clean.

Icheckstyle Processor

Purpose

Checks Java code with Checkstyle’s checks, in-process (no checkstyle program, no Java runtime to install). The Rust alternative to the checkstyle processor: a port of checkstyle 8.36.1, so a file gets the same messages, at the same lines and columns, and passes or fails the way checkstyle would exit.

How It Works

Each file goes through what checkstyle does to it: its Java grammar (the ANTLR 2 lexer and parser checkstyle generates from java.g, with the same lookahead decisions, the same tree and the same parse errors), the comments and Javadoc it records on the way, and the checks the configuration names, walked over the tree as checkstyle’s TreeWalker walks it. Messages are printed as checkstyle prints them, in its order, and a message of severity error fails the product:

[ERROR] src/Bad.java:1: File does not end with a newline. [NewlineAtEndOfFile]
[ERROR] src/Bad.java:1:8: Unused import - java.util.List. [UnusedImports]
[ERROR] src/Bad.java:3:14: Should use uppercase 'L'. [UpperEll]

Messages of severity warning and info are printed and the file passes; ignore hides them. A file checkstyle cannot check (a syntax error, or one of the cases where checkstyle itself throws) fails with the exception checkstyle stops on:

src/Broken.java:2:13: unexpected token: {

The checks are configured as checkstyle is, by a checkstyle.xml:

[processor.checker.icheckstyle]
src_dirs = ["src"]

Implemented modules

Checker (with severity, tabWidth, fileExtensions, charset UTF-8), TreeWalker, NewlineAtEndOfFile, ArrayTypeStyle, CovariantEquals, DefaultComesLast, EmptyStatement, EqualsHashCode, FallThrough, ModifiedControlVariable, OneStatementPerLine, RedundantImport, SimplifyBooleanExpression, SimplifyBooleanReturn, StringLiteralEquality, UnusedImports and UpperEll, each with all its properties, severity, id, tabWidth and <message> overrides. These are the checks of the fleet’s shared checkstyle.xml. Any other module, or a property this port does not reproduce, is a configuration error that names it, so a configuration either runs as checkstyle runs it or does not run.

Fidelity

Checked against checkstyle 8.36.1 over 5169 Java files (the fleet’s 2559, checkstyle’s own sources and the 1700 Java inputs of its test suite, many of them deliberately odd syntax) and 6000 mutated copies (broken quotes, comments, braces and literals, deleted, duplicated and swapped lines), under the fleet’s configuration and two configurations that set every other property: the same messages, line for line, and for every file checkstyle stops on, the same exception (about 4400 of them, parse errors and checkstyle’s own exceptions alike).

It is also lighter: those 5169 files take under a second of CPU, against checkstyle’s 25 seconds (and its JVM).

The engine’s unit tests (src/engines/checkstyle/tests.rs) keep it that way: they run checkstyle 8.36.1 itself (a missing or different version fails them) and the engine over the files in src/engines/checkstyle/testdata/ and deterministic mutants of them, under three configurations, and require the same result for every file.

Known differences: checkstyle checks the files of a run in one process, and two checks carry a little state from one file to the next (the line of the last lambda in OneStatementPerLine); each file here is checked on its own. Messages are English only, ${property} references resolve only through a default, and files are read as UTF-8.

Source Files

• Input: .java files under src_dirs, or the files in src_files
• Output: none (checker)

The default src_dirs is empty, so a stanza with no src_dirs or src_files checks nothing: name the directories ([""] for the whole project) or files to check.

Configuration

A config_file other than checkstyle.xml should also be listed in dep_inputs, so that changing it rebuilds.

Switching a repo from checkstyle: [processor.checker.checkstyle] → [processor.checker.icheckstyle], and args = ["-c", "checkstyle.xml"] is dropped (or becomes config_file for another file name).

Batch support

Not used: checking in-process has no start-up cost for a batch to share, so files are checked in parallel as separate products.

Clean behavior

This processor is a Checker — rsconstruct clean outputs is a no-op for it (checkers produce no outputs). See Clean behavior and rsconstruct clean.

Icpplint Processor

Purpose

Lints C and C++ files with cpplint’s rules, in-process (no cpplint program, no Python). The Rust alternative to the cpplint processor: a port of cpplint 2.0.2, so a file gets the same findings with the same messages, categories and confidence levels, and passes or fails the way cpplint would exit.

How It Works

Each file goes through what cpplint does to it: the four line views (raw, raw strings blanked, comments removed, strings collapsed), the nesting stack of namespaces, classes, extern "C" blocks, constructors and preprocessor branches, the include-order and header-guard state, NOLINT/NOLINTNEXTLINE/NOLINTBEGIN/NOLINTEND suppressions, and every check cpplint has, from legal/copyright to whitespace/todo (the sixty-six categories cpplint --filter= lists). Findings are printed in cpplint’s own format and any finding fails the file:

src/main.cc:0:  No copyright message found.  You should have a line: "Copyright [year] <Copyright Owner>"  [legal/copyright] [5]
src/main.cc:1:  Missing space before {  [whitespace/braces] [5]
src/main.cc:2:  Tab found; better to use spaces  [whitespace/tab] [1]
src/main.cc:2:  Using C-style cast.  Use static_cast<int>(...) instead  [readability/casting] [4]

Header guards are derived the way cpplint derives them: from the path relative to the repository root (the nearest directory with .git, .hg or .svn, or repository), adjusted by root. The file name cpplint sees is the path relative to the project root, which is what cpplint src/foo.cc run from the project root would see, so filters with a file part (-whitespace:src/foo.cc:14) use that path.

Configuration

cpplint’s per-directory configuration files work as they do in cpplint: CPPLINT.cfg (or the file config_file names) is read from the file’s directory upwards until one says set noparent, with filter, exclude_files, linelength, root, headers, extensions and includeorder. Every such file between a source file and the project root is an input of that file’s product, so editing one re-checks the files under it; there is no need to list them in dep_inputs. The TOML fields are cpplint’s command-line options:

[processor.checker.icpplint]
src_dirs = ["src"]
config_file = ".cpplint"
filters = ["-whitespace/tab", "-build/include_order"]
line_length = 100

A file an exclude_files pattern matches is skipped, as cpplint skips it. A configuration file with an option cpplint does not know, a non-numeric linelength, a filter that does not start with + or -, or a file whose extension is not one cpplint accepts fails the build; cpplint prints a message and goes on, which hides the mistake.

Fidelity

Checked against cpplint 2.0.2 over its own sample corpus (samples/*/*.def: seven projects under twelve option sets, including CPPLINT.cfg, --filter, --includeorder=standardcfirst, --headers, --recursive --exclude), the 1245 snippets its unit tests lint, demos-os-linux’s 1231 C/C++ files with and without the repo’s .cpplint, and 3000 mutated copies of those files (tabs, casts, missing spaces, using namespace, VLAs, sprintf, NOLINT variants, header-guard and include edits, CRLF line endings, no final newline): the same findings, file for file. Two things cpplint does are deliberately not reproduced: its “Unexpected \r (^M)” warning, which cpplint itself can never emit because Python’s text mode translates line endings before it looks; and the way a linelength, root, headers or extensions setting read from one directory’s CPPLINT.cfg stays in force for every file cpplint processes afterwards in the same run (here every file starts from the configured options).

Source Files

• Input: .c, .cc, .cpp, .cxx, .c++, .cu, .h, .hh, .hpp, .hxx, .h++, .cuh files under src_dirs, or the files in src_files
• Output: none (checker)

The default src_dirs is empty, so a stanza with no src_dirs or src_files checks nothing: name the directories ([""] for the whole project) or files to check.

Configuration

Switching a repo from cpplint: [processor.checker.cpplint] → [processor.checker.icpplint], and args = ["--config=.cpplint"] becomes config_file = ".cpplint". Any other --option=value in args becomes the field of the same name.

Batch support

Files are checked individually within a batch, so one bad file fails only its own product.

Clean behavior

This processor is a Checker — rsconstruct clean outputs is a no-op for it (checkers produce no outputs). See Clean behavior and rsconstruct clean.

Idockerfile Processor

Purpose

Lints Dockerfiles with hadolint’s rules, in-process (no hadolint binary). The Rust alternative to the hadolint processor: a port of hadolint 2.15.1’s Dockerfile parser, its # hadolint ignore= pragmas, its .hadolint.yaml configuration and all of its DL rules, so a Dockerfile gets the same findings, with the same messages, codes and severities, and passes or fails the way hadolint would exit.

What is not here is ShellCheck. hadolint runs ShellCheck over every RUN script and reports its SC codes alongside its own; ShellCheck is a separate program with no Rust counterpart, so idockerfile reports DL findings only. A repo that wants the SC findings keeps the hadolint processor.

How It Works

Each Dockerfile is parsed the way hadolint’s parser (language-docker) reads it: instructions and their flags, escaped line breaks, heredocs, the # escape= and # syntax= pragmas, exec-form JSON arrays. RUN scripts are read as hadolint reads them for its rules: which commands run, with which arguments and flags, including commands inside $(...), if, loops and subshells, and whether anything is piped. The 71 DL rules then run over the result, from DL3000 (absolute WORKDIR) through the package-manager rules (apt-get, apk, pip, npm, gem, yum, dnf, zypper, go, yarn) to DL4006 (pipefail). Findings are printed in hadolint’s own format:

Dockerfile:1 DL3006 warning: Always tag the version of an image explicitly
Dockerfile:4 DL3008 warning: Pin versions in apt get install. Instead of `apt-get install <package>` use `apt-get install <package>=<version>`
Dockerfile:4 DL3015 info: Avoid additional packages by specifying `--no-install-recommends`
Dockerfile:7 DL3059 info: Multiple consecutive `RUN` instructions. Consider consolidation.

A file fails when any finding is at least as severe as the failure threshold (info by default, like hadolint: error and warning and info fail, style does not). A file whose only findings are below the threshold passes, and nothing is printed for it. A Dockerfile hadolint’s parser cannot read fails with the position of the problem.

Configuration

idockerfile reads .hadolint.yaml (or .hadolint.yml) from the project root when one exists, exactly as hadolint run from there would, with the keys hadolint’s checks use: ignored, override (error, warning, info, style lists), trustedRegistries, label-schema, strict-labels, disable-ignore-pragma, failure-threshold, no-fail. config_file names a different file. The TOML fields below add to or override what the file says. Inline pragmas work as in hadolint: # hadolint ignore=DL3008,DL3015 for the next instruction, # hadolint stage ignore=... for the rest of the stage, # hadolint global ignore=... for the file.

[processor.checker.idockerfile]
src_files = ["Dockerfile", "docker/api/Dockerfile"]
ignored = ["DL3059"]
failure_threshold = "warning"

Fidelity

Checked against hadolint 2.15.1 over the fleet’s 154 Dockerfiles, with and without the fleet’s .hadolint.yaml, and over 2000 mutated copies (unpinned installs, missing -y, sudo, cd, pipes, untagged and latest images, bad COPY --from references, duplicate stage names, ONBUILD wrappers, pragmas, heredocs, lower-cased keywords, exec-form commands): the same DL findings, file for file. Two things had to be copied from hadolint rather than reasoned out: its tree walk yields every shell command twice (once for ShellCheck’s redirection wrapper, once for the command), which is what makes DL3059 fire only for single-command RUNs; and a RUN script ShellCheck cannot parse (an unterminated quote, a redirection without a target) contributes no commands at all. One known divergence: hadolint 2.15.1 rejects a heredoc followed directly by the next instruction (a bug in its parser release, fixed upstream since); idockerfile accepts it.

Source Files

• Input: files named Dockerfile under src_dirs, or the files in src_files
• Output: none (checker)

The default src_dirs is empty, so a stanza with no src_dirs or src_files checks nothing: name the directories ([""] for the whole project) or files to check.

Configuration

Switching a repo from hadolint: [processor.checker.hadolint] → [processor.checker.idockerfile]; the .hadolint.yaml stays as it is. A repo whose findings include SC codes it wants to keep stays on hadolint.

Batch support

Files are checked individually within a batch, so one bad file fails only its own product.

Clean behavior

This processor is a Checker — rsconstruct clean outputs is a no-op for it (checkers produce no outputs). See Clean behavior and rsconstruct clean.

Ijq Processor

Purpose

Checks that JSON files parse. Native (in-process, using serde_json; no external tools required). It is the in-process counterpart of jq, but it only parses: no jq filter is evaluated.

How It Works

Each file is read and parsed as JSON. A file that does not parse fails its product with an Invalid JSON: message giving the position.

The check is identical to ijsonlint; use whichever name reads better in your config. Duplicate keys are accepted (the last value wins).

Source Files

• Input: .json files under src_dirs
• Output: none (checker)

The default src_dirs is empty, so a stanza with no src_dirs or src_files checks nothing: name the directories ([""] for the whole project) or files to check.

Configuration

[processor.checker.ijq]
src_dirs = ["data"]

Batch support

Files are checked individually within a batch, so one bad file fails only its own product.

Clean behavior

This processor is a Checker — rsconstruct clean outputs is a no-op for it (checkers produce no outputs). See Clean behavior and rsconstruct clean.

Ijsonlint Processor

Purpose

Checks that JSON files parse. Native (in-process, using serde_json; no external tools required). A Rust alternative to jsonlint.

How It Works

Each file is read and parsed as JSON. A file that does not parse fails its product with the parser’s message and position:

data/bad.json: [processor.checker.ijsonlint] Invalid JSON:
data/bad.json: trailing comma at line 1 column 9

This is a well-formedness check only. There are no style rules, and duplicate keys are accepted (the last value wins).

Source Files

• Input: .json files under src_dirs
• Output: none (checker)

The default src_dirs is empty, so a stanza with no src_dirs or src_files checks nothing: name the directories ([""] for the whole project) or files to check.

Configuration

[processor.checker.ijsonlint]
src_dirs = [""]

Batch support

Files are checked individually within a batch, so one bad file fails only its own product.

Clean behavior

This processor is a Checker — rsconstruct clean outputs is a no-op for it (checkers produce no outputs). See Clean behavior and rsconstruct clean.

Iluacheck Processor

Purpose

Lints Lua files with luacheck’s analysis, in-process (no luacheck program, no Lua runtime to install). The Rust alternative to the luacheck processor: a port of luacheck 1.2.0, so a set of files gets the same findings with the same codes and messages, and passes or fails the way luacheck would exit.

How It Works

Each file goes through what luacheck does to it: its lexer and parser (Lua 5.1 through 5.4 and LuaJIT syntax: goto and labels, integer division and bitwise operators, <const>/<close> attributes, compound assignments, cdata literals), the linearized flow graph of every function, the resolution of which assignments reach which accesses (closures included), and every check luacheck has: globals and their fields traced through local t = table, unused and overwritten variables, values and arguments, shadowing, unreachable code, empty blocks, unbalanced assignments, duplicate table keys, cyclomatic complexity, whitespace and line length. -- luacheck: inline comments (ignore, globals, push/pop, …) apply as in luacheck, including their errors. Findings are printed as luacheck --formatter plain --codes prints them, and any finding fails the build:

config/project.lua:1:7: (W211) unused variable 'x'
config/project.lua:2:1: (W111) setting non-standard global variable 'Y'
config/project.lua:4:1: (E011) expected 'end' (to close 'if' on line 1) near 'local' (indentation-based guess)

All the files of a stanza are checked together, as one luacheck run checks the files given to it: with allow_defined or allow_defined_top, a global set in one file is defined for all the others, and an implicitly defined global no file reads is reported as unused (W131). The processor therefore makes a single product of all its files, rechecked as a whole when any of them changes.

Configuration

.luacheckrc is found and run as luacheck runs it: looked up from the project root upwards, executed as Lua (in the embedded interpreter) in an environment that falls back to the standard globals, with files["glob"] per-path overrides, custom stds, and a returned table merged in. luacheck’s default per-path stds apply (busted for *_spec.lua under spec/, test/ or tests/, rockspec, luacheckrc, ldoc). exclude_files and include_files filter the checked files as in luacheck. config_file names a different file; empty means no configuration file (--no-config).

The TOML fields are luacheck’s command-line options and override the configuration file the same way:

[processor.checker.iluacheck]
src_dirs = ["config"]
std = "lua54"
globals = ["vim"]
ignore = ["212/self"]
max_line_length = 100

Fidelity

Checked against luacheck 1.2.0 (the apt package, which runs on Lua 5.1) over the 7101 Lua files on a development machine (Neovim plugins, nmap’s NSE libraries, TeX Live, lua-language-server, ardour scripts), luacheck’s own sources and samples, the fleet’s Lua files, and 3000 mutated copies (broken tokens and escapes, missing ends, labels and goto, varargs, attributes, compound operators, duplicate keys, inline options valid and invalid), under default options, ten command-line option sets and three .luacheckrc configurations: the same findings, line for line (about 2.4 million compared). Configuration errors give luacheck’s messages. One difference is inherent: a runtime error raised inside .luacheckrc is worded by the interpreter running it, Lua 5.4 here and Lua 5.1 in luacheck (attempt to index a nil value (local 't') instead of attempt to index local 't' (a nil value)).

Not supported: the global configuration file (~/.config/luacheck/.luacheckrc), checking rockspecs as file lists, the cache, and luacheck’s output formatters other than plain with codes.

Source Files

• Input: .lua files under src_dirs, or the files in src_files
• Output: none (checker)

The default src_dirs is empty, so a stanza with no src_dirs or src_files checks nothing: name the directories ([""] for the whole project) or files to check.

Configuration

Switching a repo from luacheck: [processor.checker.luacheck] → [processor.checker.iluacheck]; the .luacheckrc stays as it is, and options in args become the fields of the same name (args = ["--globals", "vim", "--"] becomes globals = ["vim"]).

Batch support

Not applicable: the processor’s one product covers all its files.

Clean behavior

This processor is a Checker — rsconstruct clean outputs is a no-op for it (checkers produce no outputs). See Clean behavior and rsconstruct clean.

Iperlcritic Processor

Purpose

Checks Perl code with Perl::Critic’s policies, in-process (no perlcritic program, no Perl to install). The Rust alternative to the perlcritic processor: a port of Perl::Critic 1.156 and of PPI 1.284, the Perl parser under it, so a file gets the same violations, at the same lines and columns, and passes or fails the way perlcritic would exit.

How It Works

Each file goes through what Perl::Critic does to it: PPI’s tokenizer and lexer (with the same guesses PPI makes where Perl’s grammar needs a runtime to decide — regex or division, hash or block, prototype or signature — the same tree, and the same parse errors), the ## no critic annotations, and the policies the profile enables, each over the elements it applies to. Violations are printed in the profile’s verbose format, sorted by position as perlcritic sorts them, and any violation fails the product:

src/bad.pl:1:1: [TestingAndDebugging::RequireUseStrict] Code before strictures are enabled
src/bad.pl:3:1: [InputOutput::ProhibitTwoArgOpen] Two-argument "open" used
src/bad.pl:4:9: [Subroutines::ProhibitExplicitReturnUndef] "return" statement with explicit "undef"

A file PPI cannot parse fails with perlcritic’s message:

Problem while critiquing "src/broken.pl": Can't parse code: Encountered unexpected character '195'

The policies are configured as Perl::Critic’s are, by a profile (.perlcriticrc):

[processor.checker.iperlcritic]
src_dirs = [""]

Implemented policies

The 22 policies of severity 5 (gentle), which are what Perl::Critic’s default profile and the fleet’s shared .perlcriticrc enable: BuiltinFunctions::ProhibitSleepViaSelect, ProhibitStringyEval, RequireGlobFunction, ClassHierarchies::ProhibitOneArgBless, ControlStructures::ProhibitMutatingListFunctions, InputOutput::ProhibitBarewordDirHandles, ProhibitBarewordFileHandles, ProhibitInteractiveTest, ProhibitTwoArgOpen, RequireEncodingWithUTF8Layer, Modules::ProhibitEvilModules, RequireBarewordIncludes, RequireFilenameMatchesPackage, Subroutines::ProhibitExplicitReturnUndef, ProhibitNestedSubs, ProhibitReturnSort, ProhibitSubroutinePrototypes, TestingAndDebugging::ProhibitNoStrict, RequireUseStrict, ValuesAndExpressions::ProhibitLeadingZeros, Variables::ProhibitConditionalDeclarations and RequireLexicalLoopIterators, each with all its parameters, plus severity and maximum_violations_per_document.

The profile’s global options severity, verbose (a number or a format, every % field except %d), force, only, include, exclude, top and program-extensions work as in perlcritic, as do [Policy] and [-Policy] sections. A profile that enables a policy this port does not implement (say severity = 4, or [CodeLayout::ProhibitHardTabs] raised to severity = 5) is an error naming it, as are theme and single-policy, so a profile either runs as perlcritic runs it or does not run. Without a profile file, Perl::Critic’s defaults apply (severity 5); perlcritic’s fallback to ~/.perlcriticrc is not taken, so the build does not depend on the home directory.

Fidelity

Checked against Perl::Critic 1.156 on PPI 1.284 over the fleet’s 1313 Perl files, the 3950 modules of a Debian Perl installation (/usr/share/perl5 and the architecture-specific tree), 207 hand-written edge cases (heredocs, formats, __END__/__DATA__, POD, prototypes and signatures under every way of enabling them, #line directives, byte order marks, CR and CRLF line ends, every policy’s exemptions) and 12300 mutated copies: the same PPI tree for every file (every element, every token’s content and location) and the same report, violation for violation. That includes PPI’s failures: a character it cannot tokenize, and the cases where a use statement’s version or arguments make version.pm or PPI’s own feature detection die.

The engine’s unit tests (src/engines/perlcritic/tests.rs) keep it that way: they run PPI and Perl::Critic themselves (a missing or different version fails them) and the engine over the files in src/engines/perlcritic/testdata/ and deterministic mutants of them, comparing trees and reports under five profiles.

Known differences: when a policy dies on a file (a few malformed argument lists make Perl::Critic call a method on a list), perlcritic stops the whole run with Perl’s message, which names a line of its own source; here only that file fails, with the same first words. Where PPI’s feature detection dies on a string argument that names a Perl package already loaded in perlcritic’s process (use feature 'strict', (...)), Perl’s message lacks the “perhaps you forgot to load” hint that the port always gives. The default verbosity (4) prints as verbosity 5, with the file name, as perlcritic does when it is given several files, which a build always does.

Source Files

• Input: .pl and .pm files under src_dirs, or the files in src_files
• Output: none (checker)

The default src_dirs is empty, so a stanza with no src_dirs or src_files checks nothing: name the directories ([""] for the whole project) or files to check.

Configuration

A profile other than .perlcriticrc should also be listed in dep_inputs, so that changing it rebuilds.

Switching a repo from perlcritic: [processor.checker.perlcritic] → [processor.checker.iperlcritic]; the fleet’s .perlcriticrc needs no change.

Batch support

Not used: checking in-process has no start-up cost for a batch to share, so files are checked in parallel as separate products.

Clean behavior

This processor is a Checker — rsconstruct clean outputs is a no-op for it (checkers produce no outputs). See Clean behavior and rsconstruct clean.

Ishellcheck Processor

Purpose

Lints shell scripts with ShellCheck’s analysis, in-process (no shellcheck program, no Haskell runtime to install). The Rust alternative to the shellcheck processor: a port of ShellCheck 0.11.0, so a script gets the same findings with the same codes, positions and messages, and passes or fails the way shellcheck would exit.

How It Works

Each file goes through what ShellCheck does to it: its parser (sh, bash, dash, ksh and busybox dialects, here-documents, arithmetic, [[ ]] conditions, the parse errors and their notes), the control flow graph and its dataflow analysis (which assignments reach which uses, through functions and subshells), and every check of ShellCheck’s Analytics, Commands and ShellSupport modules, optional checks included. The dialect comes from shell, a # shellcheck shell= directive, the shebang or the file extension, in ShellCheck’s order. # shellcheck directives (disable, enable, source, source-path, external-sources, extended-analysis) and .shellcheckrc files (looked up from the script’s directory upwards, then in ~/.shellcheckrc and the XDG config directory) apply as in ShellCheck. Findings are printed as shellcheck --format=gcc prints them, and any finding fails the product:

src/bad.sh:2:1: warning: foo appears unused. Verify use (or export if used externally). [SC2034]
src/bad.sh:3:6: note: Double quote to prevent globbing and word splitting. [SC2086]

Each file is its own product, checked as shellcheck FILE checks it: sourced files are read only with external_sources, and their findings are reported only with check_sourced.

[processor.checker.ishellcheck]
src_dirs = ["scripts"]
exclude = ["SC1091"]
severity = "warning"

Fidelity

Checked against shellcheck 0.11.0 over 4494 real scripts (1850 from the fleet, 2644 from a development machine’s /usr/bin and friends), the 2194 snippets of ShellCheck’s own unit tests, and 28000 mutated copies (broken quotes, brackets and keywords, swapped operators, deleted and duplicated lines): the same findings, line for line (about 360,000 compared), under default options, each shell override, external_sources and check_sourced. Neither side crashes on any of them.

It is also faster and smaller than shellcheck: 2781 real scripts (the fleet’s and a development machine’s) take 2.3 seconds against shellcheck’s 15.7 on 16 threads (18 against 137 seconds of CPU), and the largest script, a 3500-line dkms, takes 1.0 second and 400 MB against 6.4 seconds and 1.9 GB.

The engine’s unit tests (src/engines/shellcheck/tests.rs) keep it that way: they run shellcheck 0.11.0 itself (a missing or different version fails them) and the engine over the scripts in src/engines/shellcheck/testdata/ and deterministic mutants of them, under each option, and require the same output line for line. The processor’s tests check that each TOML field matches the shellcheck option of the same name.

Not supported: output formats other than gcc, auto-fixes (--format=diff), and the --wiki-link-count/--color presentation options.

Source Files

• Input: .sh and .bash files under src_dirs, or the files in src_files
• Output: none (checker)

The default src_dirs is empty, so a stanza with no src_dirs or src_files checks nothing: name the directories ([""] for the whole project) or files to check.

Configuration

Switching a repo from shellcheck: [processor.checker.shellcheck] → [processor.checker.ishellcheck]; a .shellcheckrc stays as it is, and options in args become the fields of the same name (args = ["-e", "SC1091", "-S", "warning"] becomes exclude = ["SC1091"], severity = "warning").

Batch support

Not used: checking in-process has no start-up cost for a batch to share, so files are checked in parallel as separate products.

Clean behavior

This processor is a Checker — rsconstruct clean outputs is a no-op for it (checkers produce no outputs). See Clean behavior and rsconstruct clean.

Isvglint Processor

Purpose

Lints SVG files with svglint’s rules, in-process (no Node, no svglint binary). The Rust alternative to the svglint processor: a port of svglint 4.2.1’s three built-in rules and of the machinery they run on, so a file gets the same findings, with the same messages, as svglint would give it under the same rules.

How It Works

Each file is parsed the way svglint parses it (htmlparser2 in XML mode, leniently: an unclosed tag closes at the end of the file, a repeated attribute keeps its first value, entities stay as written), then every configured rule runs over the result:

• valid (on by default) checks that the file is well-formed XML, with fast-xml-parser’s validator and its messages.
• elm checks which elements appear, by CSS selector: present, absent, an exact count or a range.
• attr checks the attributes of the elements a CSS selector picks: required, forbidden, exact values, one of several values, a regular expression, attribute order and a whitelist.

svglint’s custom rules are JavaScript functions and have no counterpart. Findings are printed one per line, the rule’s name as svglint shows it (valid, elm, attr-1 for the first attr table, …), with the element and its position when there is one:

img/icon.svg:1:1: attr-1: Wrong ordering of attributes, found "xmlns, viewBox, role", expected "role, viewBox, xmlns" (<svg>)
img/icon.svg:3:3: attr-2: Expected attribute 'fill' to be one of ["red","blue"], was "green" (<path>)
img/icon.svg:4:3: elm: Element disallowed (<rect>)
img/icon.svg: elm: Found 0 elements for 'svg > title', expected 1
img/icon.svg: valid: Attribute 'fill' is repeated.

Any finding fails the file, as svglint’s exit status does. Positions are 1-based line and column of the element’s start tag (svglint’s own output prints them 0-based and miscounts lines after a leading newline; the elements are the same).

Rules in TOML

svglint reads its rules from a JavaScript file; isvglint takes the same rules as TOML in the stanza:

[processor.checker.isvglint]
src_dirs = ["icons"]

[processor.checker.isvglint.elm]
"svg" = 1               # exactly one
"svg > title" = true    # at least one
"svg > path" = [1, 3]   # between one and three
"*" = false             # nothing else (an element another rule allows is fine)

[[processor.checker.isvglint.attr]]
"rule::selector" = "svg"
"rule::whitelist" = true          # no attributes beyond those named here
"rule::order" = true              # alphabetical; or a list giving the order
xmlns = "http://www.w3.org/2000/svg"
role = "img"
viewBox = { regex = "^0 0 \\d+ \\d+$" }
"width?" = true                   # optional: checked when present

[[processor.checker.isvglint.attr]]
"rule::selector" = "svg > path"
d = { regex = "^m[-mzlhvcsqtae\\d,. ]+$", flags = "i" }
fill = ["red", "blue"]
onclick = false

An attr value is true (must exist), false (must not), a string (that exact value), an array of strings (one of them) or { regex = "...", flags = "..." } (a JavaScript-style regular expression; flags take i, m, s). A key ending in ? is optional. Selectors follow css-select’s XML-mode semantics: case-sensitive names, #id, .class, all attribute operators including != and the i flag, the four combinators, selector lists, :not, :is, :has (with a leading combinator), the -child and -of-type families with An+B, :empty, :contains, :icontains. A selector using anything else (pseudo-elements, :root, :scope, namespaces) is a configuration error, as is a rule value of the wrong shape; svglint would warn and go on.

With no elm or attr configured, only valid runs, exactly like svglint without a .svglintrc.js.

Fidelity

Checked against svglint 4.2.1 over the fleet’s 5776 tracked SVG files and 3000 mutated copies of them (dropped and renamed closing tags, duplicate, unquoted, valueless and boolean attributes, stray ampersands, extra roots, truncation, misplaced XML declarations, CDATA and comment edge cases, byte order marks, control characters), under the default rules and two rule sets exercising every selector feature and attribute check above: the same findings, file for file. The lenient parser is a step-for-step port of htmlparser2 3.10.1, including how it chains one node’s start position from the previous node’s end; the validator is a port of fast-xml-parser 5.10.1, including that a self-closing root is never “multiple roots” and that an XML declaration after a tag is read as an instruction named ?xml and passes.

Source Files

• Input: .svg files under src_dirs
• Output: none (checker)

The default src_dirs is empty, so a stanza with no src_dirs or src_files checks nothing: name the directories ([""] for the whole project) or files to check.

Configuration

Switching a repo from svglint: [processor.checker.svglint] → [processor.checker.isvglint]; the rules of .svglintrc.js become the elm table and attr tables above (a /regex/i literal is { regex = "regex", flags = "i" }); custom rules have to stay with svglint.

Batch support

Files are checked individually within a batch, so one bad file fails only its own product.

Clean behavior

This processor is a Checker — rsconstruct clean outputs is a no-op for it (checkers produce no outputs). See Clean behavior and rsconstruct clean.

Itaplo Processor

Purpose

Checks that TOML files parse. Native (in-process, using the toml crate; no external tools required). An in-process alternative to taplo.

How It Works

Each file is read and parsed as TOML. A file that does not parse fails its product with the parser’s message and a pointer to the position:

bad.toml: [processor.checker.itaplo] Invalid TOML:
bad.toml: TOML parse error at line 1, column 5
  |
1 | a =
  |     ^
string values must be quoted, expected literal string

Only syntax is checked. Unlike taplo check, there is no schema validation and no .taplo.toml is read.

Source Files

• Input: .toml files under src_dirs
• Output: none (checker)

The default src_dirs is empty, so a stanza with no src_dirs or src_files checks nothing: name the directories ([""] for the whole project) or files to check.

Configuration

[processor.checker.itaplo]
src_dirs = [""]

Batch support

Files are checked individually within a batch, so one bad file fails only its own product.

Clean behavior

This processor is a Checker — rsconstruct clean outputs is a no-op for it (checkers produce no outputs). See Clean behavior and rsconstruct clean.

Itidy Processor

Purpose

Checks HTML files the way tidy -errors does: structure, missing and misplaced tags, unknown elements, attributes and attribute values, entities, and the repairs tidy would make. Native (in-process; no tidy binary). The Rust alternative to the tidy processor: a port of HTML Tidy 5.8.0’s lexer, parser, attribute checks and clean-up passes, so it reports what tidy reports, at the same line and column, with the same warning and error totals. The pretty-printer is not ported: itidy never writes HTML.

How It Works

Each file is tokenized and parsed with tidy’s own algorithm, element by element, inferring the start and end tags the markup leaves out, moving misplaced content where tidy moves it and reporting every repair. The attribute checks (which attributes an element allows in the document’s HTML version, their values, id and name uniqueness, URIs) and the clean-up passes that follow parsing (style elements in the body, the meta charset, the doctype, HTML5-removed elements, proprietary elements and attributes) run as well. Problems are reported in tidy’s format, with the file in front:

docs/page.html: line 3 column 7 - Error: <foo> is not recognized!
docs/page.html: line 3 column 7 - Warning: discarding unexpected <foo>
docs/page.html: line 12 column 5 - Warning: <img> lacks "alt" attribute
docs/page.html: line 20 column 1 - Warning: trimming empty <p>
docs/page.html: line 31 column 17 - Warning: <div> proprietary attribute "ng-model"

The verdict is tidy’s: a file with warnings or errors fails (tidy exits 1 or 2), a clean file passes. The totals follow tidy’s counting, including the fact that tidy stops printing reports after show-errors (6) errors while still counting them. Only the report lines are printed; tidy’s trailing dialogue (“Tidy found 2 warnings and 1 error!”, “This document has errors that must be fixed…”) carries nothing a build needs and is left out, as are the Info: lines -q hides.

Options

tidy’s options drive the checks exactly as they drive tidy. config_file names a tidy configuration file (name: value lines, # comments, continuation lines), read like tidy -config FILE. The file is an input of every product, so editing it re-checks every file; there is no need to list it in dep_inputs. options lists further settings as "name: value" strings, applied after the file in order, like --name value arguments:

[processor.checker.itidy]
src_dirs = ["docs"]
options = ["custom-tags: blocklevel", "drop-empty-elements: no"]

Every option of tidy 5.8.0 is accepted and its value validated, so an existing tidy configuration parses unchanged. Options that only shape tidy’s pretty-printed output (indent, wrap, output-file, …) are ignored. A few are refused by name because itidy does not reproduce their effect: clean, gdoc, bare, word-2000 and logical-emphasis set to yes, input-xml: yes, accessibility-check above 0, mute, and any input or output encoding other than utf8. An unknown option is a build error, where tidy prints a notice and carries on.

Input is UTF-8 (a UTF-8 byte order mark is accepted; a UTF-16 one is an error naming the file). Tabs count as tab-size (8) columns, as in tidy, so column numbers agree.

Fidelity

Checked against tidy -errors -q 5.8.0 over the fleet’s 599 tracked HTML files and 6000 mutated copies of them (dropped and swapped tags, unquoted and duplicated attributes, bad entities, truncated files, control characters, invalid UTF-8, deprecated elements, misplaced list items and table cells): identical report lines, in the same order, for every file, under the default options and under the fleet’s option sets (custom-tags, drop-empty-elements, new-blocklevel-tags, drop-empty-paras, warn-proprietary-attributes). The quirks this required are documented in the source: tidy treats an empty attribute value as absent, does not count an ESC character as a column, and reads a byte past the end of an emptied text node to decide whether it was blank.

Source Files

• Input: .html and .htm files under src_dirs
• Output: none (checker)

The default src_dirs is empty, so a stanza with no src_dirs or src_files checks nothing: name the directories ([""] for the whole project) or files to check.

Configuration

[processor.checker.itidy]
src_dirs = ["docs"]
config_file = "support/tidy.conf"
options = ["warn-proprietary-attributes: no"]

Switching a repo from tidy: [processor.checker.tidy] → [processor.checker.itidy]; args = ["-config", "x.conf"] → config_file = "x.conf"; args = ["--name", "value"] → options = ["name: value"]; -errors, -q and -utf8 are the behaviour already and are dropped.

Batch support

Files are checked individually within a batch, so one bad file fails only its own product.

Clean behavior

This processor is a Checker — rsconstruct clean outputs is a no-op for it (checkers produce no outputs). See Clean behavior and rsconstruct clean.

Ixmllint Processor

Purpose

Checks that XML files are well-formed and, with schema, that they validate against an XSD schema. Native (in-process; no libxml2, no external tools). The Rust alternative to the xmllint processor: it reports what xmllint --noout and xmllint --noout --schema x.xsd report, at the same line, with the same verdict.

How It Works

Each file is decoded as its XML declaration says (UTF-8 by default; UTF-16, ISO-8859-1 and US-ASCII are understood, another declared encoding is an error), tokenized, and checked for everything xmllint checks: tag matching, duplicate attributes, entity and character references against the internal DTD subset, namespace declarations and prefixes, and the document’s shape. Problems are reported in xmllint’s format, one per line:

test.xml:3: parser error : Opening and ending tag mismatch: b line 2 and a
test.xml:6: parser error : Attribute b redefined
test.xml:1: namespace error : Namespace prefix x on b is not defined
test.xml:7: Schemas validity error : Element '{urn:keynote}slidex': This element is not expected. Expected is ( {urn:keynote}slide ).

The verdict is xmllint’s. A parser error (the file is not XML) or a Schemas validity error fails the file. A namespace error, namespace warning or parser warning is printed and the file passes, because xmllint exits 0 on those; strict = true makes them fail too.

Where xmllint reports a problem is reproduced as well: a duplicate attribute, an undeclared prefix or a schema violation is reported on the line where the element’s start tag ends (libxml2 checks the tag once it is complete and stamps the node with that line), an unfinished document on its last line, and only when nothing else went wrong first.

Schema validation

schema names an XSD file, relative to the project root, like --schema. Every file must validate against it; the schema is read once per build. The schema file is an input of every product, so a change to it re-checks every file; there is no need to list it in dep_inputs.

The validator implements the schema constructs in use: global and local elements, named and anonymous complex types with sequence, choice and all content models (with minOccurs/maxOccurs), any, mixed and simple content, attributes with use and fixed, anyAttribute, simple types restricted by the standard facets (enumeration, pattern, lengths, bounds, digits, whiteSpace), list and union, extension of simple and complex types, include, and the built-in types from xs:string to xs:dateTime. A schema using anything else (group, attributeGroup, import, redefine, key/unique, substitution groups, abstract, complex-type restriction, xsi:type in a document) is a build failure naming the construct and its line: a schema that is only half enforced would pass files xmllint rejects. Keep such a file on the xmllint processor, or extend src/engines/xmllint/xsd.rs.

Messages follow xmllint’s wording (This element is not expected. Expected is ( ... )., The attribute 'a' is required but missing., 'x' is not a valid value of the atomic type 'xs:int'., [facet 'enumeration'] The value 'v' is not an element of the set {'a', 'b'}.).

Fidelity

Checked against xmllint (libxml2 2.15) over the fleet’s 6256 tracked XML and SVG files plus 58 hand-made edge cases: every file gets the same verdict, every problem is reported at the same line with the same class, and the messages read the same. Schema validation was checked over the one fleet schema (java-keynote) with its presentations and eight mutations of them: identical reports, line for line.

Two differences remain. After a lexical error (a bad comment, an invalid character), xmllint keeps parsing and may report further problems; ixmllint stops at that error, which is already fatal. And xmllint’s parser does not load external DTDs, nor does ixmllint, so neither validates against a DTD; --valid, --dtdvalid and --relaxng have no counterpart here.

Source Files

• Input: .xml and .svg files under src_dirs
• Output: none (checker)

The default src_dirs is empty, so a stanza with no src_dirs or src_files checks nothing: name the directories ([""] for the whole project) or files to check.

Configuration

[processor.checker.ixmllint]
src_dirs = ["src"]

[processor.checker.ixmllint.presentations]
src_dirs = ["presentations"]
schema = "xsd/keynote.xsd"

Batch support

Files are checked individually within a batch, so one bad file fails only its own product.

Clean behavior

This processor is a Checker — rsconstruct clean outputs is a no-op for it (checkers produce no outputs). See Clean behavior and rsconstruct clean.

Iyamllint Processor

Purpose

Lints YAML files with yamllint’s rules. Native (in-process; no Python, no external tools). The Rust alternative to the yamllint processor: it reads the same .yamllint.yaml, runs the same 23 rules with the same options, and reports the same problems at the same positions.

How It Works

Each file is tokenized (with libyaml, the scanner design yamllint’s PyYAML implements too), then every enabled rule runs over its tokens, comments and lines, exactly as in yamllint’s linter.py. Problems are reported in yamllint’s parsable format, one per line:

test.yaml:2:11: [error] trailing spaces (trailing-spaces)
test.yaml:4:7: [error] wrong indentation: expected 4 but found 6 (indentation)
test.yaml:1:1: [warning] missing document start "---" (document-start)

A problem at the error level fails the file. A warning is printed and the file passes, as a plain yamllint run passes; strict = true makes warnings fail too, like yamllint --strict.

Configuration file

The yamllint configuration is found the way yamllint finds it: .yamllint, .yamllint.yaml or .yamllint.yml in the project root, in that order, else yamllint’s built-in default configuration. config_file names a file explicitly instead. The user-level ~/.config/yamllint/config that yamllint also consults is not read: a build must not depend on the machine it runs on.

Everything in yamllint’s configuration format is supported, with two exceptions:

• extends (default, relaxed, or a path relative to the project root), rules with enable/disable/settings, level, every rule option, ignore and ignore-from-file at the top level and per rule: all honoured, with yamllint’s own validation errors for an unknown rule, an unknown option or a wrong value. An invalid config fails the build.
• yaml-files is accepted and ignored: rsconstruct decides which files the processor scans, through src_dirs, src_files and src_extensions.
• locale is rejected. It changes how key-ordering collates; this processor compares code points, which is what yamllint does when no locale is set.

Rules

All 23 rules: anchors, braces, brackets, colons, commas, comments, comments-indentation, document-end, document-start, empty-lines, empty-values, float-values, hyphens, indentation, key-duplicates, key-ordering, line-length, new-line-at-end-of-file, new-lines, octal-values, quoted-strings, trailing-spaces, truthy. See yamllint’s rule documentation for their options.