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 latest --repo veltzer/rsconstruct --pattern 'rsconstruct-x86_64-unknown-linux-gnu' --output rsconstruct --clobber

# aarch64 / arm64
gh release download latest --repo veltzer/rsconstruct --pattern 'rsconstruct-aarch64-unknown-linux-gnu' --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/download/latest/rsconstruct-x86_64-unknown-linux-gnu

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

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.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.ruff]

[processor.pylint]

Pass extra arguments via processor config:

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

Adding zspell for docs

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

[processor.ruff]

[processor.pylint]

[processor.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.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/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.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.cc_single_file]

[processor.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 when a version tag (v*) is pushed.

Supported Platforms

How It Works

The release workflow (.github/workflows/release.yml) has two jobs:

1. build — a matrix job that builds the release binary for each platform and uploads it as a GitHub Actions artifact.
2. release — waits for all builds to finish, downloads the artifacts, and creates a GitHub release with auto-generated release notes and all binaries attached.

Creating a Release

1. Update version in Cargo.toml
2. Commit and push
3. Tag and push: git tag v0.2.2 && git push origin v0.2.2
4. The workflow creates the GitHub release automatically

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

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 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
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 zspell   # Run only zspell and auto-add words
rsconstruct build -p ruff,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.

Incremental recovery and batch behavior

By default (fail-fast mode), rsconstruct executes each product independently, even for batch-capable processors. Successfully completed products are cached immediately, so if a build fails or is interrupted, the next run only rebuilds what wasn’t completed.

With --keep-going, batch-capable processors group all their products into a single tool invocation. 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.

Processor Shortcuts (@ aliases)

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

By type:

• @checkers — all checker processors (ruff, pylint, shellcheck, etc.)
• @generators — all generator processors (tera, cc_single_file, etc.)
• @creators — all creator processors (pip, npm, cargo, etc.)

By tool:

• @python3 — all processors that require python3
• @node — all processors that require node
• Any tool name works (matched against each processor’s required_tools())

By processor name:

• @ruff — equivalent to ruff (strips the @ prefix)

Examples:

rsconstruct build -p @checkers              # Run only checker processors
rsconstruct build -p @generators            # Run only generator processors
rsconstruct build -p @python3               # Run all Python-based processors
rsconstruct build -p @checkers,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. When run without a subcommand, removes build output files (same as rsconstruct clean outputs).

rsconstruct clean                # Remove build output files (preserves cache) [default]
rsconstruct clean outputs        # Remove build output files (preserves cache)
rsconstruct clean all            # Remove out/ and .rsconstruct/ directories
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 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 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 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, --processors, --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 deps

Show or manage source file dependencies from the dependency cache. The cache is populated during builds when dependency analyzers scan source files (e.g., C/C++ headers, Python imports).

rsconstruct deps list                          # List all available dependency analyzers
rsconstruct deps build                         # Run dependency analysis without building
rsconstruct deps show all                    # Show all cached dependencies
rsconstruct deps show files src/main.c       # Show dependencies for a specific file
rsconstruct deps show files src/a.c src/b.c  # Show dependencies for multiple files
rsconstruct deps show analyzers cpp          # Show dependencies from the C/C++ analyzer
rsconstruct deps show analyzers cpp python   # Show dependencies from multiple analyzers
rsconstruct deps stats                       # Show statistics by analyzer
rsconstruct deps clean                       # Clear the entire dependency cache
rsconstruct deps clean --analyzer cpp        # Clear only C/C++ dependencies
rsconstruct deps clean --analyzer python     # Clear only Python dependencies

Example output for rsconstruct deps show all:

src/main.c: [cpp] (no dependencies)
src/test.c: [cpp]
  src/utils.h
  src/config.h
config/settings.py: [python]
  config/base.py

Example output for rsconstruct deps stats:

cpp: 15 files, 42 dependencies
python: 8 files, 12 dependencies

Total: 23 files, 54 dependencies

Note: This command reads directly from the dependency cache (.rsconstruct/deps.redb). If the cache is empty, run a build first to populate it.

This command is 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
• Viewing statistics about cached dependencies by analyzer
• 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.pylint] section
rsconstruct smart disable pylint         # Remove [processor.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

rsconstruct processors

rsconstruct processors list              # List declared processors and descriptions
rsconstruct processors list -a           # Show all built-in processors
rsconstruct processors files             # Show source and target files for each declared processor
rsconstruct processors files ruff        # Show files for a specific processor
rsconstruct processors files              # Show files for enabled processors
rsconstruct processors config ruff       # Show resolved configuration for a processor
rsconstruct processors config --diff     # Show only fields that differ from defaults
rsconstruct processors defconfig ruff    # Show default configuration for a processor
rsconstruct processors add ruff          # Append [processor.ruff] to rsconstruct.toml (fields pre-populated + comments)
rsconstruct processors add ruff --dry-run  # Preview the snippet without writing
rsconstruct processors allowlist         # Show the current processor allowlist
rsconstruct processors graph             # Show inter-processor dependencies
rsconstruct processors graph --format dot    # Graphviz DOT format
rsconstruct processors graph --format mermaid # Mermaid format
rsconstruct processors files --headers   # Show files with processor headers

rsconstruct tools

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 tools list              # List required tools and which processor needs them
rsconstruct tools list -a           # Include tools from disabled processors
rsconstruct tools check             # Verify tool versions against .tools.versions lock file
rsconstruct tools lock              # Lock tool versions to .tools.versions
rsconstruct tools install           # Install all missing external tools
rsconstruct tools install ruff      # Install a specific tool by name
rsconstruct tools install -y        # Skip confirmation prompt
rsconstruct tools install-deps      # Install declared [dependencies] (pip, npm, gem)
rsconstruct tools install-deps -y   # Skip confirmation prompt
rsconstruct tools stats             # Show tool availability and language runtime breakdown
rsconstruct tools stats --json      # Show tool stats in JSON format
rsconstruct tools graph             # Show tool-to-processor dependency graph (DOT format)
rsconstruct tools graph --format mermaid  # Mermaid format
rsconstruct tools graph --view      # Open tool graph in browser

rsconstruct tags

Search and query frontmatter tags from markdown files.

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

Manage term checking and fixing in markdown files.

rsconstruct terms fix

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

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

rsconstruct terms merge

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

rsconstruct terms merge ../other-project/terms

rsconstruct doctor

Requires config. (no subcommands)

Diagnose build environment — checks config, tools, and versions.

rsconstruct doctor

rsconstruct info

Show project information.

rsconstruct info source          # Show source file counts by extension

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 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, processors, analyzers, 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 processors defconfig <TAB>
• rsconstruct build --processors <TAB> / rsconstruct build -p <TAB>
• rsconstruct watch --processors <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 processors config <TAB>
• rsconstruct processors files <TAB>

Instance names are extracted from [processor.NAME] and [processor.NAME.SUBNAME] 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 (cpp, markdown, python, tera):

• rsconstruct analyzers config <TAB>
• rsconstruct analyzers 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__processors__config)
• rsconstruct__processors__defconfig)
• rsconstruct__processors__files)

The function also patches --processors / -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.

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, omit to disable)
output_dir = "out"    # Global output directory prefix for generator processors

# Declare processors by adding [processor.NAME] sections.
# Only declared processors run — no processors are enabled by default.
# Use `rsconstruct smart auto` to auto-detect and add relevant processors.

[processor.ruff]
# args = []

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

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

[analyzer]
auto_detect = true
enabled = ["cpp", "python"]

[graph]
viewer = "google-chrome"  # Command to open graph files (default: platform-specific)

[plugins]
dir = "plugins"  # Directory containing .lua processor plugins

[completions]
shells = ["bash"]

[dependencies]
pip = ["pyyaml", "jinja2"]    # Python packages
npm = ["eslint", "prettier"]  # Node.js packages
gem = ["mdl"]                 # Ruby gems
system = ["pandoc", "graphviz"]  # System packages (checked but not auto-installed)

Per-processor configuration is documented on each processor’s page under Processors. Lua plugin configuration is documented under Lua Plugins.

Processor instances

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

[processor.pylint]

Customize with config fields:

[processor.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.pylint.core]
src_dirs = ["src/core"]
args = ["--disable=C0114"]

[processor.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 type — use either [processor.pylint] or [processor.pylint.NAME], not both.

Instance naming

A single instance declared as [processor.pylint] has the instance name pylint. Named instances declared as [processor.pylint.core] and [processor.pylint.tests] have instance names pylint.core and pylint.tests.

The instance name is used everywhere a processor is identified:

• Build output and progress: [pylint.core] src/core/main.py
• Error messages: Error: [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} (e.g., out/marp.slides and out/marp.docs for two marp instances), ensuring outputs do not collide
• The --processors filter: use the full instance name, e.g., rsconstruct build -p pylint.core

For single instances, the instance name equals the processor type name (e.g., pylint), so there is no visible difference from previous behavior.

Auto-detection

Run rsconstruct smart auto to scan the project and automatically add [processor.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.cppcheck]
src_exclude_dirs = "${kernel_excludes}"

[processor.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). Undefined variable references produce an error.

Section details

[build]

[processor.NAME]

Each [processor.NAME] section declares a processor instance. The section name must match a builtin processor type (e.g., ruff, pylint, cc_single_file) or a Lua plugin name.

Common fields available to all processors:

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

[cache]

[analyzer]

[graph]

[plugins]

[completions]

[dependencies]

Declare project dependencies by package manager. Used by rsconstruct doctor to verify availability and rsconstruct tools install-deps to install missing packages.

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:

1. Index entries at index/{cache_key}

   • JSON mapping input checksums to output checksums
   • One entry per product (source file + processor + config)

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 index entry from remote
   • Fetches required objects from remote
   • Restores outputs locally
4. If rebuild required:
   • Executes the processor
   • Stores outputs in local cache
   • If remote_push = true, pushes to remote

Cache Hit Flow

Local cache hit → Restore from local → Done
       ↓ miss
Remote cache hit → Download index + 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
├── plugins/          # Lua processor plugins (.lua 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/cc_single_file/, preserving the directory structure:

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

Python files

Python files are linted and stub outputs are written to out/ruff/ (ruff processor) or out/pylint/ (pylint processor).

Build artifacts

All build outputs go into out/. The cache lives in .rsconstruct/. Use rsconstruct clean to remove out/ (preserving cache) or rsconstruct clean all to remove both.

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
• 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 a source file hasn’t changed, its cached dependencies are used.
• If a source file has changed, dependencies are re-scanned.
• The cache is shared across all analyzers.

Use the analyzers and deps commands to inspect the cache:

rsconstruct analyzers list            # list available analyzers
rsconstruct analyzers defconfig cpp   # show default config for an analyzer
rsconstruct analyzers add cpp         # append [analyzer.cpp] to rsconstruct.toml with comments
rsconstruct analyzers add cpp --dry-run  # preview without writing
rsconstruct deps all                  # show all cached dependencies
rsconstruct deps for src/main.c       # show dependencies for specific files
rsconstruct deps 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 analyze(
        &self,
        graph: &mut BuildGraph,
        deps_cache: &mut DepsCache,
        file_index: &FileIndex,
        verbose: bool,
    ) -> Result<()>;
}
}

The analyze method should:

1. Find products with relevant source files.
2. Scan each source file for dependencies (using the cache when available).
3. Add discovered dependencies to the product’s inputs.

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.

See also

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

icpp

Native (no-subprocess) C/C++ dependency analyzer. Scans #include directives by parsing source files directly in Rust, without invoking gcc or pkg-config.

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 compiler-discovered system include paths or pkg-config integration.

Configuration

[analyzer.icpp]
include_paths          = ["include", "src"]
src_exclude_dirs       = ["/kernel/", "/vendor/"]
follow_angle_brackets  = false
skip_not_found         = false

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

• Resolves imports to local files (ignores stdlib / external packages)
• Supports both import foo and from foo import bar syntax
• Searches relative to the source file and project root

Configuration

[analyzer.python]
# currently no tunables

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

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

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

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 processors types to list them.

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.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.shellcheck]

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

Validate YAML files:

[processor.yamllint]

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

Validate JSON files with jq:

[processor.jq]

Scans for .json files, validates each with jq.

Spell check Markdown files:

[processor.zspell]

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

Built-in checkers

ruff, pylint, mypy, pyrefly, black, pytest, doctest, shellcheck, luacheck, yamllint, jq, jsonlint, taplo, cppcheck, clang_tidy, cpplint, checkpatch, mdl, markdownlint, rumdl, aspell, zspell, ascii, encoding, duplicate_files, terms, eslint, jshint, standard, htmlhint, htmllint, tidy, stylelint, jslint, svglint, svgo, perlcritic, xmllint, checkstyle, php_lint, yq, hadolint, slidev, json_schema, iyamlschema, ijq, ijsonlint, iyamllint, itaplo, marp_images, license_header

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.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.marp]

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

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

Convert documents with pandoc (multi-format):

[processor.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/pandoc/syllabus.pdf
pandoc/syllabus.md → out/pandoc/syllabus.html
pandoc/syllabus.md → out/pandoc/syllabus.docx

Compile single-file C programs:

[processor.cc_single_file]

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

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

Convert Mermaid diagrams:

[processor.mermaid]

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

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

Compile SCSS to CSS:

[processor.sass]

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

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

Built-in generators

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

Creator

A creator runs a command and caches declared output files and directories. It scans for anchor files — files whose presence means “run this tool here.” One product is created per anchor file found, and the command runs in the anchor file’s directory.

Unlike generators (where outputs are derived from input paths), creator outputs are declared explicitly in the config via output_dirs and output_files.

How it works

1. Scans for anchor files matching src_extensions in src_dirs
2. Creates one product per anchor file
3. Runs the command in the anchor file’s directory
4. Walks all declared output_dirs and collects output_files
5. Stores each file as a content-addressed blob
6. Records a tree in the cache — a manifest listing every output file with its path, blob checksum, and Unix permissions

What gets cached

A tree entry listing all output files. On restore, the directory tree is recreated from cached blobs with permissions preserved. Individual files within the tree that already exist with the correct checksum are skipped.

Examples

Install Python dependencies with pip:

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

Scans for requirements.txt files. For each one, runs pip install and caches the entire .venv/ directory. After rsconstruct clean, the venv is restored from cache instead of reinstalling.

Build a Node.js project:

[processor.creator.npm_build]
command = "npm"
args = ["run", "build"]
src_extensions = ["package.json"]
output_dirs = ["dist"]

Scans for package.json files, runs npm run build, caches the dist/ directory.

Build documentation with Sphinx:

[processor.sphinx]

Scans for conf.py files, runs sphinx-build, caches the output directory.

docs/conf.py → (creator)

Build a Rust project with Cargo:

[processor.cargo]

Scans for Cargo.toml files, runs cargo build, optionally caches the target/ directory.

Cargo.toml → (creator)

Run a custom build script:

[processor.creator.assets]
command = "./build_assets.sh"
src_extensions = [".manifest"]
src_dirs = ["."]
output_dirs = ["assets/compiled", "assets/sprites"]
output_files = ["assets/manifest.json"]

Scans for .manifest files, runs the build script, caches two output directories and one output file.

Built-in creators

cargo, pip, npm, gem, sphinx, mdbook, jekyll, cc (full C/C++ projects)

User-defined creators use the creator processor type directly via [processor.creator.NAME].

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.site]
command = "python3"
args = ["build_site.py"]
input_globs = ["out/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/pandoc/page1.html, out/pandoc/page2.html, templates/base.html, site.yaml → out/site/index.html, out/site/style.css

Merge PDFs into a course bundle:

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

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

Built-in explicit processors

explicit, pdfunite, ipdfunite

Comparison

A2x Processor

Purpose

Converts AsciiDoc files to PDF (or other formats) using a2x.

How It Works

Discovers .txt (AsciiDoc) files in the project and runs a2x on each file, producing output in the configured format.

Source Files

• Input: **/*.txt
• Output: out/a2x/{relative_path}.pdf

Configuration

[processor.a2x]
a2x = "a2x"                           # The a2x command to run
format = "pdf"                         # Output format (pdf, xhtml, dvi, ps, epub, mobi)
args = []                              # Additional arguments to pass to a2x
output_dir = "out/a2x"                # Output directory
dep_inputs = []                      # Additional files that trigger rebuilds when changed

Batch support

Each input file is processed individually, producing its own output file.

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

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

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

Cargo Processor

Purpose

Builds Rust projects using Cargo. Each Cargo.toml produces a cached success marker, allowing RSConstruct to skip rebuilds 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 build (or a configured command) in that directory.

Input Tracking

The cargo processor tracks all .rs and .toml files 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 cargo.

Workspaces

For Cargo workspaces, each Cargo.toml (root and members) is discovered as a separate product. To build only the workspace root, use src_exclude_paths to skip member directories, or configure src_dirs to limit discovery.

Source Files

• Input: Cargo.toml plus all .rs and .toml files in the project tree
• Output: None (creator — produces output in target directory)

Configuration

[processor.cargo]
cargo = "cargo"          # Cargo binary to use
command = "build"        # Cargo command (build, check, test, clippy, etc.)
args = []                # Extra arguments passed to cargo
profiles = ["dev", "release"]  # Cargo profiles to build
src_dirs = [""]            # Directory to scan ("" = project root)
src_extensions = ["Cargo.toml"]
dep_inputs = []        # Additional files that trigger rebuilds
cache_output_dir = true  # Cache the target/ directory for fast restore after clean

Batch support

Runs as a single whole-project operation (e.g., cargo build, npm install).

Examples

Basic Usage

[processor.cargo]

Release Only

[processor.cargo]
profiles = ["release"]

Dev Only

[processor.cargo]
profiles = ["dev"]

Use cargo check Instead of build

[processor.cargo]
command = "check"

Run clippy

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

Workspace Root Only

[processor.cargo]
src_exclude_paths = ["crates/"]

Notes

• Cargo has its own incremental compilation, so rsconstruct’s caching mainly avoids invoking cargo at all when nothing changed
• The target/ directory is automatically excluded from input scanning
• For monorepos with multiple Rust projects, each Cargo.toml is built separately

CC Project Processor

Purpose

Builds full C/C++ projects with multiple targets (libraries and executables) defined in a cc.yaml manifest file. Unlike the CC Single File processor which compiles each source file into a standalone executable, this processor supports multi-file targets with dependency linking.

How It Works

The processor scans for cc.yaml files. Each manifest defines libraries and programs to build. All paths in the manifest (sources, include directories) are relative to the cc.yaml file’s location and are automatically resolved to project-root-relative paths before compilation. All commands run from the project root.

Output goes under out/cc/<path-to-cc.yaml-dir>/, so a manifest at src/exercises/foo/cc.yaml produces output in out/cc/src/exercises/foo/. A manifest at the project root produces output in out/cc/.

Source files are compiled to object files, then linked into the final targets:

src/exercises/foo/cc.yaml defines:
  library "mymath" (static) from math.c, utils.c
  program "main" from main.c, links mymath

Build produces:
  out/cc/src/exercises/foo/obj/mymath/math.o
  out/cc/src/exercises/foo/obj/mymath/utils.o
  out/cc/src/exercises/foo/lib/libmymath.a
  out/cc/src/exercises/foo/obj/main/main.o
  out/cc/src/exercises/foo/bin/main

cc.yaml Format

All paths in the manifest are relative to the cc.yaml file’s location.

# Global settings (all optional)
cc: gcc               # C compiler (default: gcc)
cxx: g++              # C++ compiler (default: g++)
cflags: [-Wall]       # Global C flags
cxxflags: [-Wall]     # Global C++ flags
ldflags: []           # Global linker flags
include_dirs: [include]  # Global -I paths (relative to cc.yaml location)

# Library definitions
libraries:
  - name: mymath
    lib_type: shared   # shared (.so) | static (.a) | both
    sources: [src/math.c, src/utils.c]
    include_dirs: [include]  # Additional -I for this library
    cflags: []               # Additional C flags
    cxxflags: []             # Additional C++ flags
    ldflags: [-lm]           # Linker flags for shared lib

  - name: myhelper
    lib_type: static
    sources: [src/helper.c]

# Program definitions
programs:
  - name: main
    sources: [src/main.c]
    link: [mymath, myhelper]  # Libraries defined above to link against
    ldflags: [-lpthread]      # Additional linker flags

  - name: tool
    sources: [src/tool.cc]    # .cc -> uses C++ compiler
    link: [mymath]

Library Types

Language Detection

The compiler is chosen per source file based on extension:

Global cflags are used for C files and cxxflags for C++ files.

Output Layout

Output is placed under out/cc/<cc.yaml-relative-dir>/:

out/cc/<cc.yaml-dir>/
  obj/<target_name>/    # Object files per target
    file.o
  lib/                  # Libraries
    lib<name>.a
    lib<name>.so
  bin/                  # Executables
    <program_name>

Build Modes

Compile + Link (default)

Each source is compiled to a .o file, then targets are linked from objects. This provides incremental rebuilds — only changed sources are recompiled.

Single Invocation

When single_invocation = true in rsconstruct.toml, programs are built by passing all sources directly to the compiler in one command. Libraries still use compile+link since ar requires object files.

Configuration

[processor.cc]
enabled = true            # Enable/disable (default: true)
cc = "gcc"                # Default C compiler (default: "gcc")
cxx = "g++"               # Default C++ compiler (default: "g++")
cflags = []               # Additional global C flags
cxxflags = []             # Additional global C++ flags
ldflags = []              # Additional global linker flags
include_dirs = []         # Additional global -I paths
single_invocation = false # Use single-invocation mode (default: false)
dep_inputs = []         # Extra files that trigger rebuilds
cache_output_dir = true   # Cache entire output directory (default: true)

Note: The cc.yaml manifest settings override the rsconstruct.toml defaults for compiler and flags.

Configuration Reference

Batch support

Runs as a single whole-project operation (e.g., cargo build, npm install).

Example

Given this project layout:

myproject/
  rsconstruct.toml
  exercises/
    math/
      cc.yaml
      include/
        math.h
      math.c
      main.c

With exercises/math/cc.yaml:

include_dirs: [include]

libraries:
  - name: math
    lib_type: static
    sources: [math.c]

programs:
  - name: main
    sources: [main.c]
    link: [math]

Running rsconstruct build produces:

out/cc/exercises/math/obj/math/math.o
out/cc/exercises/math/lib/libmath.a
out/cc/exercises/math/obj/main/main.o
out/cc/exercises/math/bin/main

CC Single File Processor

Purpose

Compiles C (.c) and C++ (.cc) source files into executables, one source file per executable.

How It Works

Source files under the configured source directory are compiled into executables under out/cc_single_file/, mirroring the directory structure:

src/main.c       →  out/cc_single_file/main.elf
src/a/b.c        →  out/cc_single_file/a/b.elf
src/app.cc       →  out/cc_single_file/app.elf

Header dependencies are automatically tracked via compiler-generated .d files (-MMD -MF). When a header changes, all source files that include it are rebuilt.

Source Files

• Input: {source_dir}/**/*.c, {source_dir}/**/*.cc
• Output: out/cc_single_file/{relative_path}{output_suffix}

Per-File Flags

Per-file compile and link flags can be set via special comments in source files. This allows individual files to require specific libraries or compiler options without affecting the entire project.

Flag directives

// EXTRA_COMPILE_FLAGS_BEFORE=-pthread
// EXTRA_COMPILE_FLAGS_AFTER=-O2 -DNDEBUG
// EXTRA_LINK_FLAGS_BEFORE=-L/usr/local/lib
// EXTRA_LINK_FLAGS_AFTER=-lX11

Command directives

Execute a command and use its stdout as flags (no shell):

// EXTRA_COMPILE_CMD=pkg-config --cflags gtk+-3.0
// EXTRA_LINK_CMD=pkg-config --libs gtk+-3.0

Shell directives

Execute via sh -c (full shell syntax):

// EXTRA_COMPILE_SHELL=echo -DLEVEL2_CACHE_LINESIZE=$(getconf LEVEL2_CACHE_LINESIZE)
// EXTRA_LINK_SHELL=echo -L$(brew --prefix openssl)/lib

Backtick substitution

Flag directives also support backtick substitution for inline command execution:

// EXTRA_COMPILE_FLAGS_AFTER=`pkg-config --cflags gtk+-3.0`
// EXTRA_LINK_FLAGS_AFTER=`pkg-config --libs gtk+-3.0`

Command caching

All command and shell directives (EXTRA_*_CMD, EXTRA_*_SHELL, and backtick substitutions) are cached in memory during a build. If multiple source files use the same command (e.g., pkg-config --cflags gtk+-3.0), it is executed only once. This improves build performance when many files share common dependencies.

Compiler profile-specific flags

When using multiple compiler profiles, you can specify flags that only apply to a specific compiler by adding [profile_name] after the directive name:

// EXTRA_COMPILE_FLAGS_BEFORE=-g
// EXTRA_COMPILE_FLAGS_BEFORE[gcc]=-femit-struct-debug-baseonly
// EXTRA_COMPILE_FLAGS_BEFORE[clang]=-gline-tables-only

In this example:

• -g is applied to all compilers
• -femit-struct-debug-baseonly is only applied when compiling with the “gcc” profile
• -gline-tables-only is only applied when compiling with the “clang” profile

The profile name matches the name field in your [[processor.cc_single_file.compilers]] configuration:

[[processor.cc_single_file.compilers]]
name = "gcc"      # Matches [gcc] suffix
cc = "gcc"

[[processor.cc_single_file.compilers]]
name = "clang"    # Matches [clang] suffix
cc = "clang"

This works with all directive types:

• EXTRA_COMPILE_FLAGS_BEFORE[profile]
• EXTRA_COMPILE_FLAGS_AFTER[profile]
• EXTRA_LINK_FLAGS_BEFORE[profile]
• EXTRA_LINK_FLAGS_AFTER[profile]
• EXTRA_COMPILE_CMD[profile]
• EXTRA_LINK_CMD[profile]
• EXTRA_COMPILE_SHELL[profile]
• EXTRA_LINK_SHELL[profile]

Excluding files from specific profiles

To exclude a source file from being compiled with specific compiler profiles, use EXCLUDE_PROFILE:

// EXCLUDE_PROFILE=clang

This is useful when a file uses compiler-specific features that aren’t available in other compilers. For example, a file using GCC-only builtins like __builtin_va_arg_pack_len():

// EXCLUDE_PROFILE=clang
// This file uses GCC-specific builtins
#include <stdarg.h>

void example(int first, ...) {
    int count = __builtin_va_arg_pack_len();  // GCC-only
    // ...
}

You can exclude multiple profiles by listing them space-separated:

// EXCLUDE_PROFILE=clang icc

Directive summary

Supported comment styles

Directives can appear in any of these comment styles:

C++ style:

// EXTRA_LINK_FLAGS_AFTER=-lX11

C block comment (single line):

/* EXTRA_LINK_FLAGS_AFTER=-lX11 */

C block comment (multi-line, star-prefixed):

/*
 * EXTRA_LINK_FLAGS_AFTER=-lX11
 */

Command Line Ordering

The compiler command is constructed in this order:

compiler -MMD -MF deps -I... [compile_before] [cflags/cxxflags] [compile_after] -o output source [link_before] [ldflags] [link_after]

Link flags come after the source file so the linker can resolve symbols correctly.

Verbosity Levels (--processor-verbose N)

Configuration

Single Compiler (Legacy)

[processor.cc_single_file]
cc = "gcc"                # C compiler (default: "gcc")
cxx = "g++"               # C++ compiler (default: "g++")
cflags = []               # C compiler flags
cxxflags = []             # C++ compiler flags
ldflags = []              # Linker flags
include_paths = []        # Additional -I paths (relative to project root)
src_dirs = ["src"]          # Source directory (default: "src")
output_suffix = ".elf"    # Suffix for output executables (default: ".elf")
dep_inputs = []         # Additional files that trigger rebuilds when changed
include_scanner = "native" # Method for scanning header dependencies (default: "native")

Multiple Compilers

To compile with multiple compilers (e.g., both GCC and Clang), use the compilers array:

[processor.cc_single_file]
src_dirs = ["src"]
include_paths = ["include"]  # Shared across all compilers

[[processor.cc_single_file.compilers]]
name = "gcc"
cc = "gcc"
cxx = "g++"
cflags = ["-Wall", "-Wextra"]
cxxflags = ["-Wall", "-Wextra"]
ldflags = []
output_suffix = ".elf"

[[processor.cc_single_file.compilers]]
name = "clang"
cc = "clang"
cxx = "clang++"
cflags = ["-Wall", "-Wextra", "-Weverything"]
cxxflags = ["-Wall", "-Wextra"]
ldflags = []
output_suffix = ".elf"

When using multiple compilers, outputs are organized by compiler name:

src/main.c  →  out/cc_single_file/gcc/main.elf
            →  out/cc_single_file/clang/main.elf

Each source file is compiled once per compiler profile, allowing you to:

• Test code with multiple compilers to catch different warnings
• Compare output between compilers
• Build for different targets (cross-compilation)

Configuration Reference

Compiler Profile Fields

Each entry in the compilers array can have:

Batch support

Each input file is processed individually, producing its own output file.

Include Scanner

The include_scanner option controls how header dependencies are discovered:

Native scanner behavior

The native scanner:

• Recursively follows #include directives
• Searches include paths in order: source file directory, configured include_paths, project root
• Skips system headers (/usr/..., /lib/...)
• Only tracks project-local headers (relative paths)

When to use compiler scanner

Use include_scanner = "compiler" if you have:

• Computed includes: #include MACRO_THAT_EXPANDS_TO_FILENAME
• Complex conditional compilation affecting which headers are included
• Headers outside the standard search paths that the native scanner misses

The native scanner may occasionally report extra dependencies (false positives), which is safe—it just means some files might rebuild unnecessarily. It will not miss dependencies (false negatives) for standard #include patterns.

Checkpatch Processor

Purpose

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

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.checkpatch]
args = []
dep_inputs = []

Batch support

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

Checkstyle Processor

Purpose

Checks Java code style using Checkstyle.

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

Chromium Processor

Purpose

Converts HTML files to PDF using headless Chromium (Google Chrome).

How It Works

Discovers .html files in the configured scan directory (default: out/marp) and runs headless Chromium with --print-to-pdf on each file, producing a PDF output.

This is typically used as a post-processing step after another processor (e.g., Marp) generates HTML files.

Source Files

• Input: out/marp/**/*.html (default scan directory)
• Output: out/chromium/{relative_path}.pdf

Configuration

[processor.chromium]
chromium_bin = "google-chrome"            # The Chromium/Chrome executable to run
args = []                                 # Additional arguments to pass to Chromium
output_dir = "out/chromium"               # Output directory for PDFs
dep_inputs = []                         # Additional files that trigger rebuilds when changed

Batch support

Each input file is processed individually, producing its own output file.

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: out/clang_tidy/{flat_name}.clang_tidy

Configuration

[processor.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.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.clang_tidy]
dep_inputs = [".clang-tidy"]

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 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 in the project tree
• Output: None (checker-style caching)

Configuration

[processor.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.clippy]

Deny All Warnings

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

Use Both Cargo Build and Clippy

[processor.cargo]

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

CMake Processor

Purpose

Lints CMake files using cmake --lint.

How It Works

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

This processor supports batch mode.

Source Files

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

Configuration

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

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: out/cppcheck/{flat_name}.cppcheck

Configuration

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

Cpplint Processor

Purpose

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

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.cpplint]
args = []
dep_inputs = []

Batch support

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

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

Drawio Processor

Purpose

Converts Draw.io diagram files to PNG, SVG, or PDF.

How It Works

Discovers .drawio files in the project and runs drawio in export mode on each file, generating output in the configured formats.

Source Files

• Input: **/*.drawio
• Output: out/drawio/{format}/{relative_path}.{format}

Configuration

[processor.drawio]
drawio_bin = "drawio"                  # The drawio command to run
formats = ["png"]                      # Output formats (png, svg, pdf)
args = []                              # Additional arguments to pass to drawio
output_dir = "out/drawio"              # Output directory
dep_inputs = []                      # Additional files that trigger rebuilds when changed

Batch support

Each input file is processed individually, producing its own output file.

ESLint Processor

Purpose

Lints JavaScript and TypeScript files using ESLint.

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

Explicit Processor

Why “explicit”?

Other processor types discover their inputs by scanning directories for files matching certain extensions. The explicit processor is different: the user declares exactly which files are inputs and which are outputs. Nothing is discovered or inferred.

Names considered:

• explicit — chosen. Directly communicates the key difference: everything is declared rather than discovered.
• custom — too generic. Doesn’t say what makes it different from the existing generator processor (which is also “custom”).
• rule — precise (Bazel/Make terminology for a build rule with explicit inputs/outputs), but carries baggage from other build systems and doesn’t fit the rsconstruct naming convention (processors, not rules).
• aggregate — describes the many-inputs-to-few-outputs pattern, but not all uses are aggregations.
• task — too generic. Could mean anything.

Purpose

Runs a user-configured script or command with explicitly declared inputs and outputs. Unlike scan-based processors (which discover one product per source file), the explicit processor creates a single product with all declared inputs feeding into all declared outputs.

This is ideal for build steps that aggregate many files into one or a few outputs, such as:

• Generating an index page from all HTML files in a directory
• Building a bundle from multiple source files
• Creating a report from multiple data files

How It Works

The processor resolves all inputs (literal paths) and input_globs (glob patterns) into a flat file list. It creates a single product with these files as inputs and the outputs list as outputs.

Rsconstruct uses this information for:

• Rebuild detection: if any input changes, the product is rebuilt
• Dependency ordering: if an input is an output of another processor, that processor runs first (automatic via resolve_dependencies())
• Caching: outputs are cached and restored on cache hit

Invocation

The command is invoked as:

command [args...] --inputs <input1> <input2> ... --outputs <output1> <output2> ...

Input ordering

Inputs are passed in a deterministic order:

1. inputs entries first, in config file order
2. input_globs results second, one glob at a time in config file order, files within each glob sorted alphabetically

This ordering is stable across builds (assuming the same set of files exists).

Configuration

[processor.explicit.site]
command = "scripts/build_site.py"
args = ["--verbose"]
inputs = [
    "resources/index.html",
    "resources/index.css",
    "resources/index.js",
    "tags/level.txt",
    "tags/category.txt",
    "tags/audiences.txt",
]
input_globs = [
    "docs/courses/**/*.html",
    "docs/tracks/*.html",
]
outputs = [
    "docs/index.html",
]

Fields

At least one of inputs or input_globs must be specified.

Glob patterns

input_globs supports standard glob syntax:

• * matches any sequence of characters within a path component
• ** matches any number of path components (recursive)
• ? matches a single character
• [abc] matches one of the listed characters

Glob results that match no files are silently ignored (the set of matching files may grow as upstream generators produce outputs via the fixed-point discovery loop).

Cross-Processor Dependencies

The explicit processor works naturally with the fixed-point discovery loop. If input_globs matches files that are outputs of other processors (e.g., pandoc-generated HTML files), rsconstruct automatically:

1. Injects those declared outputs as virtual files during discovery
2. Resolves dependency edges so upstream processors run first
3. Rebuilds the explicit processor when upstream outputs change

This means you do not need to manually order processors or wait for a second build — everything is handled in a single build invocation.

Comparison with Other Processor Types

Gem Processor

Purpose

Installs Ruby dependencies from Gemfile files using Bundler.

How It Works

Discovers Gemfile files in the project, runs bundle install in each directory, and creates a stamp file on success. Sibling .rb and .gemspec files are tracked as inputs.

Source Files

• Input: **/Gemfile (plus sibling .rb, .gemspec files)
• Output: out/gem/{flat_name}.stamp

Configuration

[processor.gem]
command = "bundle"                     # The bundler command to run
args = []                              # Additional arguments to pass to bundler install
dep_inputs = []                      # Additional files that trigger rebuilds when changed
cache_output_dir = true                # Cache the vendor/bundle directory for fast restore after clean

Batch support

Runs as a single whole-project operation (e.g., cargo build, npm install).

Generator Processor

Purpose

Runs a user-configured script or command as a generator, producing output files from input files. The script receives input/output path pairs on the command line.

How It Works

Discovers files matching the configured extensions, computes output paths under output_dir with the configured output_extension, and invokes the command with path pairs.

In single mode: command [args...] <input> <output>

In batch mode: command [args...] <input1> <output1> <input2> <output2> ...

Auto-detected when the configured scan directories contain matching files.

Source Files

• Input: files matching src_extensions in src_dirs
• Output: {output_dir}/{relative_path}.{output_extension}

Configuration

[processor.generator]
command = "scripts/convert.py"
output_dir = "out/converted"
output_extension = "html"
src_dirs = ["syllabi"]
src_extensions = [".md"]
batch = true
args = []
dep_inputs = []

Batch support

Configurable via batch = true (default). In batch mode, the script receives all input/output pairs in a single invocation. Set batch = false to invoke the script once per file.

Hadolint Processor

Purpose

Lints Dockerfiles using Hadolint.

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

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

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

Imarkdown2html Processor

Purpose

Converts Markdown files to HTML using the pulldown-cmark Rust crate. Native (in-process, no external tools required).

This is the native equivalent of markdown2html, which uses the external markdown Perl script.

Source Files

• Input: **/*.md
• Output: out/imarkdown2html/{relative_path}.html

Configuration

[processor.imarkdown2html]
src_dirs = ["docs"]
output_dir = "out/imarkdown2html"    # Output directory (default)

Batch Support

Each input file is processed individually, producing its own output file.

Iyamlschema Processor

Purpose

Validates YAML files against JSON schemas referenced by a $schema URL field in each file. Checks both schema conformance and property ordering. Native (in-process, no external tools required).

How It Works

For each YAML file:

1. Parses the YAML content
2. Reads the $schema field to get the schema URL
3. Fetches the schema (cached in .rsconstruct/webcache.redb)
4. Validates the data against the schema (including resolving remote $ref references)
5. Checks that object keys appear in the order specified by propertyOrdering fields in the schema

Fails if any file is missing $schema, fails schema validation, or has keys in the wrong order.

Configuration

[processor.iyamlschema]
src_dirs = ["yaml"]
check_ordering = true    # Check propertyOrdering (default: true)

Schema Requirements

Each YAML file must contain a $schema field with a URL pointing to a JSON schema:

$schema: "https://example.com/schemas/mydata.json"
name: Alice
age: 30

The schema is fetched via HTTP and cached locally. Subsequent builds use the cached version. Use rsconstruct webcache clear to force re-fetching.

Property Ordering

If the schema contains propertyOrdering arrays, the processor checks that data keys appear in the specified order:

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer" }
  },
  "propertyOrdering": ["name", "age"]
}

Set check_ordering = false to disable this check.

Batch Support

Files are validated individually within a batch. Partial failure is handled correctly.

Jekyll Processor

Purpose

Builds Jekyll static sites by running jekyll build in directories containing a _config.yml file.

How It Works

Discovers _config.yml files in the project (excluding common build tool directories). For each one, runs jekyll build in that directory.

Source Files

• Input: **/_config.yml
• Output: none (creator)

Configuration

[processor.jekyll]
args = []
dep_inputs = []

Batch support

Runs as a single whole-project operation (e.g., cargo build, npm install).

Jinja2 Processor

Purpose

Renders Jinja2 template files into output files using the Python Jinja2 template library.

How It Works

Files matching configured extensions in templates.jinja2/ are rendered via python3 using the jinja2 Python library. Output is written with the extension stripped and the templates.jinja2/ prefix removed:

templates.jinja2/app.config.j2  →  app.config
templates.jinja2/sub/readme.txt.j2  →  sub/readme.txt

Templates use the Jinja2 templating engine. A FileSystemLoader is configured with the project root as the search directory, so templates can include or extend other templates using relative paths. Environment variables are passed to the template context.

Source Files

• Input: templates.jinja2/**/*{src_extensions}
• Output: project root, mirroring the template path (minus templates.jinja2/ prefix) with the extension removed

Configuration

[processor.jinja2]
src_extensions = [".j2"]                      # File extensions to process (default: [".j2"])
dep_inputs = ["config/settings.py"]     # Additional files that trigger rebuilds when changed

Batch support

Each input file is processed individually, producing its own output file.

Jq Processor

Purpose

Validates JSON files using jq.

How It Works

Discovers .json files in the project (excluding common build tool directories), runs jq empty on each file, and records success in the cache. The empty filter validates JSON syntax without producing output — a non-zero exit code from jq fails the product.

This processor supports batch mode — multiple files are checked in a single jq invocation.

Source Files

• Input: **/*.json
• Output: none (linter)

Configuration

[processor.jq]
command = "jq"                               # The jq command to run
args = []                                    # Additional arguments to pass to jq (after "empty")
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.

JSHint Processor

Purpose

Lints JavaScript files using JSHint.

How It Works

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

This processor supports batch mode.

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

Source Files

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

Configuration

[processor.jshint]
command = "jshint"
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.

JSLint Processor

Purpose

Lints JavaScript files using JSLint.

How It Works

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

This processor supports batch mode.

Source Files

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

Configuration

[processor.jslint]
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.

Json Schema Processor

Purpose

Validates JSON schema files by checking that every object’s propertyOrdering array exactly matches its properties keys.

How It Works

Discovers .json files in the project (excluding common build tool directories), parses each as JSON, and recursively walks the structure. At every object node with "type": "object", if both properties and propertyOrdering exist, it verifies that the two key sets match exactly.

Mismatches (keys missing from propertyOrdering or extra keys in propertyOrdering) are reported with their JSON path. Files that contain no propertyOrdering at all pass silently.

This is a pure-Rust checker — no external tool is required.

Source Files

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

Configuration

[processor.json_schema]
args = []                                    # Reserved for future use
dep_inputs = []                            # 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.

Jsonlint Processor

Purpose

Lints JSON files using jsonlint.

How It Works

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

This processor does not support batch mode — each file is checked individually.

Source Files

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

Configuration

[processor.jsonlint]
command = "jsonlint"                          # The jsonlint command to run
args = []                                    # Additional arguments to pass to jsonlint
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.

Libreoffice Processor

Purpose

Converts LibreOffice documents (e.g., .odp presentations) to PDF or other formats.

How It Works

Discovers .odp files in the project and runs libreoffice in headless mode to convert each file to the configured output formats. Uses flock to serialize invocations since LibreOffice only supports a single running instance.

Source Files

• Input: **/*.odp
• Output: out/libreoffice/{format}/{relative_path}.{format}

Configuration

[processor.libreoffice]
libreoffice_bin = "libreoffice"        # The libreoffice command to run
formats = ["pdf"]                      # Output formats (pdf, pptx)
args = []                              # Additional arguments to pass to libreoffice
output_dir = "out/libreoffice"         # Output directory
dep_inputs = []                      # Additional files that trigger rebuilds when changed

Batch support

Each input file is processed individually, producing its own output file.

Linux Module Processor

Purpose

Builds Linux kernel modules (.ko files) from source, driven by a linux-module.yaml manifest. The processor generates a temporary Kbuild file, invokes the kernel build system (make -C <kdir> M=<src> modules), copies the resulting .ko to the output directory, and cleans up build artifacts from the source tree.

How It Works

The processor scans for linux-module.yaml files. Each manifest lists one or more kernel modules to build. For each module the processor:

1. Generates a Kbuild file in the source directory (next to the yaml).
2. Runs make -C <kdir> M=<absolute-source-dir> modules to compile.
3. Copies the .ko file to out/linux-module/<yaml-relative-dir>/.
4. Runs make ... clean and removes the generated Kbuild so the source directory stays clean.

Because the kernel build system requires M= to point at an absolute path containing the sources and Kbuild, the make command runs in the yaml file’s directory — not the project root.

The processor is a generator: it knows exactly which .ko files it produces. Outputs are tracked in the build graph, cached in the object store, and can be restored from cache after rsconstruct clean without recompiling.

linux-module.yaml Format

All source paths are relative to the yaml file’s directory.

# Global settings (all optional)
make: make                    # Make binary (default: "make")
kdir: /lib/modules/6.8.0-generic/build  # Kernel build dir (default: running kernel)
arch: x86_64                  # ARCH= value (optional, omitted if unset)
cross_compile: x86_64-linux-gnu-  # CROSS_COMPILE= value (optional)
v: 0                          # Verbosity V= (default: 0)
w: 1                          # Warning level W= (default: 1)

# Module definitions
modules:
  - name: hello               # Module name -> produces hello.ko
    sources: [main.c]         # Source files (relative to yaml dir)
    extra_cflags: [-DDEBUG]   # Extra CFLAGS (optional, becomes ccflags-y)

  - name: mydriver
    sources: [mydriver.c, utils.c]

Minimal Example

A single module with one source file:

modules:
  - name: hello
    sources: [main.c]

Output Layout

Output is placed under out/linux-module/<yaml-relative-dir>/:

out/linux-module/<yaml-dir>/
  <module_name>.ko

For example, a manifest at src/kernel/hello/linux-module.yaml defining module hello produces:

out/linux-module/src/kernel/hello/hello.ko

KDIR Detection

If kdir is not set in the manifest, the processor runs uname -r to detect the running kernel and uses /lib/modules/<release>/build. This requires the linux-headers-* package to be installed (e.g., linux-headers-generic on Ubuntu).

Generated Kbuild

The processor writes a Kbuild file with the standard kernel module variables:

obj-m := hello.o
hello-objs := main.o
ccflags-y := -DDEBUG       # only if extra_cflags is non-empty

This file is removed after building (whether the build succeeds or fails).

Configuration

[processor.linux_module]
enabled = true           # Enable/disable (default: true)
dep_inputs = []        # Extra files that trigger rebuilds

Configuration Reference

Batch support

Each input file is processed individually, producing its own output file.

Caching

The .ko outputs are cached in the rsconstruct object store. After rsconstruct clean, a subsequent rsconstruct build restores .ko files from cache (via hardlink or copy) without invoking the kernel build system. A rebuild is triggered when any source file or the yaml manifest changes.

Prerequisites

• make must be installed
• Kernel headers must be installed for the target kernel version (apt install linux-headers-generic on Ubuntu)
• For cross-compilation, the appropriate cross-compiler toolchain must be available and specified via cross_compile and arch in the manifest

Example

Given this project layout:

myproject/
  rsconstruct.toml
  drivers/
    hello/
      linux-module.yaml
      main.c

With drivers/hello/linux-module.yaml:

modules:
  - name: hello
    sources: [main.c]

And drivers/hello/main.c:

#include <linux/module.h>
#include <linux/init.h>

MODULE_LICENSE("GPL");

static int __init hello_init(void) {
    pr_info("hello: loaded\n");
    return 0;
}

static void __exit hello_exit(void) {
    pr_info("hello: unloaded\n");
}

module_init(hello_init);
module_exit(hello_exit);

Running rsconstruct build produces:

out/linux-module/drivers/hello/hello.ko

The module can then be loaded with sudo insmod out/linux-module/drivers/hello/hello.ko.

Luacheck Processor

Purpose

Lints Lua scripts using luacheck.

How It Works

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

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

Source Files

• Input: **/*.lua
• Output: none (linter)

Configuration

[processor.luacheck]
command = "luacheck"                         # The luacheck command to run
args = []                                    # Additional arguments to pass to luacheck
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.

Make Processor

Purpose

Runs make in directories containing Makefiles. Each Makefile produces a stub file on success, allowing RSConstruct to track incremental rebuilds.

How It Works

Discovers files named Makefile in the project. For each Makefile found, the processor runs make (or a configured alternative) in the Makefile’s directory. A stub file is created on success.

Directory-Level Inputs

The make processor treats all files in the Makefile’s directory (and subdirectories) as inputs. This means that if any file alongside the Makefile changes — source files, headers, scripts, included makefiles — rsconstruct will re-run make.

This is slightly conservative: a change to a file that the Makefile does not actually depend on will trigger a rebuild. In practice this is the right trade-off because Makefiles can depend on arbitrary files and there is no reliable way to know which ones without running make itself.

Source Files

• Input: **/Makefile plus all files in the Makefile’s directory tree
• Output: out/make/{relative_path}.done

Dependency Tracking Approaches

RSConstruct uses the directory-scan approach described above. Here is why, and what the alternatives are.

1. Directory scan (current)

Track every file under the Makefile’s directory as an input. Any change triggers a rebuild.

Pros: simple, correct, zero configuration. Cons: over-conservative — a change to an unrelated file in the same directory triggers a needless rebuild.

2. User-declared extra inputs

The user lists specific files or globs in dep_inputs. Only those files (plus the Makefile itself) are tracked.

Pros: precise, no unnecessary rebuilds. Cons: requires the user to manually maintain the list. Easy to forget a file and get stale builds.

This is available today via the dep_inputs config key, but on its own it would miss source files that the Makefile compiles.

3. Parse make --dry-run --print-data-base

Ask make to dump its dependency database and extract the real inputs.

Pros: exact dependency information, no over-building. Cons: fragile — output format varies across make implementations (GNU Make, BSD Make, nmake). Some Makefiles behave differently in dry-run mode. Complex to implement and maintain.

4. Hash the directory tree

Instead of listing individual files, compute a single hash over every file in the directory. Functionally equivalent to option 1 but with a different internal representation.

Pros: compact cache key. Cons: same over-conservatism as option 1, and no ability to report which file changed.

Configuration

[processor.make]
command = "make"     # Make binary to use
args = []            # Extra arguments passed to make
target = ""          # Make target (empty = default target)
src_dirs = [""]        # Directory to scan ("" = project root)
src_extensions = ["Makefile"]
dep_inputs = []    # 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.

Mako Processor

Purpose

Renders Mako template files into output files using the Python Mako template library.

How It Works

Files matching configured extensions in templates.mako/ are rendered via python3 using the mako Python library. Output is written with the extension stripped and the templates.mako/ prefix removed:

templates.mako/app.config.mako  →  app.config
templates.mako/sub/readme.txt.mako  →  sub/readme.txt

Templates use the Mako templating engine. A TemplateLookup is configured with the project root as the lookup directory, so templates can include or inherit from other templates using relative paths.

Source Files

• Input: templates.mako/**/*{src_extensions}
• Output: project root, mirroring the template path (minus templates.mako/ prefix) with the extension removed

Configuration

[processor.mako]
src_extensions = [".mako"]                    # File extensions to process (default: [".mako"])
dep_inputs = ["config/settings.py"]     # Additional files that trigger rebuilds when changed

Batch support

Each input file is processed individually, producing its own output file.

Markdown2html Processor

Purpose

Converts Markdown files to HTML using the markdown Perl script.

How It Works

Discovers .md files in the project and runs markdown on each file, producing an HTML output file.

Source Files

• Input: **/*.md
• Output: out/markdown2html/{relative_path}.html

Configuration

[processor.markdown2html]
markdown_bin = "markdown"              # The markdown command to run
args = []                              # Additional arguments to pass to markdown
output_dir = "out/markdown2html"       # Output directory
dep_inputs = []                      # Additional files that trigger rebuilds when changed

Batch support

Each input file is processed individually, producing its own output file.

MassGenerator Processor

Status

Designed, not yet implemented. This document describes the intended user-facing contract for the MassGenerator processor type. The full design rationale is in Output Prediction.

Why “mass generator”?

Existing processor types cover a matrix of “how many outputs” and “are they known in advance”:

MassGenerator is the “transparent Creator”: it produces many output files (like a Creator), but the tool itself answers the question “what will you produce?” before running. Each predicted file becomes a declared product with its own inputs, cache entry, and dependency edges.

Names considered:

• mass_generator — chosen. Says what it does: “generator” (per-file outputs like the Generator type), “mass” (many products from one tool invocation).
• transparent_creator — accurate but awkward.
• predicting_creator — describes the mechanism, not the result.
• site_generator — too narrow; the type is useful beyond static sites.

Purpose

Wraps a tool that:

1. Produces many output files from a set of source files (e.g., a static site generator).
2. Can enumerate its outputs in advance via a separate “plan” command.
3. Normally builds all its outputs in a single invocation.

Once wired as a MassGenerator, the tool gets per-file cache entries, plays cleanly with other processors sharing its output directory, and allows downstream processors to depend on its outputs.

How it works

1. The tool provides two modes

The wrapped tool must expose:

• Build mode: runs the actual generation. Produces all output files in one invocation.
• Plan mode: prints a JSON manifest to stdout listing every output it will produce, with per-output source dependencies. Does not produce any output files.

Both modes must be driven by the same internal function that enumerates outputs — otherwise the plan and the build diverge, and the cache is corrupted. This is a discipline the tool author upholds.

2. Plan phase (at graph-build time)

rsconstruct runs predict_command and parses its output. For each entry in the manifest, a product is added to the build graph with:

• inputs = the entry’s sources (files whose changes should trigger this output’s rebuild)
• outputs = [entry.path]
• processor = the MassGenerator instance name

3. Build phase

rsconstruct groups all dirty products for a MassGenerator instance into a single batch. The tool’s command is invoked once per batch; it produces all predicted files. Each product caches its own file as a blob, independently of the others.

In strict mode (default), after the tool exits rsconstruct verifies that every predicted file was produced and no unexpected files appeared in output_dirs. Mismatches are build-breaking errors.

4. Restore phase

When all products for a MassGenerator instance are clean, each is restored from its blob cache — the tool is not invoked at all. Partial cleanliness (some products clean, some dirty) triggers a single tool invocation, and clean products are cached/re-cached afterward.

Manifest format

{
  "version": 1,
  "outputs": [
    {
      "path": "_site/index.html",
      "sources": ["docs/index.md", "templates/default.html", "mysite.toml"]
    },
    {
      "path": "_site/about/index.html",
      "sources": ["docs/about.md", "templates/default.html", "mysite.toml"]
    }
  ]
}

• version — integer. Schema version. Current: 1.
• outputs[].path — relative path. Must fall within one of the processor’s output_dirs.
• outputs[].sources — minimal set of input files whose changes invalidate this output.

Configuration

[processor.mass_generator.site]
command         = "rssite build"
predict_command = "rssite plan"
output_dirs     = ["_site"]
src_dirs        = ["docs", "templates"]
src_extensions  = [".md", ".html", ".yaml"]
# loose_manifest = false   # optional; set to true to downgrade verification mismatches to warnings

Fields

Cross-processor dependencies

Because every output file is a declared product, downstream processors wire up naturally:

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

[processor.markdownlint]
# Depends on rssite's outputs automatically via file-scan:
# any _site/*.html file is a discovered virtual file in the graph.
src_dirs       = ["_site"]
src_extensions = [".html"]

No ordering hacks needed. The graph’s topological sort handles it.

Tool author contract

For a tool to be compatible with MassGenerator, its plan command must uphold these invariants:

1. Pure function of config + source tree. Same inputs → same manifest, bit for bit. No network, no timestamps, no env-var peeking (unless declared as a source).
2. Cheap or cached. rsconstruct invokes it on every graph build. Slow plan → slow rsconstruct.
3. Exact match with build output. Predicted paths must equal actual paths produced by command. Violations are errors in strict mode.
4. Deterministic variable outputs. Content-derived outputs (tag pages, archive indices, RSS) must be enumerable from the same parsing pass that plan does.

See rssite for a reference tool being built to this contract.

Comparison with other processor types

Migration story

If a tool exists first as a Creator (output_dirs only) and later adds plan support, the migration is config-only:

# Before
[processor.creator.mysite]
command     = "mysite build"
output_dirs = ["_site"]

# After
[processor.mass_generator.mysite]
command         = "mysite build"
predict_command = "mysite plan"
output_dirs     = ["_site"]

No code changes; existing downstream processors start getting precise dependencies automatically.

See also

• Output Prediction — full design rationale, invariants, execution shape
• Shared Output Directory — the fallback mechanism for opaque Creators
• Processor Ordering — sibling discussion about explicit ordering knobs
• rssite — a static site generator being built to implement this contract

Markdownlint Processor

Purpose

Lints Markdown files using markdownlint (Node.js).

How It Works

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

Depends on the npm processor — uses the markdownlint binary installed by npm.

Source Files

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

Configuration

[processor.markdownlint]
command = "node_modules/.bin/markdownlint"  # Path to the markdownlint binary
args = []                              # Additional arguments to pass to markdownlint
npm_stamp = "out/npm/root.stamp"       # Stamp file from npm processor (dependency)
dep_inputs = []                      # 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.

Marp Processor

Purpose

Converts Markdown slides to PDF, PPTX, or HTML using Marp.

How It Works

Discovers .md files in the project and runs marp on each file, generating output in the configured formats. Each format produces a separate output file.

Each marp invocation spawns a headless Chromium browser instance via Puppeteer to render the slides. This makes marp significantly more resource-intensive than typical processors — see Concurrency limiting below.

Source Files

• Input: **/*.md
• Output: out/marp/{format}/{relative_path}.{format}

Configuration

[processor.marp]
marp_bin = "marp"                      # The marp command to run
formats = ["pdf"]                      # Output formats (pdf, pptx, html)
args = ["--html", "--allow-local-files"]  # Additional arguments to pass to marp
output_dir = "out/marp"                # Output directory
dep_inputs = []                      # Additional files that trigger rebuilds when changed
max_jobs = 2                           # Limit concurrent marp instances (each spawns Chromium)

Concurrency Limiting

Each marp invocation launches a full headless Chromium browser process, which consumes hundreds of megabytes of RAM. When running parallel builds with -j N, too many simultaneous Chromium instances cause resource exhaustion and non-deterministic crashes:

TargetCloseError: Protocol error (Target.setDiscoverTargets): Target closed

Use max_jobs to limit how many marp processes run concurrently, independent of the global -j setting. For example, with -j 20 and max_jobs = 2, at most 2 Chromium instances will be alive at once while other processors still use the full 20 threads:

[processor.marp]
formats = ["pdf"]
max_jobs = 2

Recommended value: 2. A value of 4 may work on machines with plenty of RAM but has been observed to produce occasional failures on large projects (700+ slides). Without max_jobs, the global -j value applies, which typically causes crashes at higher parallelism levels.

Batch Support

Each input file is processed individually, producing its own output file.

Temporary Files

Marp creates temporary Chromium profile directories (marp-cli-*) in /tmp for each invocation. RSConstruct automatically cleans these up after each marp process completes, since marp itself does not delete them.

Mdbook Processor

Purpose

Builds mdbook documentation projects.

How It Works

Discovers book.toml files indicating mdbook projects, collects sibling .md and .toml files as inputs, and runs mdbook build. A non-zero exit code fails the product.

Source Files

• Input: **/book.toml (plus sibling .md, .toml files)
• Output: none (creator — produces output in book directory)

Configuration

[processor.mdbook]
command = "mdbook"                     # The mdbook command to run
output_dir = "book"                    # Output directory for generated docs
args = []                              # Additional arguments to pass to mdbook
dep_inputs = []                      # Additional files that trigger rebuilds when changed
cache_output_dir = true                # Cache the output directory for fast restore after clean

Batch support

Runs as a single whole-project operation (e.g., cargo build, npm install).

Mdl Processor

Purpose

Lints Markdown files using mdl (Ruby markdownlint).

How It Works

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

Depends on the gem processor — uses the mdl binary installed by Bundler.

Source Files

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

Configuration

[processor.mdl]
gem_home = "gems"                      # GEM_HOME directory
command = "gems/bin/mdl"              # Path to the mdl binary
args = []                              # Additional arguments to pass to mdl
gem_stamp = "out/gem/root.stamp"       # Stamp file from gem processor (dependency)
dep_inputs = []                      # 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.

Mermaid Processor

Purpose

Converts Mermaid diagram files to PNG, SVG, or PDF using mmdc (mermaid-cli).

How It Works

Discovers .mmd files in the project and runs mmdc on each file, generating output in the configured formats. Each format produces a separate output file.

Source Files

• Input: **/*.mmd
• Output: out/mermaid/{format}/{relative_path}.{format}

Configuration

[processor.mermaid]
mmdc_bin = "mmdc"                      # The mmdc command to run
formats = ["png"]                      # Output formats (png, svg, pdf)
args = []                              # Additional arguments to pass to mmdc
output_dir = "out/mermaid"             # Output directory
dep_inputs = []                      # Additional files that trigger rebuilds when changed

Batch support

Each input file is processed individually, producing its own output file.

Mypy Processor

Purpose

Type-checks Python source files using mypy.

How It Works

Discovers .py files in the project (excluding common non-source directories), runs mypy on each file, and creates a stub file on success. A non-zero exit code from mypy fails the product.

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

If a mypy.ini file exists in the project root, it is automatically added as an extra input so that configuration changes trigger rebuilds.

Source Files

• Input: **/*.py
• Output: out/mypy/{flat_name}.mypy

Configuration

[processor.mypy]
command = "mypy"                             # The mypy command to run
args = []                                    # Additional arguments to pass to mypy
dep_inputs = []                            # Additional files that trigger rebuilds (e.g. ["pyproject.toml"])

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.

Using mypy.ini

Mypy automatically reads configuration from a mypy.ini file in the project root. This file is detected automatically and added as an extra input, so changes to it will trigger rebuilds without manual configuration.

Npm Processor

Purpose

Installs Node.js dependencies from package.json files using npm.

How It Works

Discovers package.json files in the project, runs npm install in each directory, and creates a stamp file on success. Sibling .json, .js, and .ts files are tracked as inputs so changes trigger reinstallation.

Source Files

• Input: **/package.json (plus sibling .json, .js, .ts files)
• Output: out/npm/{flat_name}.stamp

Configuration

[processor.npm]
command = "npm"                        # The npm command to run
args = []                              # Additional arguments to pass to npm install
dep_inputs = []                      # Additional files that trigger rebuilds when changed
cache_output_dir = true                # Cache the node_modules directory for fast restore after clean

Batch support

Runs as a single whole-project operation (e.g., cargo build, npm install).

Objdump Processor

Purpose

Disassembles ELF binaries using objdump.

How It Works

Discovers .elf files under out/cc_single_file/, runs objdump to produce disassembly output, and writes the result to the configured output directory.

Source Files

• Input: out/cc_single_file/**/*.elf
• Output: disassembly files in output directory

Configuration

[processor.objdump]
args = []
dep_inputs = []
output_dir = "out/objdump"

Batch support

Each input file is processed individually, producing its own output file.

Pandoc Processor

Purpose

Converts documents between formats using pandoc.

How It Works

Discovers .md files in the project and runs pandoc on each file, converting from the configured source format to the configured output formats.

Source Files

• Input: **/*.md
• Output: out/pandoc/{format}/{relative_path}.{format}

Configuration

[processor.pandoc]
pandoc = "pandoc"                      # The pandoc command to run
from = "markdown"                      # Source format
formats = ["pdf"]                      # Output formats (pdf, docx, html, etc.)
args = []                              # Additional arguments to pass to pandoc
output_dir = "out/pandoc"              # Output directory
dep_inputs = []                      # Additional files that trigger rebuilds when changed

Batch support

Each input file is processed individually, producing its own output file.

Pdflatex Processor

Purpose

Compiles LaTeX documents to PDF using pdflatex.

How It Works

Discovers .tex files in the project and runs pdflatex on each file. Runs multiple compilation passes (configurable) to resolve cross-references and table of contents. Optionally uses qpdf to linearize the output PDF.

Source Files

• Input: **/*.tex
• Output: out/pdflatex/{relative_path}.pdf

Configuration

[processor.pdflatex]
command = "pdflatex"                   # The pdflatex command to run
runs = 2                               # Number of compilation passes
qpdf = true                           # Use qpdf to linearize output PDF
args = []                              # Additional arguments to pass to pdflatex
output_dir = "out/pdflatex"            # Output directory
dep_inputs = []                      # Additional files that trigger rebuilds when changed

Batch support

Each input file is processed individually, producing its own output file.

Pdfunite Processor

Purpose

Merges PDF files from subdirectories into single combined PDFs using pdfunite.

How It Works

Scans subdirectories of the configured source directory for files matching the configured extension. For each subdirectory, it locates the corresponding PDFs (generated by an upstream processor such as marp) and merges them into a single output PDF.

This processor is designed for course/module workflows where slide decks in subdirectories are combined into course bundles.

Source Files

• Input: PDFs from upstream processor (e.g., out/marp/pdf/{subdir}/*.pdf)
• Output: out/courses/{subdir}.pdf

Configuration

[processor.pdfunite]
command = "pdfunite"                   # The pdfunite command to run
source_dir = "marp/courses"           # Base directory containing course subdirectories
source_ext = ".md"                     # Extension of source files in subdirectories
source_output_dir = "out/marp/pdf"     # Where the upstream processor puts PDFs
args = []                              # Additional arguments to pass to pdfunite
output_dir = "out/courses"             # Output directory for merged PDFs
dep_inputs = []                      # Additional files that trigger rebuilds when changed

Batch support

Each input file is processed individually, producing its own output file.

Perlcritic Processor

Purpose

Analyzes Perl code using Perl::Critic.

How It Works

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

This processor supports batch mode.

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

Source Files

• Input: **/*.pl, **/*.pm
• Output: none (checker)

Configuration

[processor.perlcritic]
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.

PHP Lint Processor

Purpose

Checks PHP syntax using php -l.

How It Works

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

This processor supports batch mode.

Source Files

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

Configuration

[processor.php_lint]
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.

Pip Processor

Purpose

Installs Python dependencies from requirements.txt files using pip.

How It Works

Discovers requirements.txt files in the project, runs pip install -r on each, and creates a stamp file on success. The stamp file tracks the install state so dependencies are only reinstalled when requirements.txt changes.

Source Files

• Input: **/requirements.txt
• Output: out/pip/{flat_name}.stamp

Configuration

[processor.pip]
command = "pip"                        # The pip command to run
args = []                              # Additional arguments to pass to pip
dep_inputs = []                      # Additional files that trigger rebuilds when changed
cache_output_dir = true                # Cache the stamp directory for fast restore after clean

Batch support

Runs as a single whole-project operation (e.g., cargo build, npm install).

Protobuf Processor

Purpose

Compiles Protocol Buffer (.proto) files to generated source code using protoc.

How It Works

Files matching configured extensions in the proto/ directory are compiled using the Protocol Buffer compiler. Output is written to out/protobuf/:

proto/hello.proto  →  out/protobuf/hello.pb.cc

The --proto_path is automatically set to the parent directory of each input file.

Source Files

• Input: proto/**/*.proto
• Output: out/protobuf/ with .pb.cc extension

Configuration

[processor.protobuf]
protoc_bin = "protoc"                     # Protoc binary (default: "protoc")
src_extensions = [".proto"]                   # File extensions to process
output_dir = "out/protobuf"              # Output directory (default: "out/protobuf")
dep_inputs = []                         # Additional files that trigger rebuilds

Batch support

Each input file is processed individually, producing its own output file.

Pylint Processor

Purpose

Lints Python source files using pylint.

How It Works

Discovers .py files in the project (excluding common non-source directories), runs pylint on each file, and creates a stub file on success. A non-zero exit code from pylint fails the product.

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

If a .pylintrc file exists in the project root, it is automatically added as an extra input so that configuration changes trigger rebuilds.

Source Files

• Input: **/*.py
• Output: out/pylint/{flat_name}.pylint

Configuration

[processor.pylint]
args = []                                  # Additional arguments to pass to pylint
dep_inputs = []                          # Additional files that trigger rebuilds (e.g. ["pyproject.toml"])

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.

Pyrefly Processor

Purpose

Type-checks Python source files using pyrefly.

How It Works

Discovers .py files in the project (excluding common non-source directories), runs pyrefly check on each file, and records success in the cache. A non-zero exit code from pyrefly fails the product.

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

Source Files

• Input: **/*.py
• Output: none (linter)

Configuration

[processor.pyrefly]
command = "pyrefly"                          # The pyrefly command to run
args = []                                    # Additional arguments to pass to pyrefly
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.

Pytest Processor

Purpose

Runs Python test files using pytest to verify they pass.

How It Works

Python test files (.py) in the tests/ directory are run using pytest. Each test file is checked individually — a failing test causes the build to fail.

Source Files

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

Configuration

[processor.pytest]
src_extensions = [".py"]                      # File extensions to process (default: [".py"])
src_dirs = ["tests"]                     # Directories to scan (default: ["tests"])
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.

Requirements Processor

Purpose

Generates a requirements.txt file for a Python project by scanning the project’s .py source files for import statements and listing the third-party PyPI distributions they reference.

How It Works

1. Scans every .py file in the project’s source directories.
2. Extracts the top-level module name from each import / from statement.
3. Drops imports that resolve to a local project file (intra-project imports).
4. Drops imports that are part of the Python standard library.
5. Drops imports listed in exclude.
6. Maps each remaining import name to its PyPI distribution name using the built-in curated table (e.g. cv2 → opencv-python, yaml → PyYAML). User-supplied mapping entries win over the built-in table.
7. Writes the deduplicated result to requirements.txt.

Import → Distribution Mapping

Most Python packages publish under the same name as their top-level import, so the default is identity (import requests → requests). A curated table handles the common exceptions:

Projects that import an unusual name should add an override:

[processor.requirements.mapping]
internal_tools = "acme-internal-tools"

Limitations

• No version pinning. The generated file lists bare distribution names. Running pip freeze > requirements.txt is the right tool if you need pinned versions.
• Static analysis only. Conditional imports inside try blocks, runtime __import__ calls, and string-based imports are not detected.
• Curated mapping is finite. Packages with import/distribution name mismatches not in the built-in table default to identity; add them to mapping when needed.

Source Files

• Input: **/*.py (configurable via src_dirs / src_extensions)
• Output: requirements.txt (configurable via output)

Configuration

[processor.requirements]
output = "requirements.txt"    # Output file path
exclude = []                   # Import names to never emit
sorted = true                  # Sort entries alphabetically
header = true                  # Include a "# Generated by rsconstruct" header

[processor.requirements.mapping]
# Per-project overrides: import_name = "pypi-distribution-name"
# These win over the built-in curated table.

Batch support

Runs as a single whole-project operation — all .py files feed into one requirements.txt output.

Ruff Processor

Purpose

Lints Python source files using ruff.

How It Works

Discovers .py files in the project (excluding common non-source directories), runs ruff check on each file, and creates a stub file on success. A non-zero exit code from ruff fails the product.

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

Source Files

• Input: **/*.py
• Output: out/ruff/{flat_name}.ruff

Configuration

[processor.ruff]
command = "ruff"                            # The ruff command to run
args = []                                  # Additional arguments to pass to ruff
dep_inputs = []                          # Additional files that trigger rebuilds (e.g. ["pyproject.toml"])

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.

Rumdl Processor

Purpose

Lints Markdown files using rumdl.

How It Works

Discovers .md files in the project (excluding common non-source directories), runs rumdl check on each file, and creates a stub file on success. A non-zero exit code from rumdl fails the product.

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

Source Files

• Input: **/*.md
• Output: out/rumdl/{flat_name}.rumdl

Configuration

[processor.rumdl]
command = "rumdl"                             # The rumdl command to run
args = []                                    # Additional arguments to pass to rumdl
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.

Rust Single File Processor

Purpose

Compiles single-file Rust programs (.rs) into executables, similar to the cc_single_file processor but for Rust.

How It Works

Rust source files in the src/ directory are compiled directly to executables using rustc. This is useful for exercise, example, or utility repositories where each .rs file is a standalone program.

Output is written to out/rust_single_file/ preserving the directory structure:

src/hello.rs  →  out/rust_single_file/hello.elf
src/exercises/ex1.rs  →  out/rust_single_file/exercises/ex1.elf

Source Files

• Input: src/**/*.rs
• Output: out/rust_single_file/ with configured suffix (default: .elf)

Configuration

[processor.rust_single_file]
command = "rustc"                         # Rust compiler (default: "rustc")
flags = []                                # Additional compiler flags
output_suffix = ".elf"                    # Output file suffix (default: ".elf")
output_dir = "out/rust_single_file"       # Output directory
dep_inputs = []                         # Additional files that trigger rebuilds

Batch support

Each input file is processed individually, producing its own output file.

Sass Processor

Purpose

Compiles SCSS and SASS files into CSS using the Sass compiler.

How It Works

Files matching configured extensions in the sass/ directory are compiled to CSS. Output is written to out/sass/ preserving the directory structure:

sass/style.scss  ->  out/sass/style.css
sass/components/button.scss  ->  out/sass/components/button.css

Source Files

• Input: sass/**/*{src_extensions}
• Output: out/sass/ mirroring the source structure with .css extension

Configuration

[processor.sass]
sass_bin = "sass"                         # Sass compiler binary (default: "sass")
src_extensions = [".scss", ".sass"]           # File extensions to process
output_dir = "out/sass"                   # Output directory (default: "out/sass")
dep_inputs = []                         # Additional files that trigger rebuilds

Batch support

Each input file is processed individually, producing its own output file.

Script Processor

Purpose

Runs a user-configured script or command as a linter on discovered files. This is a generic linter that lets you plug in any script without writing a custom processor.

How It Works

Discovers files matching the configured extensions in the configured scan directory, then runs the configured linter command on each file (or batch of files). A non-zero exit code from the script fails the product.

This processor is disabled by default — you must set enabled = true and provide a command in your rsconstruct.toml.

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

Source Files

• Input: configured via src_extensions and src_dirs
• Output: none (checker)

Configuration

[processor.script]
enabled = true
command = "python"
args = ["scripts/md_lint.py", "-q"]
src_extensions = [".md"]
src_dirs = ["marp"]

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.

Shellcheck Processor

Purpose

Lints shell scripts using shellcheck.

How It Works

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

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

Source Files

• Input: **/*.sh, **/*.bash
• Output: none (linter)

Configuration

[processor.shellcheck]
command = "shellcheck"                       # The shellcheck command to run
args = []                                    # Additional arguments to pass to shellcheck
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.

Slidev Processor

Purpose

Builds Slidev presentations.

How It Works

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

This processor supports batch mode.

Source Files

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

Configuration

[processor.slidev]
args = []
dep_inputs = []