Features: compilación condicional y unificación

Una feature es un interruptor con nombre que activa funcionalidad opcional: código que se compila solo si la enciendes, dependencias que solo se traen si hacen falta. Es el mecanismo con el que un mismo crate sirve a un microcontrolador sin std y a un servidor con todo el ecosistema. Pero bajo su comodidad late una ley inflexible que decide si tu diseño funciona o se rompe en árboles grandes: las features son aditivas y se unifican. El build no elige la feature de un consumidor, calcula la unión de las que pide todo el árbol. Diseñarlas como capacidades que se suman, y nunca como modos que se excluyen, es la diferencia entre componer y colisionar.

Declarar y consumir features

La tabla [features] define cada interruptor como una lista de otras features o dependencias que activa. La feature default es la que se enciende si no dices lo contrario:

[features]
default = ["std"]
std = []
serde = ["dep:serde"]
completo = ["std", "serde"]

[dependencies]
serde = { version = "1", optional = true }

En el código, #[cfg(feature = "x")] incluye o excluye elementos en tiempo de compilación. Lo que queda fuera no pesa ni un byte en el binario final:

#[cfg(feature = "std")]
pub fn cargar(ruta: &str) -> String {
    std::fs::read_to_string(ruta).unwrap()   // requiere std
}

#[cfg(not(feature = "std"))]
pub fn cargar(_ruta: &str) -> &'static str {
    "modo sin std"                            // variante para no_std
}

Quien te consume puede renunciar a tus defaults con default-features = false y reactivar solo lo que necesite. Así se compila un crate en un entorno no_std: apagando std.

[dependencies]
mi_crate = { version = "1", default-features = false, features = ["serde"] }

Dependencias opcionales y la sintaxis dep:

Marcar una dependencia como optional = true crea, por defecto, una feature implícita con su mismo nombre: activarla trae el crate. Eso es cómodo pero acopla el nombre de tu feature al de la dependencia. La sintaxis dep: rompe ese acoplamiento: referencia la dependencia opcional sin crear la feature implícita, de modo que tú decides cómo se llama la capacidad y qué la activa.

[features]
# La capacidad publica se llama "serializar", no "serde":
serializar = ["dep:serde", "chrono?/serde"]

[dependencies]
serde  = { version = "1", optional = true }
chrono = { version = "0.4", optional = true }

Ahí aparecen las dos formas de activar la feature de una dependencia. crate/feature enciende esa feature y, si el crate es opcional, lo trae. La forma débil crate?/feature —con la interrogación— es más quirúrgica: enciende la feature de chrono solo si chrono ya está activado por otra vía, sin traerlo por su cuenta. Es la herramienta para decir «si además usas fechas, que sepan serializarse» sin imponer la dependencia a todos.

La unificación y la ley de aditividad

Aquí está el concepto que decide si tu crate escala. Cuando dos partes del árbol usan el mismo crate con features distintas, Cargo no lo compila dos veces: lo compila una vez con la unión de todas las features pedidas. Si a activa serde/std y b usa serde sin std, el build entero recibe std. Nadie eligió esa combinación; emergió de sumar.

flowchart TD
APP[Build del binario] --> A[crate a pide serde con std]
APP --> B[crate b pide serde sin std]
A --> U[serde compilada UNA vez]
B --> U
U --> R[Union de features: gana std]
style U fill:#89b4fa,color:#11111b
style R fill:#a6e3a1,color:#11111b

De ahí se sigue la ley de aditividad: activar una feature solo puede añadir API o comportamiento, jamás quitarlo ni cambiarlo. Si la respetas, la unificación es inocua: recibir features de más nunca rompe a nadie. Si la violas —una feature que elimina un método, que cambia una firma, que contradice a otra—, algún consumidor lejano encenderá lo que tú apagabas y el fallo aflorará en código ajeno. El resolvedor 2 y el 3 afinan los bordes —las dependencias de compilación y las macros procedurales se resuelven aparte del grafo normal, y las features específicas de una plataforma no se filtran a otras—, pero dentro del grafo ordinario la unión manda.

cargo build --features "serde std"        # activa dos a la vez
cargo build --no-default-features --features serde
cargo build --all-features                # enciende todo: util en CI