Explicação do Cargo.toml
Cargo.toml é o manifesto que o Cargo lê para cada build. Ele declara a identidade da sua crate, dependências, features, perfis e associação a workspaces.
Receita
[package]
name = "api"
version = "0.1.0"
edition = "2024"
rust-version = "1.97"
[dependencies]
axum = "0.8"
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1", features = ["full"] }
[dev-dependencies]
tower = { version = "0.5", features = ["util"] }Quando usar isso: Sempre que você adicionar uma crate, fixar uma versão do Rust ou ajustar perfis de build.
Exemplo de Trabalho
Um pequeno manifesto de serviço Axum com pins de dependência prontos para workspace:
[package]
name = "orders-api"
version = "0.3.1"
edition = "2024"
rust-version = "1.97"
license = "MIT OR Apache-2.0"
description = "API HTTP de Pedidos"
repository = "https://github.com/acme/orders"
[dependencies]
axum = { version = "0.8", features = ["json"] }
serde = { version = "1.0", features = ["derive"] }
sqlx = { version = "0.8", features = ["runtime-tokio", "postgres"] }
thiserror = "2"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
tracing = "0.1"
[dev-dependencies]
reqwest = { version = "0.12", features = ["json"] }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
[profile.release]
lto = "thin"
codegen-units = 1O que isso demonstra:
edition = "2024"seleciona os padrões da linguagem para a craterust-versioninforma ao Cargo a MSRV; o CI deve corresponder- Flags de feature em dependências reduzem caminhos de código não utilizados
[profile.release]ajusta o binário de produção
Mergulho Profundo
Metadados [package]
| Campo | Propósito |
|---|---|
name | Nome da crate em crates.io e em caminhos use |
version | Semver para lançamentos |
edition | Superfície da linguagem 2018, 2021 ou 2024 |
rust-version | Rust mínimo suportado (MSRV) |
license / license-file | Necessário para publicação |
description | Resumo de uma linha para crates.io |
repository | URL da origem para documentação e cargo package |
Tabelas de Dependência
| Tabela | Quando |
|---|---|
[dependencies] | Sempre vinculadas em builds normais |
[dev-dependencies] | Apenas para testes, benchmarks, exemplos |
[build-dependencies] | Usadas apenas por build.rs |
Especificadores de versão:
serde = "1.0" # compatível com 1.0.x
tokio = { version = "1", features = ["rt"] }
sqlx = { version = "0.8", default-features = false }
local = { path = "../shared" }
git2 = { git = "https://github.com/org/git2-rs", rev = "abc123" }[features] e [lints]
[features]
default = ["postgres"]
postgres = ["sqlx/postgres"]
[lints.rust]
unsafe_code = "forbid"- Features propagam para dependências opcionais
[lints](Rust 1.74+) define níveis de lint em nível de crate no manifesto
Armadilhas
- Versões com caret vs. exatas -
"1.0"permite1.9emcargo update. Correção: fixe com"=1.0.210"apenas quando precisar reproduzir um build exato. rust-versionausente - contribuidores em toolchains mais antigas recebem erros confusos. Correção: defina a MSRV e documente no README.- Nomes de crate duplicados - renomear um pacote sem atualizar os caminhos
usequebra os dependentes. Correção: trate renomeações como semver-major para bibliotecas. - Explosão de features - cada dependência opcional deve ser mapeada para uma feature nomeada. Correção: evite
optional = truesem uma flag de feature que os consumidores possam habilitar. - Dependências de workspace não herdadas - membros repetem pins de versão. Correção: use
[workspace.dependencies]eworkspace = truenos membros.
Alternativas
| Alternativa | Usar Quando | Não Usar Quando |
|---|---|---|
CLI cargo add | Edições rápidas com sintaxe correta | Geração de manifestos em lote por script |
[patch] / [replace] | Forks locais durante o desenvolvimento | Estratégia de dependência permanente |
Apenas Cargo.lock | Aplicativos binários precisam de reprodutibilidade | Bibliotecas publicadas (geralmente omitem o lock) |
FAQs
O que é a edition 2024?
A Edition 2024 habilita padrões de linguagem mais recentes (por exemplo, blocos gen, prelude atualizado). É ortogonal à versão do compilador Rust; você ainda precisa do Rust 1.97+ para os recursos da toolchain que usa.
Bibliotecas devem commitar Cargo.lock?
Geralmente não para bibliotecas no crates.io; sim para aplicativos e raízes de workspace para que o CI e as implantações sejam reproduzíveis.
Como fixo uma dependência git?
Use as chaves git, branch, tag ou rev. Prefira releases marcadas em vez de branches flutuantes para produção.
O que significa default-features = false?
Desabilita o conjunto de features padrão da dependência para que você opte explicitamente, reduzindo o tempo de compilação e o tamanho do binário.
Um repositório pode ter múltiplos pacotes?
Sim, via [workspace] com múltiplos members. Cada membro tem sua própria seção [package].
Como compartilho versões entre membros de um workspace?
Defina as versões uma vez em [workspace.dependencies] e referencie com dep = { workspace = true }.
O que faz publish = false?
Marca um membro de workspace como apenas interno; cargo publish o ignora mesmo que ocorram aumentos de versão.
Como excluo arquivos da crate publicada?
Use exclude = [...] ou include = [...] em [package]; cargo package --list mostra o conteúdo do tarball.
Onde vão as configurações específicas de binários?
Tabelas [[bin]] nomeiam binários extras; [[example]] e [[test]] personalizam targets além dos padrões.
Como a MSRV interage com as dependências?
Se uma dependência requer Rust 1.80 e você define rust-version = "1.70", cargo build falha com um erro MSRV claro. Aumente seu piso ou faça downgrade da dependência.
Relacionados
- Noções Básicas do Cargo - layout e comandos do projeto
- Features e Dependências Opcionais - compilação condicional
- Gerenciamento de Dependências - atualizações e auditoria
- Workspaces - manifestos compartilhados
- Perfis e Configurações de Build - ajuste de release
Versões da Pilha: Esta página foi escrita para Rust 1.97.0 (edition 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4 e Polars 0.46+.