Equipe Rust Brasil 6 min de leitura

Guia Completo do Cargo

Guia completo do Cargo: criar projetos, build, run, test, doc, publish, workspaces, features, profiles e cargo install. Tudo sobre o build system do Rust.

rust instalação cargo build gerenciador de pacotes workspaces

O Cargo e o gerenciador de pacotes, build system e task runner oficial do Rust. Ele gerencia dependencias, compila projetos, executa testes, gera documentacao e publica crates. Neste guia completo, vamos explorar todos os comandos e recursos essenciais do Cargo.

Primeiros Comandos

Criar um Novo Projeto

# Criar um binário (aplicação)
cargo new meu-app
cd meu-app

# Criar uma biblioteca
cargo new minha-lib --lib

# Inicializar em um diretório existente
cargo init
cargo init --lib

Estrutura de um Projeto Cargo

meu-app/
├── Cargo.toml       # Manifesto do projeto
├── Cargo.lock       # Lock de dependências (commitado para binários)
├── src/
│   ├── main.rs      # Ponto de entrada (binários)
│   └── lib.rs       # Ponto de entrada (bibliotecas)
├── tests/           # Testes de integração
├── benches/         # Benchmarks
├── examples/        # Exemplos
└── target/          # Artefatos de compilação

Build, Run e Test

# Compilar em modo debug
cargo build

# Compilar em modo release (otimizado)
cargo build --release

# Compilar e executar
cargo run

# Executar com argumentos
cargo run -- arg1 arg2

# Verificar erros sem compilar (mais rápido)
cargo check

# Executar testes
cargo test

# Executar testes com saída visível
cargo test -- --nocapture

# Executar um teste específico
cargo test nome_do_teste

Cargo.toml: O Manifesto

O Cargo.toml define tudo sobre seu projeto:

[package]
name = "meu-app"
version = "0.1.0"
edition = "2024"
authors = ["Seu Nome <email@exemplo.com>"]
description = "Descrição do projeto"
license = "MIT"
repository = "https://github.com/usuario/meu-app"

[dependencies]
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1", features = ["full"] }
reqwest = "0.12"

[dev-dependencies]
criterion = "0.5"
tempfile = "3"

[build-dependencies]
cc = "1.0"

[[bin]]
name = "meu-app"
path = "src/main.rs"

Gerenciar Dependencias

# Adicionar uma dependência
cargo add serde
cargo add serde --features derive
cargo add tokio -F full

# Adicionar como dev-dependency
cargo add criterion --dev

# Remover uma dependência
cargo remove serde

# Atualizar dependências
cargo update

# Atualizar uma dependência específica
cargo update -p serde

# Ver árvore de dependências
cargo tree

# Ver dependências desatualizadas
cargo install cargo-outdated
cargo outdated

Features

Features permitem compilação condicional de funcionalidades:

[features]
default = ["json"]
json = ["dep:serde_json"]
xml = ["dep:quick-xml"]
full = ["json", "xml"]

[dependencies]
serde_json = { version = "1.0", optional = true }
quick-xml = { version = "0.31", optional = true }

Usar features:

# Compilar com features padrão
cargo build

# Compilar sem features padrão
cargo build --no-default-features

# Compilar com features específicas
cargo build --features "json,xml"

# Compilar com todas as features
cargo build --all-features

Profiles de Compilação

Profiles controlam as otimizações do compilador:

# Cargo.toml

# Profile de desenvolvimento (cargo build)
[profile.dev]
opt-level = 0
debug = true
overflow-checks = true

# Profile de release (cargo build --release)
[profile.release]
opt-level = 3
lto = true
codegen-units = 1
strip = true
panic = "abort"

# Profile customizado para testes
[profile.test]
opt-level = 1

# Profile customizado para benchmarks
[profile.bench]
opt-level = 3
lto = true

# Usar profile de release
cargo build --release

# O binário release fica em:
# target/release/meu-app (muito menor e mais rápido)

Para entender como builds release funcionam em CI, consulte o guia de GitHub Actions.

Workspaces

Workspaces permitem gerenciar múltiplos crates em um único repositório:

# Cargo.toml (raiz)
[workspace]
members = [
    "crates/core",
    "crates/api",
    "crates/cli",
]
resolver = "2"

[workspace.package]
version = "0.1.0"
edition = "2024"
authors = ["Equipe <team@example.com>"]

[workspace.dependencies]
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1", features = ["full"] }

Em cada crate do workspace:

# crates/api/Cargo.toml
[package]
name = "meu-app-api"
version.workspace = true
edition.workspace = true

[dependencies]
serde.workspace = true
meu-app-core = { path = "../core" }

Comandos para workspaces:

# Build de todo o workspace
cargo build --workspace

# Testar todo o workspace
cargo test --workspace

# Build de um crate específico
cargo build -p meu-app-api

# Executar o binário CLI
cargo run -p meu-app-cli

Documentação

O Cargo gera documentação a partir dos doc comments:

# Gerar documentação
cargo doc

# Gerar e abrir no navegador
cargo doc --open

# Incluir dependências na documentação
cargo doc --document-private-items

# Gerar documentação do workspace
cargo doc --workspace

Publicar Crates

Para publicar no crates.io:

# Login (necessário uma vez)
cargo login seu-token-aqui

# Verificar antes de publicar
cargo publish --dry-run

# Publicar
cargo publish

# Publicar em um workspace (crate específico)
cargo publish -p minha-lib

Checklist antes de publicar:

  1. Preencher [package] no Cargo.toml (name, version, description, license)
  2. Incluir um README.md
  3. Verificar com cargo clippy e cargo test
  4. Rodar cargo publish --dry-run

cargo install

Para instalar binários de crates publicados:

# Instalar um binário
cargo install ripgrep
cargo install fd-find
cargo install cargo-watch

# Instalar de um repositório git
cargo install --git https://github.com/usuario/repo

# Instalar versão específica
cargo install ripgrep --version 14.0.0

# Listar binários instalados
cargo install --list

# Desinstalar
cargo uninstall ripgrep

Os binários são instalados em ~/.cargo/bin/.

Ferramentas Úteis via Cargo

# Recompilação automática ao salvar
cargo install cargo-watch
cargo watch -x run
cargo watch -x test

# Auditoria de segurança
cargo install cargo-audit
cargo audit

# Expansão de macros
cargo install cargo-expand
cargo expand

# Verificar código não utilizado
cargo install cargo-udeps --locked
cargo +nightly udeps

# Binários mais rápidos para instalar
cargo install cargo-binstall
cargo binstall ripgrep

Configuração Global

Crie ~/.cargo/config.toml para configurações globais:

[build]
# Usar mais jobs de compilação
jobs = 8

[target.x86_64-unknown-linux-gnu]
# Usar linker mais rápido
linker = "clang"
rustflags = ["-C", "link-arg=-fuse-ld=mold"]

[net]
# Configurar proxy
# proxy = "http://proxy:8080"

[registries.crates-io]
protocol = "sparse"

[alias]
b = "build"
r = "run"
t = "test"
c = "check"
cl = "clippy"

Solução de Problemas

Compilação lenta

Use um linker rápido (mold, lld ou zld) e habilite compilação incremental:

# Instalar mold (Linux)
sudo apt install mold  # ou equivalente

# Verificar compilação incremental
echo $CARGO_INCREMENTAL  # deve ser 1 ou não definido

Erro: “failed to select a version for the requirement”

Conflito de dependências. Verifique com:

cargo tree -d  # Mostra duplicatas
cargo update   # Tenta resolver

Cache do Cargo corrompido

# Limpar cache de build
cargo clean

# Limpar cache de registro
rm -rf ~/.cargo/registry/cache/
cargo fetch

Próximos Passos

Com o Cargo dominado:

Se você também usa build systems em outras linguagens, confira o golang.com.br para comparar o Cargo com o Go modules.

Última atualização: 23 de fevereiro de 2026. Para remover o Cargo e o Rust, veja Como Desinstalar Rust.