Escrever uma biblioteca
Do primeiro arquivo ao pacote publicado — estrutura, contrato, versão, testes e registro.
Uma biblioteca é um projeto com uma diferença que muda tudo: outra pessoa vai depender dela. O que num programa é detalhe interno — o nome de uma ação, a ordem de um parâmetro, o formato de um retorno — vira promessa.
Esta seção é o caminho inteiro, na ordem em que ele acontece.
1. Estrutura
o esqueleto, o forge.toml e onde cada coisa mora
2. O contrato
o que o relay promete, e o que quebra quem depende de você
3. Testes de biblioteca
testar pelo nome público, e não pelo caminho interno
4. Versão
semver, o que cada número significa, e como o resolvedor lê
5. Publicar
empacotar, o registro estático, e o que vai dentro do tarball
6. Manter
depreciar sem quebrar, e o que fazer numa mudança incompatível
Em trinta segundos#
dataforge init minha-lib && cd minha-lib
# escreva src/main.df, com 'relay' no fim
dataforge check .
dataforge test tests/
dataforge pack # gera dist/minha-lib-1.0.0.tar.gz
dataforge publish --registry=../registroAs quatro bibliotecas deste repositório#
Elas existem como referência de quem for escrever a sua — e como prova de que o gerenciador funciona ponta a ponta:
| Pacote | O que faz |
|---|---|
| `validador` | CPF, CNPJ, e-mail, CEP e esquema de formulário |
| `tabela` | saída tabular para terminal |
| `datas` | datas em pt-BR, com feriados |
| `cofre` | configuração em camadas |
As quatro somam 46 testes, e o código de cada uma é curto o bastante para ser lido inteiro.
O que distingue uma biblioteca de um programa#
| Programa | Biblioteca | |
|---|---|---|
| quem decide a entrada | você | quem usa |
| renomear uma ação | um grep e pronto | quebra todo mundo |
| erro sem tratamento | aparece para você | aparece na aplicação de outra pessoa |
| efeito no topo do arquivo | aceitável | inaceitável — roda no adopt de quem importa |
| dependência nova | sua escolha | vira dependência de todos os seus usuários |
| o teste | prova que funciona | é a documentação do contrato |