Empacotamento e Distribuição
Envie binários de CLI Rust com cargo-dist, GitHub Releases e gerenciadores de pacotes.
Receita
cargo install cargo-dist
cargo dist init
cargo dist build# dist.toml (gerado / personalizado)
[workspace.metadata.dist]
cargo-dist-version = "0.28.0"
installers = ["shell", "powershell"]
targets = ["aarch64-apple-darwin", "x86_64-unknown-linux-gnu", "x86_64-pc-windows-msvc"]Quando usar isso: CLIs públicas que precisam de artefatos de lançamento reproduzíveis e multiplataforma sem scripts manuais de CI.
Exemplo Funcional
# Cargo.toml
[package]
name = "mytool"
version = "0.1.0"
edition = "2024"
[workspace.metadata.dist]
# cargo dist lê isso para configuração de lançamento# .github/workflows/release.yml (simplificado)
name: Release
on:
push:
tags: ['v*']
jobs:
dist:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: dtolnay/rust-toolchain@stable
- run: cargo dist build --artifacts=local
- uses: softprops/action-gh-release@v2
with:
files: target/distrib/*# Instalação do usuário via instalador de shell
curl --proto '=https' --tlsv1.2 -LsSf \
https://github.com/org/mytool/releases/download/v0.1.0/mytool-installer.sh | shO que isso demonstra:
cargo-distconstrói arquivos por alvo- Scripts de instalação colocam binários no
PATH - GitHub Releases hospeda artefatos versionados
- Fluxo de trabalho acionado por tag mantém os lançamentos reproduzíveis
Análise Profunda
Canais de Distribuição
| Canal | Audiência |
|---|---|
cargo install | Desenvolvedores Rust |
| GitHub Releases | Usuários em geral |
| Homebrew / nix | Usuários avançados de macOS / Linux |
| crates.io | Descoberta de bibliotecas + crates binários |
Linkagem Estática para Portabilidade
rustup target add x86_64-unknown-linux-musl
cargo build --release --target x86_64-unknown-linux-muslBinários musl rodam na maioria das distribuições Linux sem problemas de versão glibc.
Assinando Lançamentos
- Assine checksums com
cosignou GPG - Publique
SHA256SUMSjunto com os arquivos - Documente os passos de verificação no README
Armadilhas
- Ferramentas de compilação cruzada ausentes - CI Linux não pode construir binários macOS sem ferramentas cruzadas. Correção: Use a matriz de compilação gerenciada do cargo-dist ou runners específicos da plataforma.
- Glibc vs musl - Contêineres Alpine precisam de alvos musl. Correção: Construa arquivos musl separados ou use linkagem estática.
- Símbolos de depuração removidos - Mais difícil de diagnosticar falhas de usuário. Correção: Envie símbolos de depuração divididos para seu rastreador de falhas.
- Arquivos de licença omitidos - Redistribuidores precisam da LICENSE incluída. Correção: Inclua LICENSE e NOTICE em cada arquivo.
- Versão não sincronizada - A tag diz v0.2.0 mas Cargo.toml diz 0.1.0. Correção: Automatize atualizações de versão no fluxo de trabalho de lançamento.
Alternativas
| Alternativa | Use Quando | Não Use Quando |
|---|---|---|
cross manual + CI | Controle total sobre os passos de compilação | Você quer geração de instalador também |
cargo-binstall | Usuários já usam binstall | Você precisa de scripts de instalação personalizados |
| Imagens Docker | Ferramentas CLI de servidor | Ferramentas de desenvolvimento de desktop |
FAQs
cargo-dist vs cross?
cargo-dist orquestra lançamentos, instaladores e CI. cross foca em compilação cruzada. Eles se complementam.
Como publico no crates.io?
cargo publish após a tag cargo dist. Usuários de binários podem cargo install mytool.
Fórmula Homebrew?
Aponte a fórmula para os arquivos tarball de lançamento do GitHub. Atualize SHA256 em cada atualização de versão.
Instaladores MSI do Windows?
cargo-dist suporta WiX/MSI através de suas opções de instalador. Habilite nos metadados de dist.
Binário universal macOS?
Construa ambos aarch64-apple-darwin e x86_64-apple-darwin, então use lipo ou envie arquivos separados.
SBOM para lançamentos?
Gere com cargo cyclonedx ou cargo auditable e anexe aos lançamentos para conformidade da cadeia de suprimentos.
Canais de pré-lançamento?
Publique tags beta (v0.2.0-beta.1) em um canal separado de pré-lançamento do GitHub.
Auto-atualização na CLI?
Verifique a API do GitHub Releases na inicialização. Opcional; respeite espelhos corporativos.
Versão mínima do Rust?
Defina rust-version em Cargo.toml e imponha na CI para que as compilações correspondam às expectativas do usuário.
Automação do changelog?
Use git-cliff ou release-plz para gerar notas a partir de commits convencionais.
Relacionados
- Completions de Shell e Páginas Man - agrupar completions
- Noções Básicas de CLI - layout do binário
- Melhores Práticas de CLI - semver para alterações de CLI
- Configuração e Env - configuração padrão em pacotes
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+.