Noções Básicas de Cargo

10 exemplos para você começar com o Cargo - 7 básicos e 3 intermediários.

Pré-requisitos

• Rust 1.97.0 com edição 2024 (rustup default stable)
• cargo --version imprime 1.97 ou mais recente

Exemplos Básicos

1. Criar um Novo Crate Binário

cargo new cria um projeto executável com Cargo.toml e src/main.rs.

cargo new greeter
cd greeter
cargo run

• Cria Cargo.toml com metadados [package] e edição 2024
• src/main.rs é o ponto de entrada binário
• target/ contém artefatos de compilação (adicione ao gitignore)
• A saída padrão é uma compilação de depuração em target/debug/

Relacionado: Explicação do Cargo.toml - campos do manifesto

2. Criar um Crate de Biblioteca

Use --lib ao compilar um crate reutilizável em vez de um binário.

cargo new --lib math_utils
cd math_utils

pub fn add(a: i32, b: i32) -> i32 {
    a + b
}
 
#[cfg(test)]
mod tests {
    use super::*;
 
    #[test]
    fn adds() {
        assert_eq!(add(2, 2), 4);
    }
}

• A raiz da biblioteca é src/lib.rs
• A API pública é tudo marcado como pub
• Testes unitários ficam no mesmo arquivo sob #[cfg(test)]
• Consumidores adicionam math_utils = "0.1" ao seu Cargo.toml

Relacionado: Workspaces - repositórios com múltiplos crates

3. Compilar e Executar

cargo build compila; cargo run compila e executa o binário.

cargo build          # depuração (compilação rápida)
cargo build --release  # otimizado
cargo run -- arg1 arg2

• Compilações de depuração incluem símbolos para dbg! e backtraces
• --release usa as configurações de [profile.release]
• Argumentos extras após -- vão para o seu programa, não para o Cargo
• cargo check verifica tipos sem linkagem (ciclo de feedback mais rápido)

Relacionado: Perfis e Configurações de Compilação - níveis de otimização

4. Executar Testes

cargo test executa testes unitários, testes de integração e doctests.

cargo test
cargo test add_works -- --nocapture
cargo test --doc

• Testes unitários em src/**/*.rs sob #[cfg(test)]
• Testes de integração em tests/*.rs (crates separados)
• -- --nocapture mostra println! dos testes
• Testes falhos imprimem um backtrace com RUST_BACKTRACE=1

Relacionado: Noções Básicas de Testes - guia completo de testes

5. Adicionar uma Dependência

Declare crates em [dependencies]; o Cargo resolve as versões e compila um lockfile.

[dependencies]
serde = { version = "1.0", features = ["derive"] }

cargo add serde --features derive
cargo build

• cargo add edita Cargo.toml e baixa o crate
• Cargo.lock fixa versões exatas para compilações reproduzíveis
• Commite Cargo.lock para binários; bibliotecas geralmente o omitem
• cargo update -p serde atualiza um crate dentro dos limites do semver

Relacionado: Gerenciamento de Dependências - atualizações e auditoria

6. Layout do Projeto

Um crate binário padrão se parece com isto:

my_app/
├── Cargo.toml
├── Cargo.lock
├── src/
│   └── main.rs
└── tests/
    └── integration_test.rs

• src/main.rs = raiz binária; src/lib.rs = raiz da biblioteca (um ou ambos)
• benches/ para benchmarks Criterion; examples/ para exemplos de binários
• build.rs é executado antes da compilação quando código nativo ou codegen é necessário
• Arquivos de módulo vão para src/ como mod_name.rs ou mod_name/mod.rs

Relacionado: Scripts de Compilação (build.rs) - etapas de compilação personalizadas

7. Inspecionar o Projeto

Subcomandos do Cargo ajudam você a entender o que está compilando.

cargo metadata --format-version 1 | jq '.packages[].name'
cargo tree -p my_app
cargo doc --open

• cargo tree mostra o grafo de dependências
• cargo doc --open compila e abre a documentação da API das dependências
• cargo metadata é o grafo do projeto legível por máquina
• Use estes antes de adicionar dependências transitivas pesadas

Relacionado: Subcomandos Úteis do Cargo - expand, bloat, watch

Exemplos Intermediários

8. Features e Compilação Condicional

Habilite funcionalidades opcionais com features do Cargo.

[features]
default = ["std"]
std = []
 
[dependencies]
log = { version = "0.4", optional = true }

#[cfg(feature = "std")]
pub fn init() {
    log::info!("initialized");
}

cargo build --no-default-features
cargo build --features std

• Features são a principal forma de reduzir o tempo de compilação e o tamanho do binário
• #[cfg(feature = "...")] controla o código em tempo de compilação
• As features padrão devem ser o caso comum
• Documente flags de feature no README do crate e em comentários do Cargo.toml

Relacionado: Features e Dependências Opcionais

9. Comandos de Workspace

Execute o Cargo na raiz do workspace para compilar todos os crates membros.

cargo build --workspace
cargo test -p api
cargo run -p cli -- --help

• -p seleciona um pacote em um workspace
• --workspace compila todos os membros que compartilham um Cargo.lock
• [workspace.dependencies] compartilhado deduplica pins de versão
• CI geralmente executa cargo test --workspace --all-features

Relacionado: Workspaces - limites e layout

10. Publicar no crates.io

Prepare metadados, verifique localmente e depois publique.

cargo publish --dry-run
cargo package
cargo publish

[package]
name = "my_crate"
version = "0.1.0"
edition = "2024"
license = "MIT OR Apache-2.0"
description = "Resumo de uma linha para crates.io"
repository = "https://github.com/org/my_crate"

• cargo publish --dry-run detecta erros de manifesto precocemente
• Semver: alterações de API que quebram exigem um bump principal
• cargo package produz o tarball .crate localmente
• Defina CARGO_REGISTRY_TOKEN para publicação em CI não interativa

Relacionado: Publicando no crates.io

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+.