Lição 40: Publicação e Crates.io (Distribuição de Peças)

1. Narrativa

O mecha Æther tem componentes tão bem projetados que outras academias querem usá-los. A publicação de crates é como enviar peças para o armazém central — crates.io — onde qualquer piloto do mundo pode baixá-las. Mas antes de publicar, é preciso garantir que o manifesto (Cargo.toml) está correto e a versão segue as regras de SemVer.

2. Conceito

Publicação em Rust envolve preparar o pacote corretamente:

• Cargo.toml: Manifesto com nome, versão, edição, dependências e metadados
• SemVer (Versionamento Semântico): MAJOR.MINOR.PATCH
  • MAJOR: mudanças incompatíveis (breaking changes)
  • MINOR: novas funcionalidades compatíveis
  • PATCH: correções de bugs compatíveis
• cargo publish: Publica no crates.io
• Metadados obrigatórios: description, license (ou license-file)
• README.md: Documentação principal exibida no crates.io

3. Requisitos

• Implementar funções de validação de metadados para publicação
• Manipular versões semânticas (incrementar patch, minor, major)
• Gerar conteúdo de Cargo.toml formatado corretamente
• Validar nomes de peças/crates

4. Design de Dados

graph LR
    A[Fonte: src/lib.rs] --> B[Cargo.toml]
    B --> C[cargo publish]
    C --> D[crates.io]
    D --> E[Outros projetos]
    E --> F[cargo add peca]

5. Diagrama de Fluxo

flowchart TD
    A[Preparar Cargo.toml] --> B{Metadados ok?}
    B -->|Sim| C{Versão válida?}
    B -->|Não| D[Corrigir metadados]
    C -->|Sim| E{Nome disponível?}
    C -->|Não| F[Corrigir versão]
    E -->|Sim| G[cargo publish]
    E -->|Não| H[Escolher outro nome]
    G --> I[Publicado no crates.io!]

6. Funções

Função	Descrição
nome_peca_valido	Verifica nome com letras minúsculas, números, hifens e underscores (2-64 chars)
incrementar_patch	Incrementa versão PATCH (bug fix)
incrementar_minor	Incrementa versão MINOR (nova feature)
incrementar_major	Incrementa versão MAJOR (breaking change)
formatar_versao	Formata versão como "MAJOR.MINOR.PATCH"
dependencia_existe	Verifica se dependência já está na lista
gerar_cargo_toml	Gera conteúdo de Cargo.toml
validar_metadados	Valida nome, versão e descrição para publicação

7. Exemplo

let versao = incrementar_minor(1, 2, 3);
assert_eq!(formatar_versao(versao.0, versao.1, versao.2), "1.3.0");

let toml = gerar_cargo_toml("mecha-lib", "0.1.0", "Biblioteca de mechas");
assert!(toml.contains("edition = \"2024\""));

8. Missão

1. Implementar nome_peca_valido validando formato e comprimento
2. Implementar incrementar_patch somando 1 ao patch
3. Implementar incrementar_minor incrementando minor e zerando patch
4. Implementar incrementar_major incrementando major e zerando minor/patch
5. Implementar formatar_versao usando format!
6. Implementar dependencia_existe buscando na lista
7. Implementar gerar_cargo_toml gerando o TOML formatado
8. Implementar validar_metadados verificando campos não vazios

9. Como Executar

cargo build
cargo test
cargo clippy -- -D warnings
cargo fmt --check

10. Dicas

• Nomes de crates no crates.io são exclusivos — escolha com cuidado
• Use cargo publish --dry-run para testar sem publicar
• Cargo.toml aceita keywords e categories para melhorar descoberta
• SemVer é obrigatório — versão 0.x.y indica API instável
• Adicione documentation = "..." para link para docs.rs