Ritchie: Como criar uma fórmula do zero

February 13, 2020
Guillaume Falourd
Guillaume Falourd
Back-end Developer

Zupper curioso, sempre procurando impactar da melhor forma as pessoas ao seu redor.


O comando - rit create formula - cria a estrutura necessária para o usuário iniciar o desenvolvimento de uma nova fórmula na sua máquina. Antes de entrar em detalhes no passo a passo para criação de fórmula, é recomendado ler a documentação referente ao funcionamento do Ritchie.


Repositório de fórmulas

Para poder usar uma fórmula no CLI, é necessário ela se encontrar num repositório de fórmulas. Esse repositório precisa ter uma estrutura particular, contendo os seguintes elementos :

→ uma pasta tree, contendo o arquivo tree.json do repositório.

Esse arquivo tree.json vai conter a árvore dos comandos de todas as fórmulas do repositório. O CLI juntará as árvores de todo os repositórios que o usuário tem acesso na hora de executar os comandos.

→ um arquivo Makefile, localizado na raíz do projeto.

Esse arquivo Makefile precisa conter uma referência a todas as fórmulas do repositório, pois ele que permite gerar os arquivos necessários para testar a(s) fórmula(s) localmente.

→ as pastas contendo as fórmulas.

Cada uma dessas pastas vai conter o código executável e os arquivos referentes a uma fórmula.


Fórmulas

Para as fórmulas serem executáveis, é preciso ter alguns elementos configurados :

→ O tree.json do repositório onde a fórmula é implementada.

Para o CLI conhecer o comando executável da sua fórmula após juntar todas as árvores de comandos dos diversos repositórios.

→ O config.json na pasta da fórmula

Esse arquivo corresponde aos parâmetros de entrada (inputs) da fórmula, para o CLI saber quais informações ele precisará pedir para o usuário quando ele executará o comando no terminal a fim de processar a fórmula corretamente.

→ O binário contendo o código da fórmula.

Para o CLI baixar esse binário de acordo com o sistema operacional do computador do usuário e executar a fórmula através dos parâmetros de entrada que terão sido informados.


Comando de criação

Precisamos garantir que todos os elementos apresentados nos passos anteriores sejam configurados corretamente na criação da fórmula, e é isso que o comando rit create formula oferece para nós.


Quando esse comando é executado no terminal, um input é pedido para o usuário, o comando que executará a nova fórmula (idealmente seguindo o padrão rit + group + verb + noun).

A partir desse comando, serão criados e configurados todos os arquivos e a arquitetura comentados anteriormente.


Criação do repositório de fórmulas

A primeira vez que é criado uma fórmula localmente com o comando rit create formula, o código da fórmula avalia se já existe o repositório de formula, chamado ritchie-formulas-local na home da máquina do usuário.

→ Caso exista esse repositório, a nova fórmula será adicionada la.
→ Caso não exista, o repositório será criado antes de adicionar a nova fórmula.

Segue a estrutura do repositório com uma fórmula (dentro da pasta group).


Esse repositório vai sempre conter pelo menos a pasta tree, o makefile (principal), assim que a pasta da fórmula adicionada.

  • O tree.json da pasta tree será atualizado com a árvore do novo comando.
  • O makefile (principal) será atualizado com o caminho da pasta da nova fórmula

Observação: Além disso, existirá 2 arquivos shell (.sh) necessário para realizar os testes. Voltaremos a falar sobre eles mais para frente. Na parte Teste da fórmula.


Criação da pasta da fórmula

O comando também cria uma pasta referente a fórmula no repositório, de acordo com o input informado. Essa pasta terá a seguinte estrutura :


O conteúdo da pasta SRC é padronizado, e é sempre composto dos seguintes elementos :

→ O arquivo main.go

Esse arquivo é o executável da fórmula. Ele que inicia o código que será chamado pelo terminal. Por padrão, ele será criado na linguagem Go (mas nada impede usar uma outra linguagem) e conterá um exemplo padrão de implementação.

→ O arquivo Makefile (formula)

Esse arquivo é diferente do Makefile do repositório. O Makefile da fórmula permite gerar os binários da fórmula, enquanto o Makefile do repositório permite tanto gerar os binários de todas as formulas, quanto testar as formulas localmente.

→ O arquivo config.json

Esse arquivo conterá 3 inputs padrões como exemplo, para serem usados no arquivo main.go da fórmula.

→ A pasta PKG

Essa pasta será composta dos demais arquivos do código que, junto com o arquivo main.go permitirão a execução da fórmula. Por padrão, eles também serão criados na linguagem Go (mas nada impede usar uma outra linguagem).

Observação: Lembre-se de que você pode escrever sua fórmula usando qualquer linguagem que você esteja familiarizado (bash, python, golang, etc.).

Se você criou uma fórmula pela primeira vez, o repositório e a pasta da fórmula deverão seguir a mesma estrutura que abaixo :

Implementação da fórmula

Com o repositório de fórmulas criado na Home com a nova fórmula, é preciso de fato desenvolver a sua lógica.

É necessário alterar 3 lugares :

  • O config.json da fórmula para configurar os inputs.
  • O arquivo main.go
  • Os arquivos (códigos) da pasta PKG.

Caso foi usado uma outra linguagem, poderá ser necessário alterar mais arquivos.

Não altere o nome das pastas raízes da fórmula (group/verb/noun) sem atualizar o tree.json e o Makefile (principal) com os paths adequados.

Lembre que o tree.json e o Makefile (principal) já terão sido alterados com a execução do comando rit create formula. Consequentemente, não precisará alterar-los para conseguir testar a nova fórmula, mesmo após ter alterados os arquivos comentados acima.

Obs : Portanto, é possível realizar alguns ajustes nesses arquivos se tiver necessidade. 

Por exemplo : Se precisar alterar a mensagem descriptiva ou o helper do comando associado a sua fórmula, será necessário realizar essas modificações no tree.json.


Teste da fórmula

Note: O Ritchie precisa estar instalado no computador para poder testar as novas fórmulas pelo terminal.

Uma vez que a fórmula terá sido implementada, existem vários métodos de testar ela. 

Vamos apresentar 2 deles aqui.

→ Através de uma IDE (se estiver usando uma).


Você pode executar o arquivo principal da sua fórmula (ex : main.go) configurando variáveis do ambiente para representar seus parâmetros de entrada. A vantagem de usar uma IDE é de ter a possibilidade de debugar o código.
Obs : Pode se usar Goland para Go, IntelliJ ou Eclipse para Java ou Kotlin por exemplo

→ Através do terminal

Na criação da nova fórmula, foi informado no arquivo Makefile da raíz do repositório o path onde está localizada a fórmula, dentro do repositório.

Neste arquivo existe um comando test-local que permite criar o binário de uma ou mais fórmulas e colocar ela(s) na pasta temporária do Ritchie (.rit) localizada na home da máquina do usuário.

Observação : Esse comando test-local usa 2 outros arquivos na raíz do repositório : copy-bin-configs.sh e unzip-bin-configs.sh que permitem de fato extrair os binários e os config.json associados a cada fórmula que é testada.

Existe 2 maneiras de usar esse comando do Makefile

→ make test-local form={nome_formula} 

Para adicionar na pasta temporária .rit a fórmula que deseja testar em particular.

→ make test-local

Para adicionar todas as fórmulas do repositório na pasta temporária .rit

Após ter adicionado a fórmula no .rit através do Makefile (principal), será possível executar o comando associado a essa fórmula pelo terminal (o auto-completion não funcionará nesse caso).

Teste local da nova fórmula

Pasta .rit após uso do comando make test-local


Comunidade

✅ Parabéns, você criou sua primeira fórmula usando o Ritchie !

Para nós, o Ritchie é uma ferramenta comunitária em que cada indivíduo pode contribuir, compartilhando suas criações com o resto do mundo !

Sua fórmula pode ser útil para outras pessoas?

→ Compartilhe ela com a comunidade, abrindo uma pull request no repositório ritchie-formulas.

O que você achou deste conteúdo?
Open Code Newsletter
Seu cadastro foi efetuado com sucesso! Enviaremos as novidades no seu email.
Oops! Something went wrong while submitting the form.