O arquivo lib.rs
é o entry-point convencional de bibliotecas escritas em Rust.
Todos os itens (funções, estruturas, enumerações, traits, etc) exportados nesse entry-point podem ser acessados por outras Crates que dependem da sua biblioteca.
Quando uma Crate utiliza outra Crate como biblioteca (isso se chama dependência), somente os itens públicos de lib.rs
podem ser acessados. Como, por padrão, os itens de um módulo em Rust são privados, somente o que é explicitamente marcado como pub
em lib.rs
é visível para os dependentes downstream. Itens privados também não aparecem na documentação gerada automaticamente em docs.rs.
Uma Crate pode ser um binário ou uma biblioteca. Forma-se uma “árvore de dependências” quando Crates começam a depender de outras Crates. O gerenciamento de dependências é feito pelo Cargo.
Geralmente bibliotecas open-source são publicadas no crates.io, mas esse não é o único meio de disponibilizar uma Crate. Além de depender de bibliotecas publicadas no crates.io, é possível também especificar repositórios Git, projetos locais ou em outros registries como library sources. Veja mais aqui.
Para mais detalhes sobre bibliotecas e sobre o Cargo, o Livro Oficial do Cargo é uma boa referência.
Por padrão, quando você utiliza o comando cargo new
para criar um projeto, cria-se um arquivo main.rs
no diretório src
. Isso indica que o projeto é uma Crate executável (também chamada de binary crate). O arquivo main.rs
contém a função main
que é executada quando alguém inicia seu binário.
Já quando se utiliza a flag --lib
para gerar um novo projeto, cria-se, ao invés de main.rs
, lib.rs
, o que define o projeto como uma biblioteca. O lib.rs
é, reiterando, o entry-point dos itens exportados pela biblioteca.
O Rust optou por estabelecer convenções bem definidas, de modo que, por padrão, todo projeto com um lib.rs
é considerado uma biblioteca e todo projeto com um main.rs
é considerado um executável. Essas convenções podem ser alteradas, mas isso é raramente necessário.
Se necessário, um binário e um executável podem coexistir numa mesma Crate.
É possível também criar um Workspace, ideal para monorepos, mas aí já vai além do escopo desta pergunta.