rsconstruct 0.9.176

Rust based fast build system
# Pdfunite Processor

## Purpose

Merges PDF files from subdirectories into single combined PDFs using [pdfunite](https://poppler.freedesktop.org/).

The Rust alternative is [ipdfunite](ipdfunite.md): the same one PDF per subdirectory, merged in-process with lopdf, no poppler. Switching is `pdfunite` → `ipdfunite` in the stanza header.

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

The sources are located by `source_dir` and `source_ext`, not by `src_dirs` /
`src_extensions`; the standard `src_exclude_dirs`, `src_exclude_files`,
`src_exclude_paths` and `src_files` fields apply to that lookup as they do to a scan.

## Source Files

- Input: PDFs from upstream processor (e.g., `out/processor.generator.marp/{subdir}/*.pdf`)
- Output: `out/processor.generator.pdfunite/{subdir}.pdf`

## Configuration

```toml
[processor.generator.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/processor.generator.marp"     # Where the upstream processor puts PDFs
args = []                              # Additional arguments to pass to pdfunite
output_dir = "out/processor.generator.pdfunite"  # Output directory for merged PDFs
dep_inputs = []                      # Additional files that trigger rebuilds when changed
```

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `command` | string | `"pdfunite"` | The pdfunite executable to run |
| `source_dir` | string | `"marp/courses"` | Directory containing course subdirectories |
| `source_ext` | string | `".md"` | Extension of source files to look for |
| `source_output_dir` | string | `"out/processor.generator.marp"` | Directory where the upstream processor outputs PDFs |
| `args` | string[] | `[]` | Extra arguments passed to pdfunite |
| `output_dir` | string | `"out/processor.generator.pdfunite"` | Output directory for merged PDFs |
| `dep_inputs` | string[] | `[]` | Extra files whose changes trigger rebuilds |
| `required_tools` | string[] | `[]` | Extra tools the build needs on PATH beyond the built-in ones (e.g. what a wrapper script shells out to); checked before building and covered by `tool install` and version locking |

## Batch support

Each directory is merged individually, producing its own output file. Merges run one at a time (`max_jobs` is capped at 1).

## Clean behavior

This processor is a Generator — `rsconstruct clean outputs` removes each declared output file individually with no directory recursion. After all per-product cleans complete, the orchestrator removes any parent directories that are now empty. Pass `--no-empty-dirs` to keep them. See [Clean behavior](../../processors.md#clean-behavior) and [`rsconstruct clean`](../../commands.md#rsconstruct-clean).