Features & Optional Dependencies

Features do Cargo são a maneira padrão de compilar caminhos de código opcionais, conectar dependências opcionais e permitir que os consumidores paguem apenas pelo que habilitam.

Receita

[features]
default = ["std"]
std = ["dep:log"]
metrics = ["dep:prometheus"]
 
[dependencies]
log = { version = "0.4", optional = true }
prometheus = { version = "0.13", optional = true }

#[cfg(feature = "metrics")]
pub fn export_metrics() { /* ... */ }

Quando usar isso: Backends opcionais, código específico da plataforma ou para reduzir o tempo de compilação para consumidores da biblioteca.

Exemplo de Trabalho

Uma biblioteca com backends de banco de dados selecionados por feature:

[features]
default = ["postgres"]
postgres = ["dep:sqlx", "sqlx/postgres"]
sqlite = ["dep:sqlx", "sqlx/sqlite"]
 
[dependencies]
sqlx = { version = "0.8", optional = true, default-features = false }

#[cfg(feature = "postgres")]
pub async fn connect(url: &str) -> sqlx::Result<sqlx::PgPool> {
    sqlx::PgPool::connect(url).await
}
 
#[cfg(feature = "sqlite")]
pub async fn connect(url: &str) -> sqlx::Result<sqlx::SqlitePool> {
    sqlx::SqlitePool::connect(url).await
}

cargo build --no-default-features --features sqlite
cargo test --all-features

O que isso demonstra:

• Dependências opcionais ficam inativas até que uma feature as habilite
• Os nomes das features devem descrever a capacidade, não o detalhe de implementação
• A sintaxe dep:sqlx vincula uma feature diretamente a um crate opcional
• O CI deve testar --no-default-features e --all-features

Mergulho Profundo

Composição de Features

[features]
full = ["json", "metrics"]
json = ["dep:serde", "serde/derive"]

• Features podem habilitar outras features (semântica de união)
• Habilitar full inclui tudo o que ele lista
• Evite ciclos: a feature A não deve habilitar B se B habilitar A

cfg no Código

#[cfg(all(feature = "postgres", not(feature = "sqlite")))]
compile_error!("enable at most one database backend");

• Combine feature, target_os e flags cfg personalizadas
• Use compile_error! para conjuntos de features mutuamente exclusivos
• Documente as combinações de features necessárias na documentação do crate

Notas de Rust

#[cfg(feature = "std")]
use std::collections::HashMap;
 
#[cfg(not(feature = "std"))]
use hashbrown::HashMap;

• #[cfg(test)] é separado das features do Cargo
• cfg_attr anexa atributos condicionalmente
• required-features em [[example]] controla as demonstrações executáveis

Armadilhas

• Features padrão implícitas em dependências - você puxa código pesado não intencionalmente. Correção: default-features = false e lista explícita de features.
• Unificação de features em todo o workspace - um membro que habilita uma feature a habilita para todos os crates que compartilham essa dependência. Correção: separe backends incompatíveis em crates separados, se necessário.
• Renomeações de features que quebram - features = ["old"] downstream quebra silenciosamente em tempo de compilação. Correção: trate renomeações de features como semver-major para bibliotecas.
• Sem features para módulos internos - usar pub + feature para cada helper privado cria confusão na API. Correção: mantenha os módulos internos privados; controle apenas a superfície pública.
• Testar apenas features padrão - caminhos opcionais se deterioram. Correção: matriz de CI com --all-features e jobs por feature.

Alternativas

FAQs

Relacionados

• Cargo.toml Explicado - tabelas do manifesto
• Perfis e Configurações de Compilação - tamanho vs velocidade
• Scripts de Compilação (build.rs) - flags cfg personalizadas
• Design de Configuração e Features - design em nível de aplicativo

Versões da Stack: Esta página foi escrita para Rust 1.97.0 (edição 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4 e Polars 0.46+.