feature-flag-management

name	feature-flag-management
description	Conventions for adding / propagating Cargo features across the stochastic-rs workspace. Invoke when adding a new optional dependency, gating a sub-module, or debugging "feature X enabled in crate A but not B" build errors.

Feature flag management — stochastic-rs

The workspace has 8 sub-crates, several of which carry optional dependencies (openblas, cuda-native, gpu, metal, accelerate, python, yahoo, ai, hotpath). Without discipline, cargo check --all-features explodes with "feature X needed but not propagated" or, worse, an unflagged path silently compiles a Box<dyn Fn(f64) -> f64> that panics at runtime.

This SKILL documents the conventions that prevent the §4.1 feature-flag trap (rc.0 release-blocker: a dep: proxy feature that compiled in single-crate isolation but blew up under --all-features).

1. Three patterns, three uses

1.1 dep: proxy syntax (preferred for optional dependencies)

# In stochastic-rs-quant/Cargo.toml:
[dependencies]
yahoo_finance_api = { workspace = true, optional = true }

[features]
yahoo = ["dep:yahoo_finance_api"]

Why: the dep: prefix tells Cargo that "yahoo" is a feature only, and never a transitive enable. Without dep:, auto-creates a feature named whenever the crate has an optional dep of that name, and any sub-crate that lists as a plain dep silently activates it. That's the exact failure mode we hit in rc.0.