rsconstruct 0.9.145

Rust based fast build system
# CC Single File Processor

## Purpose

Compiles C (`.c`) and C++ (`.cc`) source files into executables, one source file per executable. A file is C++ by extension — `.cc`, `.cpp`, `.cxx`, `.c++` or `.C` — and gets the C++ compiler and `cxxflags`; everything else gets the C compiler and `cflags`. The default `src_extensions` is `[".c", ".cc"]`; add `.cpp`/`.cxx` to it to compile those too.

## How It Works

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

```text
src/main.c       →  out/processor.generator.cc_single_file/main.elf
src/a/b.c        →  out/processor.generator.cc_single_file/a/b.elf
src/app.cc       →  out/processor.generator.cc_single_file/app.elf
```

Header dependencies are tracked by the [cpp](../../analyzers/cpp.md) /
[icpp](../../analyzers/icpp.md) analyzer, which scans `#include` directives and adds the
headers as inputs. When a header changes, all source files that include it are rebuilt.
Every entry of `src_dirs` is scanned; a missing entry is a config error unless
`[build] allow_missing_src_dirs = true`, in which case the other entries still build.

## Source Files

- Input: `{source_dir}/**/*.c`, `{source_dir}/**/*.cc`
- Output: `out/processor.generator.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

```c
// 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):

```c
// 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):

```c
// 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:

```c
// 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:

```c
// 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.generator.cc_single_file.compilers]]` configuration:

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

[[processor.generator.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`:

```c
// 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()`:

```c
// 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:

```c
// EXCLUDE_PROFILE=clang icc
```

### Directive summary

| Directive | Execution | Use case |
|---|---|---|
| `EXTRA_COMPILE_FLAGS_BEFORE` | Literal flags | Flags before default cflags |
| `EXTRA_COMPILE_FLAGS_AFTER` | Literal flags | Flags after default cflags |
| `EXTRA_LINK_FLAGS_BEFORE` | Literal flags | Flags before default ldflags |
| `EXTRA_LINK_FLAGS_AFTER` | Literal flags | Flags after default ldflags |
| `EXTRA_COMPILE_CMD` | Subprocess (no shell) | Dynamic compile flags via command |
| `EXTRA_LINK_CMD` | Subprocess (no shell) | Dynamic link flags via command |
| `EXTRA_COMPILE_SHELL` | `sh -c` (full shell) | Dynamic compile flags needing shell features |
| `EXTRA_LINK_SHELL` | `sh -c` (full shell) | Dynamic link flags needing shell features |

### Supported comment styles

Directives can appear in any of these comment styles:

**C++ style:**
```c
// EXTRA_LINK_FLAGS_AFTER=-lX11
```

**C block comment (single line):**
```c
/* EXTRA_LINK_FLAGS_AFTER=-lX11 */
```

**C block comment (multi-line, star-prefixed):**
```c
/*
 * EXTRA_LINK_FLAGS_AFTER=-lX11
 */
```

## Command Line Ordering

The compiler command is constructed in this order:

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

| Position | Source |
|---|---|
| `compile_before` | `EXTRA_COMPILE_FLAGS_BEFORE` + `EXTRA_COMPILE_CMD` + `EXTRA_COMPILE_SHELL` |
| `cflags/cxxflags` | `[processor.generator.cc_single_file]` config `cflags` or `cxxflags` |
| `compile_after` | `EXTRA_COMPILE_FLAGS_AFTER` |
| `link_before` | `EXTRA_LINK_FLAGS_BEFORE` + `EXTRA_LINK_CMD` + `EXTRA_LINK_SHELL` |
| `ldflags` | `[processor.generator.cc_single_file]` config `ldflags` |
| `link_after` | `EXTRA_LINK_FLAGS_AFTER` |

## Verbosity Levels (`--processor-verbose N`)

| Level | Output |
|-------|--------|
| 0 (default) | Target basename: `main.elf` |
| 1 | Target path + compiler commands: `out/processor.generator.cc_single_file/main.elf` |
| 2 | Adds source path: `out/processor.generator.cc_single_file/main.elf <- src/main.c` |
| 3 | Adds all inputs: `out/processor.generator.cc_single_file/main.elf <- src/main.c, src/utils.h` |

## Configuration

### Single Compiler (Legacy)

```toml
[processor.generator.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 (required; no default)
output_suffix = ".elf"    # Suffix for output executables (default: ".elf")
dep_inputs = []         # Additional files that trigger rebuilds when changed
```

### Multiple Compilers

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

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

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

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

```text
src/main.c  →  out/processor.generator.cc_single_file/gcc/main.elf
            →  out/processor.generator.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

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `cc` | string | `"gcc"` | C compiler command |
| `cxx` | string | `"g++"` | C++ compiler command |
| `cflags` | string[] | `[]` | Flags passed to the C compiler |
| `cxxflags` | string[] | `[]` | Flags passed to the C++ compiler |
| `ldflags` | string[] | `[]` | Flags passed to the linker |
| `include_paths` | string[] | `[]` | Additional `-I` include paths (shared) |
| `src_dirs` | string[] | `[]` | Directories to scan for source files. No default — an unset `src_dirs` scans nothing. |
| `output_suffix` | string | `".elf"` | Suffix appended to output executables |
| `dep_inputs` | string[] | `[]` | Extra files whose changes trigger rebuilds |
| `required_tools` | string[] | `[]` | Extra tools the build needs on PATH beyond the profiles' compilers (e.g. what a wrapper compiler shells out to); checked before building and covered by `tool install` and version locking |
| `compilers` | array | `[]` | Multiple compiler profiles (overrides single-compiler fields) |

### Compiler Profile Fields

Each entry in the `compilers` array can have:

| Key | Type | Required | Description |
|-----|------|----------|-------------|
| `name` | string | Yes | Profile name (used in output path) |
| `cc` | string | No | C compiler (default: "gcc") |
| `cxx` | string | No | C++ compiler (default: "g++") |
| `cflags` | string[] | No | C compiler flags |
| `cxxflags` | string[] | No | C++ compiler flags |
| `ldflags` | string[] | No | Linker flags |
| `output_suffix` | string | No | Output suffix (default: ".elf") |

## Batch support

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

## Header dependencies

Header scanning is not a setting of this processor: it is done by the
[cpp](../../analyzers/cpp.md) or [icpp](../../analyzers/icpp.md) analyzer, whose
`include_paths` (and, for `cpp`, compiler and flag) fields control how `#include` directives are resolved.

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