Processors

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

Processor Types

Processors are classified into three types:

• Generators — produce real output files from input files (e.g., compiling code, rendering templates, transforming file formats)
• Checkers — validate input files without producing output files (e.g., linters, spell checkers, static analyzers). Success is recorded in the cache database.
• Mass generators — produce a directory of output files without enumerating them individually (e.g., sphinx, mdbook, cargo, pip, npm, gem). Output directories can be cached and restored as a whole — see Output directory caching below.

The processor type is displayed in rsconstruct processors list output:

cc_single_file [generator] enabled
ruff [checker] enabled
tera [generator] enabled

For checkers, rsconstruct processors files shows “(checker)” instead of output paths since no files are produced:

[ruff] (3 products)
src/foo.py → (checker)
src/bar.py → (checker)

Configuration

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

[processor.ruff]

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

[processor.cc_single_file]

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

Use rsconstruct processors list to see declared processors and descriptions. Use rsconstruct processors list --all to include hidden processors. Use rsconstruct processors 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
• Spellcheck — checks documentation files for spelling errors
• Rumdl — lints Markdown files with rumdl
• 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
• Json Schema — validates JSON schema propertyOrdering

Output Directory Caching

Mass generators (sphinx, mdbook, cargo, pip, npm, gem) produce output in directories rather than individual files. RSConstruct can cache these entire directories so that after rsconstruct clean && rsconstruct build, the output is restored from cache instead of being regenerated.

After a successful build, RSConstruct walks the output directory, stores every file as a content-addressed blob in .rsconstruct/objects/, and records a manifest (path, checksum, Unix permissions) in the cache entry. On restore, the entire directory is recreated from cached objects with permissions preserved.

This is controlled by the cache_output_dir config option (default true) on each mass generator:

[processor.sphinx]
cache_output_dir = true    # Cache _build/ directory (default)

[processor.cargo]
cache_output_dir = false   # Disable for large target/ directories

Output directories cached per processor:

When cache_output_dir is false, the processor falls back to the previous behavior (stamp-file or empty-output caching, no directory restore).

Custom Processors

You can define custom processors in Lua. See Lua Plugins for details.