---
title: "Guia Completo do Cargo"
url: "https://rustlang.com.br/instalacao/cargo/"
markdown_url: "https://rustlang.com.br/instalacao/cargo.MD"
description: "Guia completo do Cargo: criar projetos, build, run, test, doc, publish, workspaces, features, profiles e cargo install. Tudo sobre o build system do Rust."
date: "2026-02-23"
author: "Equipe Rust Brasil"
---

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


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

```bash
# 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

```bash
# 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:

```toml
[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

```bash
# 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:

```toml
[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:

```bash
# 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:

```toml
# 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
```

```bash
# 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](/instalacao/github-actions/).

## Workspaces

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

```toml
# 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:

```toml
# 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:

```bash
# 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:

```bash
# 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](https://crates.io):

```bash
# 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:

```bash
# 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

```bash
# 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:

```toml
[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:

```bash
# 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:

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

### Cache do Cargo corrompido

```bash
# Limpar cache de build
cargo clean

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

## Próximos Passos

Com o Cargo dominado:

- Siga o tutorial de [Primeiros Passos com Rust](/tutoriais/primeiros-passos/)
- Consulte o [Cheatsheet Rust](/cheatsheet/) para referência rápida
- Aprenda a gerenciar toolchains com o [Guia Completo do Rustup](/instalacao/rustup/)
- Configure seu editor com o [guia de VS Code](/instalacao/vscode/) ou [Neovim](/instalacao/neovim/)
- Veja as [Perguntas Frequentes](/faq/) para dúvidas comuns

Se você também usa build systems em outras linguagens, confira o [golang.com.br](https://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](/instalacao/desinstalar/).*