This article was originally published on Pragmatic Perl

Uma estratégia para resolver este tipo de prolema é construir seu próprio repositório do CPAN, que conterá apenas as versões dos módulos que você deseja. Dessa forma você pode utilizar o construtor do CPAN para instalar módulos a partir do seu próprio repositório sem ficar exposto ao CPAN público.

Através dos anos eu construí vários repositórios personalizados do CPAN utilizando ferramentas como CPAN::Mini e CPAN::Site. Mas eles sempre me pareceram desajeitados e nunca estive satisfeito com eles. A alguns anos atrás, fui contratado por um cliente para construir outro repositório personalizado do CPAN. Mas desta vez eu tive a oportunidade de começar a partir do zero. O resultado disso tudo é o projeto Pinto.

Pinto é uma ferramenta robusta para criar e manipular repositórios CPAN personalizados. Ele possui várias características poderosas que irão, de forma segura, lhe ajudar a gerenciar todos os módulos Perl cuja sua aplicação seja dependente. Este tutorial irá lhe ajudar a criar um repositório CPAN personalizado com o Pinto e ao mesmo tempo, demonstrar algumas de suas características.

Instalando o Pinto

O módulo Pinto está disponível pelo CPAN e pode ser instalado como qualquer outro módulo utilizando o cpan ou o cpanm. Porém o projeto Pinto é mais uma aplicação do que uma biblioteca. É uma ferramenta que você utiliza para gerenciar o código de suas aplicações, isso sem se tornar parte de sua aplicação. Portanto eu recomendo instalar o Pinto como um projeto independente através desses dois comandos:

curl -L http://getpinto.stratopan.com | bash
source ~/opt/local/pinto/etc/bashrc

Isso irá instalar o Pinto em ~/opt/local/pinto e adicionará os diretórios necessários em seu PATH e MANPATH. Todo o conteúdo é localizado, isso significa que ao instalar o Pinto não irá afetar o seu ambiente de desenvolvimento, e da mesma forma, o seu ambiente de desenvolvimento também não irá afetar o Pinto.

Explorando o Projeto Pinto

Assim como quando explora uma ferramenta nova, a primeira coisa que você deverá saber é como buscar ajuda:

pinto commands            # Apresenta uma lista de comandos disponíveis
pinto help <COMMAND>      # Apresenta um sumário de opções e argumentos para o <COMMAND>
pinto manual <COMMAND>    # Apresenta o manual completo para <COMMAND>

O projeto também é instalado com outra documentação, incluindo um tutorial e um guia rápido para referências. Você pode acessar esses documentos através dos comandos:

man Pinto::Manual::Introduction  # Explica os conceitos básicos do projeto
man Pinto::Manual::Installing    # Sugestões para a instalação
man Pinto::Manual::Tutorial      # Um guia narrativo pelo projeto
man Pinto::Manual::QuickStart    # Um sumário de comandos comuns

Criando o Repositório

O primeiro passo ao utilizar o projeto Pinto é criar um repositório através do comando init:

pinto -r ~/repo init

O comando criará um novo repositório no diretório ~/repo. Se o diretório não existir, ele será criado para você. Se ele já existir então deve estar vazio.

A opção -r (ou --root) especifica aonde o repositório está. Isso é necessário para todo comando. Mas se você se cansar de digitar isso sempre, você poderá configurar a variável de ambiente PINTO_REPOSITORY_ROOT para que referencie o seu repositório, dessa forma você pode omitir o -r.

Inspecionando O Repositório

Agora que você já possui um repositório, vamos ver o que há por dentro. Para ver o seu conteúdo, use o comando list:

pinto -r ~/repo list

A partir desse ponto, a listagem retornará vazia porque não há nada no repositório. Mas você irá utilizar o comando list várias vezes durante o tutorial.

Adicioando Módulos do CPAN

Suponha que você esteja trabalhando em uma aplicação My-App que contém um módulo My::App, e que dependa do módulo URI. Você pode trazer o módulo URI para o seu repositório utilizando o comando pull:

pinto -r ~/repo pull URI

Você será questionado a escrever uma mensagem que descreva o motivo de tal mudança em seu repositório. No topo da mensagem inclui uma mensagem simples que você poderá editar. O rodapé da mensagem mostrará exatamente quais módulos foram adicionados. Salve o arquivo e feche o editor de texto quando terminar.

Agora você deverá ter o módulo URI em seu repositório Pinto. Então vamos ver o que realmente temos. Novamente use o comando list para ver o conteúdo do repositório:

pinto -r ~/repo list

Dessa vez a listagem irá se parecer com isso:

rf  URI                            1.60  GAAS/URI-1.60.tar.gz
rf  URI::Escape                    3.31  GAAS/URI-1.60.tar.gz
rf  URI::Heuristic                 4.20  GAAS/URI-1.60.tar.gz
...

Você pode observar que o módulo URI foi adicionado ao repositório, assim como os requisitos para o URI, e todos os requisitos dos requisitos, e assim por diante.

Adicionando Módulos Particulares

Agora suponha que você terminou o seu trabalho no módulo My-App e você está pronto para liberar a primeira versão. Utilizando sua ferramenta preferida de instalação (e.g. ExUtils::MakeMaker, Module::Builder, Module::Install, etc.) você cria o pacote da sua distribuição como My-App-1.0.tar.gz. Agora você pode colocar a distribuição no repositório Pinto com o comando add:

$> pinto -r ~/repo add path/to/My-App-1.0.tar.gz

Novamente será necessário descrever em uma mensagem as mudanças realizadas. Agora, quando você lista o conteúdo do repositório, verá o módulo My::App mostrando você como autor da distribuição.

rl  My::App                         1.0  JEFF/My-App-1.0.tar.gz
rf  URI                            1.60  GAAS/URI-1.60.tar.gz
rf  URI::Escape                    3.31  GAAS/URI-1.60.tar.gz
rf  URI::Heuristic                 4.20  GAAS/URI-1.60.tar.gz
...

Instalando Módulos

Agora que você já possui seus módulos dentro do repositório, o próximo passo será construir e instalar os módulos em algum outro lugar. Por baixo dos panos o repositório do Pinto é organizado da mesma forma que o repositório do CPAN, então ele é totalmente compatível com o cpanm e qualquer outro instalador Perl. Tudo o que você precisa fazer é apontar o instalador para o seu novo repositório:

cpanm --mirror file://$HOME/repo --mirror-only My::App

Isso irá construir e instalar o módulo My::App utilizando *somente* os módulos em seu repositório Pinto. Isso significa que você terá exatamente as mesmas versões dos módulos toda vez que realizar a instalação, mesmo que os módulos sejam removidos ou atualizados no CPAN.

Com o cpanm, a opção --mirror-only é importante por que previne o cpanm de realizar buscas nos CPAN quando não encontra algum módulo em seu repositório. Quando isso acontece, normalmente significa que algumas distribuições no repositório não possuem todas as dependências devidamente descritas em seu arquivo META. Para corrigir o problema, apenas utilize o comando pull para buscar os módulos faltantes.

Atualizando Módulos

Suponha que diversas semanas se passaram desde que você lançou a primeira versão do My-App e agora o módulo URI está na versão 1.62, disponível pelo CPAN. Ele agora possui algumas correções que você gostaria de poder ter. Novamente, podemos trazer o novo módulo ao repositório utilizando o comando pull. Mas já que o seu repositório já possui uma versão do módulo URI, você agora deve indicar que quer uma versão nova especificando a versão mínima que você deseja:

pinto -r ~/repo pull URI~1.62

Se observar agora na listagem dos módulos irá ver que a nova versão do URI já está presente:

rl  My::App                         1.0  JEFF/My-App-1.0.tar.gz
rf  URI                            1.62  GAAS/URI-1.62.tar.gz
rf  URI::Escape                    3.38  GAAS/URI-1.62.tar.gz
rf  URI::Heuristic                 4.20  GAAS/URI-1.62.tar.gz
...

Se a nova versão do URI exigir uma nova versão de algum outro módulo adicional, estes também serão atualizados. E quando instalar o My::App, você terá a versão 1.62.

Trabalhando Com Pilhas (Stacks)

Até o momento nós tratamos o repositório como uma fonte de recurso única. Então quando atualizamos o módulo URI na última seção, afetamos todas as pessoas e aplicações que possam estar utilizando do mesmo repositório. Mas esse tipo de impacto abrangente é indesejado. Você gostaria de realizar mudanças de forma isolada e testá-las antes de forçar as outras pessoas a atualizar. É justamente para isso que as pilhas servem.

Todo repositório do tipo CPAN possui um índice que mapeia a última versão de cada módulo ao arquivo que a contém. Normalmente há apenas um índice por repositório. Diferentemente, em um repositório Pinto pode haver diferentes índices. Cada índice é chamado stack (ou pilha). Isso lhe permite criar diferentes stacks de dependências dentro de um único repositório. Então você pode ter um stack "desenvolvimento" e um stack "produção", ou um stack "perl-5.8" e outro "perl-5.16". Toda vez que você atualiza ou adiciona um módulo, irá afetar apenas um único stack.

Mas antes de seguir a diante, você precisa saber sobre o stack padrão. Para a maioria das aplicações, o nome do stack é um parâmetro opcional. Então se você não especificar um stack, então o comando é aplicado para qualquer stack marcado como padrão.

Em qualquer repositório, não irá ocorrer mais de um stack padrão. Quando criamos um repositório, um stack chamado "master" também é criado e então marcado como padrão. Você pode alterar o stack padrão ou mudar o seu nome, mas eu não mexeria nisso. Apenas lembre-se que "master" é o nome do stack criado com o novo repositório.

Criando Uma Pilha

Suponha que seu repositório contenha a versão 1.60 do módulo URI mas a versão 1.62 foi liberada no CPAN, como descrevemos antes. Você quer tentar atualizar o seu repositório, mas dessa vez irá realizar isso em um stack separado.

Até o momento, tudo que você adicionou no repositório foi para o stack "master". Então nós iremos agora criar um clone desse stack utilizando o comando copy:

pinto -r ~/repo copy master uri_upgrade

Esse comando criará um novo stack chamado "uri_upgrade". Se você quer ver o conteúdo apenas utilize o comando list com a opção "--stack":

pinto -r ~/repo list --stack uri_upgrade

A listagem deverá ser idêntica ao "master":

rl  My::App                         1.0  JEFF/My-App-1.0.tar.gz
rf  URI                            1.60  GAAS/URI-1.60.tar.gz
...

Atualizando uma Pilha

Agora que você já possui um stack separado você pode tetar atualizar o módulo URI. Assim como antes, você utilizará o comando pull. Mas desta vez, você dirá que utilize o stack "uri_upgrade":

pinto -r ~/repo pull --stack uri_upgrade URI~1.62

Nós podemos comparar o "master" e o "uri_upgrade" utilizando o comando diff:

pinto -r ~/repo diff master uri_upgrade

+rf URI                                              1.62 GAAS/URI-1.62.tar.gz
+rf URI::Escape                                      3.31 GAAS/URI-1.62.tar.gz
+rf URI::Heuristic                                   4.20 GAAS/URI-1.62.tar.gz
...
-rf URI                                              1.60 GAAS/URI-1.60.tar.gz
-rf URI::Escape                                      3.31 GAAS/URI-1.60.tar.gz
-rf URI::Heuristic                                   4.20 GAAS/URI-1.60.tar.gz

A saída é similar ao comando diff(1). Registros começando por "+" foram adicionados e aqueles que começam com "-" foram removidos. Você pode notar que os módulos da distribuição URI-1.60 foram substituídos por módulos da distribuição URI-1.62.

Instalando a Partir da Pilha

Uma vez que tenha novos módulos na stack "uri_upgrade", você pode tentar construir sua aplicação ao apontar o cpanm para aquele stack. Cada stack é nada mais do que um subdiretório dentro do repositório, então tudo o que você precisa fazer é:

cpanm --mirror file://$HOME/repo/stacks/uri_upgrade --mirror-only My::App

Se todos os testes passaram, então você agora pode atualizar o módulo URI para a versão 1.62 na stack "master", utilizando o comando pull. Como "master" é o stack padrão, você pode omitir o parâmetro "--stack":

pinto -r ~/repo pull URI~1.62

Trabalhando com Fixadores (Pins)

stacks são ótimas formas de você testar o efeito que ocorre com mudanças nas dependências de suas aplicações. Mas e se os testes não passarem? Se o problema reside dentro do My-App você pode rapidamente corrigi-lo, e em seguida lançar a versão 2.0 do My-App, e então, prosseguir com a atualização do URI no stack "master".

Mas e se a origem do bug está no URI então irá levar um bom tempo até que o My-App seja corrigido, e você agora tem um problema. Você não que que outra pessoa qualquer atualize o módulo URI ou que ele seja atualizado inadvertidamente para satisfazer algum outro requisito que o My-App possa ter. Até que você saiba que o problema fora corrigido, você precisará impedir que o módulo URI seja atualizado. É para isso que os pins servem.

Fixando um Módulo

Quando você utiliza um pin (fixador) em um módulo, aquela versão do módulo é obrigada a se manter no stack. Qualquer tentativa de atualizar o módulo (tanto diretamente quanto indiretamente) irá falhar. Para fixar um módulo, utilize o comando pin:

pinto -r ~/repo pin URI

Se vocẽ observar a listagem do stack "master" novamente, irá observar algo como isso:

...
rl  My::App                         1.0  JEFF/My-App-1.0.tar.gz
rf! URI                            1.60  GAAS/URI-1.60.tar.gz
rf! URI::Escape                    3.31  GAAS/URI-1.60.tar.gz
...

O símbolo "!" próximo ao início do registro indica que o módulo está fixado. Se alguém tentar atualizar o módulo URI ou adicionar uma distribuição que exige uma versão mais nova do módulo URI, então você receberá um aviso, não sendo possível adicionar a nova distribuição. Note que todo módulo na distribuição URI-1.60 está fixado, então é impossível atualizar parcialmente a distribuição (essa situação pode acontecer quando um módulo entra em uma distribuição diferente).

Desafixando um Módulo

Após um certo tempo, suponha que você resolveu o problema no módulo My-App ou então uma nova versão do URI foi lançada, corrigindo o bug. Nessa situação, você agora já pode desafixar o módulo URI da stack através do comando unpin:

pinto -r ~/repo unpin URI

A partir de agora você está livre para atualizar o módulo URI para a última versão. Da mesma forma que acontece quando você fixa um módulo, ao desafixá-lo, você libera também todos os módulos da distribuição.

Utilizando Fixadores e Pilhas ao Mesmo Tempo

As pilhas e os fixadores (pins e stacks) são comumente utilizadas juntas para ajudar a gerenciar mudanças em seu ciclo de desenvolvimento. Por exemplo você pode criar uma stack chamada "prod" que contém suas dependências de confiança. Ao mesmo tempo você pode ter também uma stack chamada "dev" que contém módulos experimentais para seu próximo lançamento. Inicialmente, a stack "dev" é apenas uma cópia da "prod".

Ao longo do processo de desenvolvimento, você pode atualizar ou adicionar vários módulos na pilha "dev". Se um módulo atualizado quebrar sua aplicação, então você pode colocar um pin naquele módulo, dentro da stack "prod", sinalizando que aquele módulo não deve ser atualizado.

Fixadores e Adendos (Patches)

Em certas situações você pode se deparar com uma nova versão de uma distribuição no CPAN com um bug cujo autor é incapaz ou impossibilitado de corrigir. Nesta situação, você pode decidir realizar um patch local para aquela distribuição.

Então suponha que você realizou um fork do código do módulo URI e criou uma versão local chamada URI-1.60_PATCHED.tar.gz. Você pode agora adicioná-la ao seu repositório utilizando o comando add:

pinto -r ~/repo add path/to/URI-1.60_PATCHED.tar.gz

Nesta situação é aconselhável fixar o módulo, já que você não gostaria de atualizar o módulo até que tenha certeza de que uma nova versão do CPAN inclua o patch ou então o autor corrija o problema.

pinto -r ~/repo pin URI

Quando o autor do URI liberar a versão 1.62 você irá querer testá-la antes de decidir se pode desafixar da sua versão local. Assim como antes, isso pode ser realizado clonando o stack através do comando clone. Desta vez vamos chamar o stack de "trial":

pinto -r ~/repo copy master trial

Mas antes de você poder atualizar o URI no stack "trial", você deverá desafixá-lo:

pinto -r ~/repo unpin --stack trial URI

Agora você pode proceder com a atualização do URI na stack e tentar construir a aplicação My::App, dessa forma:

pinto -r ~/repo pull --stack trial URI~1.62
cpanm --mirror file://$HOME/repo/stacks/trial --mirror-only My::App

Se tudo der certo, remova o pin do stack "master" e puxe a nova versão do URI de volta.

pinto -r ~/repo unpin URI
pinto -r ~/repo pull URI~1.62

Revisando o Histórico de Mudanças

Como você deve ter notado, cada comando que altera o estado de um stack exige uma mensagem que o descreva. Você pode revisar essas mensagens através do comando log:

pinto -r ~/repo log

Isso deve retornar algo do tipo:

revision 4a62d7ce-245c-45d4-89f8-987080a90112
Date: Mar 15, 2013 1:58:05 PM
User: jeff

     Pin GAAS/URI-1.59.tar.gz

     Pinning URI because it is not causes our foo.t script to fail

revision 4a62d7ce-245c-45d4-89f8-987080a90112
Date: Mar 15, 2013 1:58:05 PM
User: jeff

     Pull GAAS/URI-1.59.tar.gz

     URI is required for HTTP support in our application

...

O cabeçalho de cada mensagem mostra quem fez a mudança e quando ela aconteceu. é possível ver também um identificador único, similar ao SHA-1 do Git. Você pode usar esses identificadores para ver a diferença entre as revisões ou para retornar o stack para um estado anterior (isso na verdade ainda não está implementado).

Conclusões

Neste tutorial, você viu os comandos básicos para criar um repositório Pinto e como adicionar módulos a ele. Você viu também como utilizar os stacks e os pins para gerenciar as sua dependências frente a alguns problemas e obstáculos no desenvolvimento.

Cada comando possui várias opções que não foram discutidas neste tutorial, e há ainda outros comandos que não foram mencionados aqui. Então eu o encorajo a explorar o manual de cada comando e aprender mais.