Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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, creator, and explicit. 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.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 smart auto to auto-detect and add relevant processors.

Use rsconstruct processors list to see declared processors and descriptions. Use rsconstruct processors list --all to show all built-in processors, not just those enabled in the project. 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
  • Zspell — 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
  • 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)

Output Directory Caching

Creator processors (cargo, sphinx, mdbook, pip, npm, gem, and user-defined creators) produce output in directories rather than individual files. RSConstruct caches 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 directories, stores every file as a content-addressed blob, and records a tree (manifest of paths, checksums, and Unix permissions). On restore, the entire directory tree is recreated from cached blobs with permissions preserved. See Cache System for details.

For user-defined creators, output directories are declared via output_dirs:

[processor.creator.venv]
command = "pip"
args = ["install", "-r", "requirements.txt"]
src_extensions = ["requirements.txt"]
output_dirs = [".venv"]

For built-in creators, this is controlled by the cache_output_dir config option (default true):

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

Custom Processors

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