Publicar uma crate no crates.io é o passo final para compartilhar seu código com a comunidade Rust. Nesta aula, você aprenderá a preparar sua crate, preencher metadados corretamente, usar versionamento semântico e executar o comando cargo publish com segurança.

Vamos explorar desde a configuração inicial até a publicação efetiva, incluindo como evitar erros comuns e garantir que sua crate seja útil e bem documentada para outros desenvolvedores.

crates.io

crates.io é o registro central de pacotes (crates) da linguagem Rust. É onde a maioria dos desenvolvedores publica suas bibliotecas e ferramentas, e de onde o Cargo baixa dependências. O site fornece uma interface para visualizar documentação, estatísticas de downloads e informações de versão.

Para publicar, você precisa criar uma conta no crates.io e autenticar-se via cargo login. O processo é simples, mas exige que você tenha um token de API, que pode ser gerado no painel da sua conta.

// Exemplo de código: nada aqui, mas é comum ver código de exemplo na documentação da crate.
// Veja como fica a estrutura de um projeto que será publicado:
// src/lib.rs
pub fn soma(a: i32, b: i32) -> i32 {
    a + b
}

Metadados no Cargo.toml

O arquivo Cargo.toml contém todos os metadados necessários para publicar sua crate. Campos como name, version, authors, description, license, repository e documentation são essenciais. O Cargo valida esses campos antes de publicar; por exemplo, a descrição é obrigatória e deve ter menos de 1000 caracteres.

Além disso, você pode configurar categorias e palavras-chave para facilitar a descoberta da sua crate. É importante também definir a edição do Rust (como edition = "2021") para garantir compatibilidade.

[package]
name = "minha_crate"
version = "0.1.0"
edition = "2021"
description = "Uma crate de exemplo para demonstração"
license = "MIT"
authors = ["Seu Nome <email@exemplo.com>"]
repository = "https://github.com/seuusuario/minha_crate"
documentation = "https://docs.rs/minha_crate"
keywords = ["exemplo", "demonstração"]
categories = ["algorithms"]

Versionamento semântico

O versionamento semântico (SemVer) é um padrão para atribuir números de versão que comunicam mudanças na API. A versão é formada por MAJOR.MINOR.PATCH, onde MAJOR indica mudanças incompatíveis, MINOR adiciona funcionalidades de forma compatível, e PATCH corrige bugs sem alterar a API.

No Rust, o Cargo respeita o SemVer ao resolver dependências: por exemplo, uma dependência ^1.2.3 aceita qualquer versão compatível até antes da próxima MAJOR. Ao publicar, você deve escolher a versão correta para não quebrar usuários.

// Exemplo de versão no Cargo.toml
version = "0.2.0" // Mudança menor com novas funcionalidades
// version = "1.0.0" // Primeira versão estável
// version = "1.2.1" // Correção de bug sem mudanças na API

cargo publish

O comando cargo publish é responsável por enviar sua crate para o crates.io. Antes de publicar, é recomendável executar cargo package para gerar o pacote e verificar se tudo está correto. O Cargo também compila e testa sua crate antes de publicar, garantindo que ela está funcional.

Durante a publicação, o Cargo cria um arquivo .crate contendo todos os arquivos necessários. É importante ter um arquivo README.md e documentação via cargo doc, pois eles são exibidos na página da crate.

# Comandos no terminal (não é código Rust)
cargo login
cargo package --list
cargo publish

Boas práticas

  • Verifique se sua crate tem documentação completa (cargo doc).
  • Inclua um README claro com exemplos de uso.
  • Teste sua crate em diferentes versões do Rust (use rustup).
  • Não publique versões com código incompleto; use versões 0.x.y para desenvolvimento inicial.
  • Considere usar cargo semver-checks para verificar compatibilidade.

Referências

Exercícios

  1. Crie um projeto Cargo chamado minha_crate com versão 0.1.0 e preencha os metadados obrigatórios (descrição, licença, autores).

    2. ✓ Resposta: Execute cargo new minha_crate. Edite o Cargo.toml com:
    [package]
name = "minha_crate"
version = "0.1.0"
edition = "2021"
description = "Uma crate de exemplo"
license = "MIT"
authors = ["Seu Nome"]
  2. Explique a diferença entre versões 0.1.0, 0.2.0 e 1.0.0 em termos de SemVer.

    3. ✓ Resposta: 0.1.0 indica uma versão inicial instável; 0.2.0 adiciona funcionalidades sem quebrar a API (mas ainda instável); 1.0.0 é a primeira versão estável, indicando que a API é estável e mudanças incompatíveis só ocorrem na próxima MAJOR.
  3. O que o comando cargo publish faz além de enviar o pacote?

    4. ✓ Resposta: Ele valida o pacote, compila e roda os testes, gera a documentação (se configurada) e, após o envio, torna a crate disponível no crates.io.
  4. Como você verifica se sua crate está pronta para publicação sem publicar?

    5. ✓ Resposta: Use cargo package para gerar o pacote e cargo package --list para listar os arquivos incluídos. Também rode cargo test e cargo doc.
  5. Qual é a finalidade do campo documentation no Cargo.toml?

    6. ✓ Resposta: Ele fornece a URL da documentação gerada pelo cargo doc (geralmente em docs.rs), que é exibida na página da crate no crates.io.

Observações finais

Publicar uma crate é um marco importante. Lembre-se de que uma vez publicada, uma versão não pode ser alterada; apenas novas versões podem ser lançadas. Portanto, teste exaustivamente antes de publicar. Além disso, mantenha sua crate atualizada e responda a issues para construir uma boa reputação na comunidade.