tap-args-feature-gating

name	tap-args-feature-gating
description	When a Titan bench tool accepts --tap via titan_render_bench_common::TapArgs, BOTH the CLI field AND the wiring in on_start must be gated behind
source	auto-skill
extracted_at	2026-06-16T03:07:24.361Z

Tap Args Feature Gating — Bench Tool Pattern

When adding --tap / TITAN_TAP support to a Titan bench tool via titan_render_bench_common::TapArgs, gate EVERYTHING behind #[cfg(feature = "debug-dumps")]. The CLI field AND the wiring in on_start must both be gated. A half-gated setup (gated wiring, ungated CLI) is a silent no-op trap.

The trap

TapArgs is defined in titan-render-bench-common behind #[cfg(feature = "debug-dumps")]. It implements clap::Args so it can be flattened into any #[derive(Parser)] struct.

If the CLI field is NOT gated but the wiring IS:

// main.rs — CLI field (NOT gated — always compiled)
#[command(flatten)]
tap: TapArgs,  // compiles: TapArgs is always available at type level

// on_start — wiring (GATED — only compiled with debug-dumps)
#[cfg(feature = "debug-dumps")]
if let Some(ref mut r) = self.renderer {
    if self.args.tap.any() {
        r.configure_taps(self.args.tap.to_tap_config());
        // ...
    }
}

In a non-debug-dumps build:

• --tap depth_prepass is accepted by clap with NO error or warning
• The wiring code is dead-code-eliminated
• The bench runs normally with zero tap output
• The user has no indication anything is wrong

This happened on titan-render-bench-culling as of 2026-06-15.

The correct pattern

Follow the probe bench's layout (tools/titan-render-bench-probe/src/main.rs):

// CLI — GATE the field
#[cfg(feature = "debug-dumps")]
#[command(flatten)]
tap: titan_render_bench_common::TapArgs,

// Wiring — GATE the wiring block
#[cfg(feature = "debug-dumps")]
if let Some(ref mut r) = self.renderer {
    if self.args.tap.any() {
        r.configure_taps(self.args.tap.to_tap_config());
        let ids = self.args.tap.selection_ids();
        r.configure_tap_selection(&ids);
    }
}

With both gated, a non-debug-dumps build rejects --tap with a clap error: "unexpected argument '--tap' found." The user immediately knows they need --features debug-dumps.

Cargo.toml feature forwarding

The bench's Cargo.toml must forward debug-dumps to the common crate:

[features]
debug-dumps = ["titan-render-bench-common/debug-dumps"]

Without this, TapArgs won't compile at all because the common crate's debug-dumps feature gates the struct definition.

Verification

# Should fail with clap error (no feature):
cargo run -p titan-render-bench-culling -- --tap depth_prepass

# Should accept --tap (with feature):
cargo run -p titan-render-bench-culling --features debug-dumps -- --tap depth_prepass --dump-dir out/