Perl package guidelines (Português)

Status de tradução:
Esse artigo é uma tradução de
Perl package guidelines
. Data da última tradução: 2018-11-01. Você pode ajudar a sincronizar a tradução, se houver
alterações
na versão em inglês.
Diretrizes de pacotes do Arch
32-bit
–
CLR
–
CMake
–
Cross
–
DKMS
–
Eclipse
–
Electron
–
Fonte
–
Free Pascal
–
GNOME
–
Go
–
Haskell
–
Java
–
KDE
–
Kernel
–
Lisp
–
Meson
–
MinGW
–
Node.js
–
Nonfree
–
OCaml
–
Perl
–
PHP
–
Python
–
R
–
Ruby
–
Rust
–
Shell
–
VCS
–
Web
–
Wine
Este documento cobre a criação de
PKGBUILDs
para módulos perl distribuídos pelo CPAN, a Comprehensive Perl Authors Network. Este documento tem como público-alvo aqueles que deseja empacotar módulos perl. Para as políticas do Perl, veja
Políticas do Perl
.
Convenções de empacotamento do Arch Linux
As seguintes convenções devem ser usadas para manter os pacotes de módulos perl consistentes. Esta seção serve como uma introdução ao conceito de empacotamento de perl, do ponto de vista do Arch Linux; isto é, gerenciamento de pacotes e administração do sistema. Em um esforço para agradar o leitor
TL;DR
, o material mais fácil e/ou mais popular está no topo.
Nomes de pacotes
Para módulos, o nome do pacote deve começar com
perl-
e o resto do nome deve ser construído a partir do nome do módulo, convertendo-o em letras minúsculas e, em seguida, substituindo os dois pontos por hífenes. Por exemplo, o nome do pacote correspondente a
HTML::Parser
será
perl-html-parser
. Os aplicativos Perl devem ter o mesmo nome do aplicativo, mas em letras minúsculas.
Colocação de arquivos no pacote
Os pacotes Perl devem instalar os arquivos do módulo em
/usr/lib/perl5/$version/vendor_perl/
(use
perl -V:vendorarch
em scripts), ou
/usr/share/perl5/vendor_perl/
. Isso é feito configurando o parâmetro de linha de comando
INSTALLDIRS
para
vendor
como mostrado abaixo. Nenhum arquivo deve ser armazenado em
/usr/lib/perl5/$version/site_perl/
, pois esse diretório é reservado para uso pelo administrador do sistema para instalar pacotes Perl fora do sistema de gerenciamento de pacotes. Quando um usuário instala módulos em todo o sistema usando o shell
cpan
, os módulos acabam nos subdiretórios site-perl.
Os arquivos
perllocal.pod
e
.packlist
também não devem estar presentes; isso é cuidado pelo exemplo de PKGBUILD descrito abaixo.
Arquitetura
Na maioria dos casos, o vetor
arch
deve conter
'any'
porque a maioria dos pacotes Perl são independentes de arquitetura. Os módulos XS são compilados em bibliotecas carregadas dinamicamente (arquivos .so) e devem explicitamente configurar sua arquitetura para
('x86_64')
para indicar que eles são dependentes da arquitetura quando construídos. Um módulo XS geralmente contém um ou mais arquivos .xs que geram dinamicamente arquivos .c.
Automação
Um plugin para o shell CPAN de segunda geração, CPANPLUS, está disponível no pacote perl-cpanplus-dist-arch do repo da comunidade. Este plugin empacota distribuições rapidamente quando elas são instaladas pelo CPANPLUS. A documentação on-line está disponível em
https://metacpan.org/release/CPANPLUS-Dist-Arch
Exemplos de PKGBUILD
Um exemplo de PKGBUILD pode ser encontrado em
[1]
.
Os dois exemplos a seguir do PKGBUILD usam técnicas, introduzidas nesta página, destinadas a tornar um PKGBUILD mais resiliente a problemas mais sofisticados. Como existem dois estilos de scripts de construção, há dois exemplos de PKGBUILDS. O primeiro PKGBUILD é um exemplo de como empacotar uma distribuição que usa
Makefile.PL
. O segundo PKGBUILD pode ser usado como ponto de partida para uma distribuição que usa
Build.PL
.
PKGBUILD
# Contributor: Your Name <youremail@domain.com>
pkgname=perl-foo-bar
pkgver=1.0
pkgrel=1
pkgdesc='This packages the Foo-Bar distribution, containing the Foo::Bar module!'
_dist=Foo-Bar
arch=('any')
url="https://metacpan.org/release/$_dist"
license=('GPL' 'PerlArtistic')
depends=(perl)
options=('!emptydirs' purge)
source=("http://search.cpan.org/CPAN/authors/id/BAZ/$_dist-$pkgver.tar.gz")
md5sums=(...)

build() {
  cd "$srcdir/$_dist-$pkgver"
  unset PERL5LIB PERL_MM_OPT PERL_LOCAL_LIB_ROOT
  export PERL_MM_USE_DEFAULT=1 PERL_AUTOINSTALL=--skipdeps
  /usr/bin/perl Makefile.PL
  make
}

check() {
  cd "$srcdir/$_dist-$pkgver"
  unset PERL5LIB PERL_MM_OPT PERL_LOCAL_LIB_ROOT
  export PERL_MM_USE_DEFAULT=1
  make test
}

package() {
  cd "$srcdir/$_dist-$pkgver"
  unset PERL5LIB PERL_MM_OPT PERL_LOCAL_LIB_ROOT
  make install INSTALLDIRS=vendor DESTDIR="$pkgdir"
}
PKGBUILD
# Contributor: Your Name <youremail@domain.com>
pkgname=perl-foo-bar
pkgver=1.0
pkgrel=1
pkgdesc='This packages the Foo-Bar distribution, containing the Foo::Bar module!'
_dist=Foo-Bar
arch=('any')
url="https://metacpan.org/release/$_dist"
license=('GPL' 'PerlArtistic')
depends=(perl)
options=('!emptydirs' purge)
source=("http://search.cpan.org/CPAN/authors/id/BAZ/$_dist-$pkgver.tar.gz")
md5sums=(...)

build() {
  cd "$srcdir/$_dist-$pkgver"
  unset PERL5LIB PERL_MM_OPT PERL_MB_OPT PERL_LOCAL_LIB_ROOT
  export PERL_MM_USE_DEFAULT=1 MODULEBUILDRC=/dev/null
  /usr/bin/perl Build.PL
  ./Build
}

check() {
  cd "$srcdir/$_dist-$pkgver"
  unset PERL5LIB PERL_MM_OPT PERL_MB_OPT PERL_LOCAL_LIB_ROOT
  export PERL_MM_USE_DEFAULT=1
  ./Build test
}

package() {
  cd "$srcdir/$_dist-$pkgver"
  unset PERL5LIB PERL_MM_OPT PERL_MB_OPT PERL_LOCAL_LIB_ROOT
  ./Build install --installdirs=vendor --destdir="$pkgdir"
}
A justificativa para a complexidade adicional desses PKGBUILDs é apresentada nas seções abaixo.
Mecanismos de módulo CPAN
Há uma série de mecanismos cuidadosamente projetados, e não tão cuidadosamente, que trabalham juntos para criar o sistema de módulos. Ao fazer uso do CPAN, os procedimentos devem ser seguidos para buscar o código-fonte de um módulo, criar esse módulo buscado e inseri-lo no software do sistema para execução posterior. Para entender como os módulos devem ser empacotados, isso ajuda imensamente se entendermos como os módulos funcionam sem qualquer envolvimento dos pacotes pacman e Arch Linux. Nosso objetivo, no final, é tentar ser o mais discreto possível, melhorando a organização e a consistência do produto final.
Módulos
Os módulos são declarados com a palavra-chave
package
no perl. Os módulos estão contidos em um arquivo
.pm
(pronuncia-se como "dót-pi-em"). Embora seja possível, mais de um módulo (
package
) está no arquivo. Os módulos têm namespaces separados por
::
(dois pontos duplos), como:
Archlinux::Module
. Ao carregar um módulo, os
::
s são substituídos por separadores de diretórios. Por exemplo:
Archlinux/Module.pm
será carregado para o módulo
Archlinux::Module
.
O módulos principais estão incluídos com uma instalação do perl. Alguns módulos principais estão
apenas
disponíveis empacotados com o perl. Outros módulos ainda podem ser baixados e instalados separadamente do CPAN.
Distribuições
Distributions
também são conhecidas como
dist
ou
package
no CPAN-lingo, sendo um equivalente a um pacote do Arch Linux neste site. Distribuições são arquivos
.tar.gz
cheios de arquivos. Esses arquivos contêm principalmente arquivos de módulo .pm, testes para os módulos incluídos, documentação para os módulos e o que for necessário.
Normalmente, uma distribuição contém um módulo primário com o mesmo nome. Às vezes isso não é verdade, como na distribuição do Template-Toolkit. O pacote mais recente,
Template-Toolkit-2.22.tar.gz
, para o
Template-Toolkit
dist, não contém o módulo
Template::Toolkit
!
Às vezes, porque as distribuições são nomeadas conforme um módulo principal, seus nomes são usados de forma intercambiável e ficam confusos. No entanto, às vezes é útil considerá-los uma entidade separada (como no caso do Template-Toolkit).
CPAN
Cada espelho CPAN contém índices que listam as distribuições no CPAN, os módulos nos dists e o nome do autor que carregou o dist. Estes são simplesmente arquivos de texto. O índice mais útil está no arquivo
/modules.dlocaches.details.txt.gz
disponível em cada espelho do CPAN. O termo "pacotes" aqui se refere à palavra-chave
package
na própria linguagem perl, não algo similar aos pacotes pacman. O shell CPAN, chamado de letras minúsculas, em itálico
cpan
, é simplesmente o venerável script perl que navega nos índices para encontrar o módulo que você deseja instalar.
Os módulos são encontrados na lista
02packages.details.txt.gz
. Na mesma linha que o nome do módulo/pacote está o caminho para o tarball de distribuição que contém o módulo. Quando você pede ao
cpan
para instalar um módulo, ele irá procurar o módulo e instalar a distribuição relevante. Como a distribuição está instalando, irá gerar uma lista de dependências do módulo.
Cpan
tentará carregar cada dependência de módulo no intérprete perl. Se um módulo da versão fornecida não puder ser carregado, o processo será repetido.
O shell
cpan
não precisa se preocupar com qual versão do módulo necessário está sendo instalado. O
cpan
pode confiar no fato de que a última versão do módulo deve satisfazer os requisitos do módulo original que começou a instalar em primeiro lugar. Somente as versões mais recentes dos módulos são listadas no arquivo de detalhes dos pacotes. Infelizmente, para o autor do pacote perl, nem sempre podemos confiar no fato de que nossos pacotes oferecem a versão mais recente de uma distribuição perl e os módulos contidos nela. A verificação de dependência do Pacman é muito mais estática e fortemente aplicada.
Dependências de módulos
Perl tem uma maneira única de definir dependências em comparação com sistemas similares, como
eggs
de python e
gems
de ruby.
Eggs
definem dependências de outros eggs.
Gems
dependem de
gems
. Dists de perl dependem de módulos. Os módulos só estão disponíveis nas distribuições CPAN, de modo que as distribuições perl dependem apenas indiretamente das distribuições. Os módulos podem definir suas próprias versões independentes das distribuições dentro do código-fonte do módulo. Isso é feito definindo uma variável
package
chamada
$VERSION
. Ao usar
strict
e
warnings
, isso é definido com a nossa palavra-chave. Por exemplo:
package Foo::Module;
use warnings;
use strict;
our $VERSION = '1.00';
Os módulos podem alterar suas versões da maneira que quiserem e até mesmo ter uma versão diferente da versão de distribuição. A utilidade disso é questionável, mas é importante ter em mente. Versões de módulo são mais difíceis de determinar fora do interpretador perl e requerem análise do próprio código perl e talvez até mesmo carregar o módulo em perl. A vantagem é que, dentro do módulo perl, as versões do módulo são fáceis de determinar. Por exemplo:
use Foo::Module;
print $Foo::Module::VERSION, "\n";
Definição de dependências
Onde estão as dependências definidas nas distribuições perl? Elas são "definidas" dentro do script
Makefile.PL
ou
Build.PL
. Por exemplo, dentro do script
Makefile.PL
, a função
WriteMakeFile
é chamada para gerar o
Makefile
assim:
use ExtUtils::MakeMaker;
WriteMakeFile(
    'NAME' => 'ArchLinux::Module',
    'VERSION' => '0.01',
    'PREREQ_PM' => { 'POSIX' => '0.01' },
);
Este é um exemplo artificial, mas é importante entender que as dependências não são finais até que o script
Makefile.PL
ou
Build.PL
seja executado. Dependências são especificadas em tempo de execução, o que significa que elas podem ser alteradas ou modificadas usando todo o poder do perl. Isso significa que o autor do módulo pode adicionar, remover ou alterar versões de dependências antes da instalação da distribuição. Alguns autores de módulos usam isso para fazer coisas excessivamente inteligentes, como depender de módulos apenas se eles estiverem instalados. Algumas dists multiplataformas também dependem de módulos específicos do sistema quando instalados em sistemas operacionais diferentes.
Como exemplo, a distribuição CPANPLUS procura por plugins CPANPLUS::Dist que estão atualmente instalados. Se algum plug-in estiver instalado para a versão atualmente instalada do CPANPLUS, ele será incluído nos pré-requisitos do novo CPANPLUS. Não sei bem por quê. Felizmente para o perl empacotador, a maioria das dependências é estática, como no exemplo acima, que requer o módulo POSIX com uma versão mínima de 0.01.
Informações meta
Os arquivos meta são incluídos em distribuições recentes que contêm meta-informações sobre distribuições, como nome, autor, descrição abstrata e requisitos do módulo. Anteriormente, havia arquivos
META.yml
no formato YAML, mas, mais recentemente, a mudança foi feita para arquivos
META.json
no formato JSON. Esses arquivos podem ser editados manualmente, mas com mais frequência eles são gerados automaticamente pelos scripts
Makefile.PL
ou
Build.PL
ao empacotar uma distribuição para lançamento. A última especificação é descrita nas
documentações online do CPAN::Meta::Spec
.
Lembre-se que as dependências podem ser alteradas em tempo de execução! Por esse motivo, outro meta arquivo é gerado após a execução do script de compilação. Este segundo meta arquivo é chamado
MYMETA.json
e reflete as alterações feitas no script em tempo de execução e pode ser diferente do arquivo meta gerado quando a distribuição foi empacotada para o CPAN.
Distribuições idosas no CPAN não possuem nenhum arquivo meta. Esses lançamentos antigos são anteriores à ideia do arquivo META.yml e descrevem apenas seus pré-requisitos em seu
Makefile.PL
.
Módulos instaláveis
Um dos maiores pontos fortes do perl é o grande número de módulos disponíveis no CPAN. Não muito surpreendentemente, existem também vários módulos diferentes usados para instalar... bem... módulos! Há mais de uma maneira de fazer isso! Eu não estou ciente de um nome padrão para esses tipos de módulos, então eu os chamei de "Módulos de Instalação".
Estes módulos estão preocupados com a compilação da distribuição e instalação dos arquivos do módulo, sempre que o usuário preferir. Isso parece simples, mas considerando o número de diferentes sistemas em que perl é executado, isso pode se tornar complexo. Todos os módulos de instalação colocam um arquivo de código perl dentro do tarball dist. A execução deste script perl iniciará o processo de compilação e instalação. O script sempre termina com o sufixo
.PL
e é denominado "Script de compilação" na lista abaixo.
ExtUtils::MakeMaker
Script de compilação
Makefile.PL
Link no CPAN
https://search.cpan.org/dist/ExtUtils-MakeMaker
O módulo mais antigo e original para a instalação de módulos é o
ExtUtils::MakeMaker
. A principal desvantagem deste módulo é que ele requer que o programa
make
compile e instale tudo. Isso pode não parecer um grande problema para os usuários do Linux, mas é um verdadeiro aborrecimento para as pessoas do Windows!
Module::Build
Script de instalação
Build.PL
Link no CPAN
https://search.cpan.org/dist/Module-Build
A principal vantagem do Module::Build é que ele é puro perl. Isto significa que não requer que um programa
make
seja instalado para você compilar/instalar módulos. Sua adoção foi complicada porque se o
Module::Build
ainda não estivesse instalado, você não poderia executar o script
Build.PL
incluído! Este não é um problema com versões recentes do perl porque
Module::Build
é um módulo central. (
NOTE
A partir do perl 5.22, o Module::Build não será mais um módulo central)
Module::Build::Tiny
Script de compilação
Build.PL
Link no CPAN
https://search.cpan.org/dist/Module-Build-Tiny
Esta é outra ferramenta de compilação de puro perl. Como interface, implementa um subconjunto da interface do Module::Build, em particular, requer traços antes de seus argumentos (Module::Build aceita com e sem) e não suporta
.modulebuildrc
.
Module::Install
Script de compilação
Makefile.PL
Link no CPAN
https://search.cpan.org/dist/Module-Install
Outro módulo moderno de compilação/instalação,
Module::Install
ainda requer que o programa
make
seja instalado para funcionar.
MI
foi criado para substituir
MakeMaker
, para resolver algumas das deficiências do
MakeMaker
. Ironicamente, isso depende do
MakeMaker
para operar. Os arquivos
Makefile.PL
que são gerados pelo
MI
são muito diferentes e são implementados usando uma linguagem simples específico do domínio.
Uma característica muito interessante é que o
Module::Install
empacota uma
cópia completa
de si mesmo no arquivo de distribuição. Por causa disso, ao contrário de
MakeMaker
ou
M::B
, você não precisa que
Module::Install
esteja instalado em seu sistema.
Outra característica muito original é a instalação automática.
Embora não seja recomendado pelos autores de
Module::Install
, esse recurso é usado com bastante frequência
. Quando o autor do módulo habilita a auto-instalação para sua distribuição,
Module::Install
irá procurar e instalar quaisquer módulos de pré-requisito que não estejam instalados quando o
Makefile.PL
for executado. Este recurso é ignorado quando
Module::Install
detecta que está sendo executado por
CPAN
ou
CPANPLUS
. No entanto, esse recurso não é ignorado quando executado dentro... oh, eu não sei ... um
PKGBUILD
! Espero que você possa ver como um programa permissivo do perl baixando e instalando módulos a qualquer momento, dentro de um PKGBUILD, possa ser um problema. Veja a variável de ambiente
#PERL_AUTOINSTALL
para ver como corrigir isso.
Variáveis de ambiente
Diversas variáveis de ambiente podem afetar o modo como os módulos são construídos ou instalados. Alguns têm um efeito muito dramático e podem causar problemas se forem mal compreendidos. Um usuário avançado pode estar usando essas variáveis de ambiente. Algumas delas quebrarão um PKGBUILD desavisado ou causarão um comportamento inesperado.
PERL_MM_USE_DEFAULT
Quando esta variável é definida para um valor verdadeiro, o módulo de instalação fingirá que a resposta padrão foi dada para qualquer pergunta que normalmente faria. Isso não "sempre" funciona, mas todos os módulos de instalação o honram.
Isso não significa que o autor do módulo irá!
PERL_AUTOINSTALL
Você pode passar argumentos adicionais de linha de comando para o
Makefile.PL
do
Module::Install
com essa variável. Para desativar a instalação automática (
altamente recomendado
), atribua
--skipdeps
a este.
export PERL_AUTOINSTALL='--skipdeps'
PERL_MM_OPT
Você pode passar argumentos adicionais de linha de comando a
Makefile.PL
e/ou
Build.PL
com essa variável. Por exemplo, você pode instalar módulos em seu diretório pessoal usando:
export PERL_MM_OPT=INSTALLBASE=~/perl5
PERL_MB_OPT
Essa é a mesma coisa que
PERL_MM_OPT
, exceto por ser apenas para
Module::Build
. Por exemplo, você poderia instalar módulos em seu diretório pessoal usando:
export PERL_MB_OPT=--install_base=~/perl5
MODULEBUILDRC
Module::Build
permite que você sobrescreva seus argumentos de linha de comando com um arquivo rc. O padrão deste é
~/.modulebuildrc
. É considerado obsoleto no conjunto de ferramentas perl. Você pode sobrescrever qual arquivo usa definindo o caminho para o arquivo rc em
MODULEBUILDRC
. Os paranoicos podem definir
MODULEBUILDRC
para
/dev/null
... apenas por precaução.
PERL5LIB
Os diretórios pesquisados por bibliotecas podem ser configurados pelo usuário (especialmente se eles estiverem usando
Local::Lib
) definindo
PERL5LIB
. Isso deve ser apagado antes de compilar.
PERL_LOCAL_LIB_ROOT
Se o usuário estiver usando
Local::Lib
, então
PERL_LOCAL_LIB_ROOT
será definido. Isso deve ser apagado antes de compilar.
Problemas com perl instalado pelo usuário
Um problema sutil é que os programadores avançados de perl podem gostar de ter múltiplas versões de perl instaladas. Isso é útil para testar a compatibilidade com versões anteriores em programas criados. Também há benefícios de velocidade para compilar seu próprio interpretador perl personalizado (p. ex., sem threads). Outra razão para um
perl
personalizado é simplesmente porque o pacote perl do Arch Linux às vezes fica atrás de versões perl. O usuário pode estar experimentando o perl mais recente ... quem sabe?
Se o usuário tiver um executável personalizado do perl em seu
$PATH
, o perl personalizado será executado quando o usuário digita o comando
perl
na shell. Na verdade, o perl personalizado será executado dentro do
PKGBUILD
também! Isso pode levar a problemas traiçoeiros que são difíceis de entender.
O problema reside nos módulos XS compilados. Esses módulos ligam perl e C. Como tal, eles devem usar a API C internal do perl para realizar essa ponte. A API C do perl muda um pouco entre diferentes versões do perl. Se o usuário tiver uma versão diferente do perl do que o perl do sistema (
/usr/bin/perl
), então qualquer módulo XS compilado com o perl do usuário será incompatível com o perl do sistema. Ao tentar usar o módulo XS compilado com o perl do sistema, o módulo vai falhar em carregar com um erro de vinculação.
Uma solução simples é sempre usar o caminho absoluto do interpretador perl do sistema (
/usr/bin/perl
) ao executar perl no
PKGBUILD
.