Joenio Marques da Costa
Joenio Marques da Costa

Tutorial de empacotamento Debian - Parte 2

Debian shot wallpaper por mdh3ll

Este tutorial descreve passo-a-passo como criar pacotes de bibliotecas da linguagem de programação Perl para o sistema operacional Debian e submetê-lo aos repositórios oficiais via Debian Perl Group.

O Debian é um sistema operacional livre criado e mantido por um grupo independente de desenvolvedores espalhados ao redor do mundo, o projeto foi iniciado em 1993 e tem sido desenvolvido abertamente desde então, sempre seguindo o espírito livre do projeto GNU.

Roteiro deste tutorial

Esta é a segunda parte do Tutorial de empacotamento Debian e é importante que você tenha feito a parte 1, caso contrário volte a parte 1 e siga ao menos as etapas de configuração do ambiente de desenvolvimento, link abaixo.

Após fazer as configurações básicas e instalar os pacotes necessários vamos iniciar a parte 2 deste tutorial seguindo o roteiro abaixo.

  • Selecionar um dos pacotes candidatos para empacotamento
  • Criar o pacote da biblioteca selecionada
  • Construir o pacote e verificar problemas
  • Executar testes automatizadod do pacote
  • Submeter o pacote aos repositórios oficiais via Debian Perl Group

Pacotes candidatos para empacotamento

Seleciona uma das bibliotecas abaixo, algumas já possuem bug do tipo RFP aberto no sistema de acompanhamento de bugs (Bug Tracking System - BTS) do Debian, as demais são bibliotecas Perl com upload recente no cpan.org ainda nao empacotados no Debian, e que possuam uma ou mais dependencias reversas, isso significa que a biblioteca tem usuários.

Selecionar um dos pacotes abaixo para empacotamento

Selecione um dos pacotes candidatos acima e siga os passos que se seguem adaptando sempre o nome da biblioteca e o nome do pacote que você escolheu, o tutorial irá descrever os passos para o pacote Getopt::EX::Hashed, você deve selecionar um pacote diferente entre os pacotes acima, ou se preferir pode selecionar outra biblioteca qualquer que ainda não esteja empacotada no Debian.

Criar o pacote da biblioteca selecionada

Antes de criar a versão inicial do pacote verifique se o pacote não está empacotado no Debian.


sudo apt-file update
dh-make-perl locate Getopt::EX::Hashed


== dh-make-perl 0.124 ==
Using cached Contents from Wed May 15 21:03:54 2024
Getopt::EX::Hashed is not found in any Debian package

Garantindo que o pacote não está presente, vamos seguir e criar o template inicial do pacote usando o dh-make-perl.


dh-make-perl --pkg-perl --cpan Getopt::EX::Hashed

Correções básicas no template inicial

O dh-make-perl criou o pacote inicial libgetopt-ex-hashed-perl para a biblioteca Getopt::EX::Hashed, é necessário realizar algumas correções.

Arquivo debian/copyright

A primeira correção é o ano e o email do autor do pacote, será preciso buscar essas duas informações no código fonte da biblioteca Getopt::EX::Hashed.

Files: *
Copyright: <INSERT COPYRIGHT YEAR(S) HERE>, Kazumasa Utashiro
License: Artistic or GPL-1+

Podemos analisar os arquivos manualmente abrindo de um em um para encontrar essa informação ou usar os comandos abaixo para nos auxiliar.

grep


grep -i -r --exclude-dir=.git --exclude-dir=debian copyright

licensecheck


licensecheck --shortname-scheme=debian,spdx --copyright --recursive .

scan-copyrights


scan-copyrights

Analisando a saída de cada um desse comandos foi possível identificar que o ano do copyright do Getopt::EX::Hashed é 2021-2024 e o email do author é kaz@utashiro.com, essas duas alterações no arquivo debian/copyright nos dá o seguinte diff abaixo.

joenio@debian-dev-main:~/tutorial/libgetopt-ex-hashed-perl$ git diff
diff --git a/debian/copyright b/debian/copyright
index 4860058..018e342 100644
--- a/debian/copyright
+++ b/debian/copyright
@@ -12,7 +12,7 @@ DISCLAIMER: This copyright info was automatically extracted
  with this file.
 
 Files: *
-Copyright: <INSERT COPYRIGHT YEAR(S) HERE>, Kazumasa Utashiro
+Copyright: 2021-2024, Kazumasa Utashiro <kaz@utashiro.com>
 License: Artistic or GPL-1+
 
 Files: debian/*

Commit.


git commit debian/copyright -m 'd/copyright: add upstream copyright year/email'

Remova também o DISCLAIMER adicionado pelo dh-make-perl e commit.


git commit debian/copyright -m 'd/copyright: remove dh-make-perl disclaimer'

No exemplo seguido aqui essas duas alterações são suficientes mas é possível que a biblioteca que você escolheu necessite de mais alterações, é possível que exista mais de um nome declarado como dono do copyright nos arquivos de código-fonte, é necessário adicionar cada nome com seus respectivos ano e email.

A título de exemplo é possível definir algo como no exemplo abaixo, com múltiplos nomes, e ano diferentes no arquivo debian/copyright.

Files: debian/*
Copyright: 2006, Florian Ragwitz <rafl@debian.org>
 2008-2014, gregor herrmann <gregoa@debian.org>
 2008, Damyan Ivanov <dmn@debian.org>
License: Artistic or GPL-1+

Caso o upstream não forneça informação sobre o copyright de algum arquivo será necessário documentar isso de alguma forma, uma opção é adotar o padrão Berne Convention Comment e adicionar o seguinte comentário.

Comment: The upstream distribution does not contain an explicit statement of
 copyright ownership. Pursuant to the Berne Convention for the Protection of
 Literary and Artistic Works, it is assumed that all content is copyright by
 its respective authors unless otherwise stated.

Arquivo debian/control

Verifique o arquivo debian/control no seu editor de texto preferido e se necessário atualize o campo Standards-Version para versão 4.7.0.

Standards-Version: 4.7.0

Faça commit da mudança.


git commit debian/control -m 'declare compliance with Debian Policy 4.7.0'

Verifique também a versão do debhelper-compat, deve estar com a versão mais recente 13.

Build-Depends: debhelper-compat (= 13),

E commit caso tenha alterado o arquivo.


git commit debian/control -m 'update debhelper compat to 13'

Atualize a descrição do pacote, tanto para a descrição curta (synopsis), quanto para a descrição longa (extended description), veja por exemplo o diff com a descrição do libgetopt-ex-hashed-perl.

joenio@debian-dev-main:~/tutorial/libgetopt-ex-hashed-perl$ git diff
diff --git a/debian/control b/debian/control
index d5bdf38..a5db9da 100644
--- a/debian/control
+++ b/debian/control
@@ -20,19 +20,10 @@ Architecture: all
 Depends: ${misc:Depends},
          ${perl:Depends},
          libscalar-list-utils-perl
-Description: Hash store object automation for Getopt::Long
- Getopt::EX::Hashed is a module to automate a hash object to store command
- line option values for Getopt::Long and compatible modules including
- Getopt::EX::Long. Module name shares Getopt::EX prefix, but it works
- independently from other modules in Getopt::EX, so far.
+Description: Perl module to automatically store Getopt::Long options into Hash
+ The Getopt::EX::Hashed is a module to automate a hash object to store command
+ line option values for Getopt::Long and compatible modules, including
+ Getopt::EX::Long.
  .
- Major objective of this module is integrating initialization and
- specification into single place. It also provides simple validation
- interface.
- .
- Accessor methods are automatically generated when is parameter is given. If
- the same function is already defined, the program causes fatal error.
- Accessors are removed when the object is destroyed. Problems may occur when
- multiple objects are present at the same time.
- .
- This description was automagically extracted from the module by dh-make-perl.
+ The module name shares the Getopt::EX namespace, but it works independently
+ from other modules with the Getopt::EX prefix.

Commit as modificações feita na descrição.


git commit debian/control -m 'rephrase synopsis and extended description'

Atenção sobre dependendências declaradas no debian/control

Não se deve incluir dependencias para os pacotes perl-modules ou perl-base, apenas para perl, lembrar que perl é fornecido por ${perl:Depends}. Verifique a versão das dependências, nem sempre as sugestões dos desenvolvedores no Makefile.PL está correta, ou pode ocorrer do Debian não possuir versão mais antiga que as versões no Makefile.PL.

Verifique se debian/control contém a seguinte definição para declarar que o build do pacote não precisa de root e pode ser executado com usuário comum, que é o caso da maioria dos pacotes Perl.

Rules-Requires-Root: no

Por fim, use o cme para analisar o debian/control e corriga os eventuais alertas e problemas relatados.


cme check dpkg-control debian/control

Se a saída for semelhante ao conteúdo abaixo significa que não foi encontrado nenhum erro ou alerta e o arquivo debian/control está ok.

Reading package lists... Done
Building dependency tree... Done
Reading state information... Done

Arquivo debian/changelog

Será necessário alterar este arquivo pois nele é onde fazemos referência ao número do bug report no sistema de bugs do Debian, veremos isso mais adiante, algo necessário para pacotes que serão submetidos ao repositório oficial do Debian.

Construir o pacote num ambiente chroot isolado

É importante manter o chroot sempre atualizado, então lembre de sempre executar o comando abaixo antes de buildar um novo pacote.


sudo pbuilder update

Gerar o pacote e verificar a conformidade com lintian

Construir o pacote dentro do chroot além da vantagem de isolamento possui também a comodidade de não precisar instalar manualmente as dependências de build do pacote pois o pbuilder toma conta de instalar tudo que está declarado no debian/control.


BUILDER=pbuilder git-pbuilder

Lembre de rodar o Lintian com a flag específicas para pacotes Perl --profile pkg-perl, isto inclui algumas verificações específicas definidas pelo Debian Perl Group. Adicione também a flag --info para ver mais detalhes com explicação sobre os alertas.


lintian -I --profile pkg-perl --info

O lintian produziu os dois alertas abaixo para o pacote libgetopt-ex-hashed-perl

W: libgetopt-ex-hashed-perl: initial-upload-closes-no-bugs [usr/share/doc/libgetopt-ex-hashed-perl/changelog.Debian.gz:1]
W: libgetopt-ex-hashed-perl source: newer-standards-version 4.7.0 (current is 4.6.2)

O primeiro alerta initial-upload-closes-no-bugs será corrigido na próxima etapa, já o alerta newer-standards-version pode ser ignorado pois aparentemente se trata de um falso-positivo que será atualizado numa próxima versão do lintian como pode ser visto no commit abaixo.

Executar o testes funcionals do Debian com autopkgtest

O autopkgtest do time de Perl injeta uma serie de testes que “no caso geral” funciona com qualquer biblioteca do CPAN (exemplo: smokes, use.t, syntax.t, etc…), veja detalhes no link abaixo.

No link abaixo há um tutorial simples, curto e pratico feito no debci sobre o autopkgtest:

Vamos usar o autopkgtest combinado com schroot, a ferramenta mk-sbuild torna a vida mais facil para criar chroots sem precisar root, basta adicionar o seu usuario ao grupo sbuild. Após adicionar seu usuário ao grupo sbuild é necessário fazer logout e login no Debian.


sudo apt-get install  ubuntu-dev-tools
sudo adduser joenio sbuild

Entao execute mk-sbuild <release>, sera criado um chroot com o nome <release>-<arch>, exemplo sid-amd64.


mk-sbuild sid

depois basta rodar no codigo do pacote para buildar com esse chroot:


autopkgtest . -- schroot sid-amd64

As últimas linhas impressas no terminal após a execução do autopkgtest informa que o pacote rodou os testes com sucesso.

All tests successful.
Files=1, Tests=4,  0 wallclock secs ( 0.01 usr  0.01 sys +  0.05 cusr  0.00 csys =  0.07 CPU)
Result: PASS
autopkgtest [12:43:16]: test autodep8-perl-recommends: -----------------------]
autopkgtest [12:43:16]: test autodep8-perl-recommends:  - - - - - - - - - - results - - - - - - - - - -
autodep8-perl-recommends PASS (superficial)
autopkgtest [12:43:16]: @@@@@@@@@@@@@@@@@@@@ summary
autodep8-perl-build-deps PASS
autodep8-perl        PASS (superficial)
autodep8-perl-recommends PASS (superficial)

Atualizar o arquivo debian/changelog com o número do bug

Ao empacotar um software é importante registrar que temos a intenção de empacotar este software para que a comunidade Debian tenha conhecimento de que alguém está trabalhando nisso e assim evitar re-trabalho e sobreposição, um pseudo-pacote chamado wnpp (Work-Needing and Prospective Packages) é utilizado para concentrar os bugreports relativos a novos pacotes.

Os bugs reportados no pseudo-pacote wnpp recebem tags indicando o tipo do “bug”, neste caso queremos reportar um bug indicando que estamos trabalhando (ou iremos trabalhar) num novo pacote, a tag para isso é a ITP (Intent To Package), consulte a documentação oficial do reportbug para saber como configurá-lo e execute o seguinte comando para registrar um bug do tipo ITP.

Mas se você selecionou um dos pacotes candidatos com bug do tipo RFP já aberto então não é necessário abrir um ITP, basta referenciar o número do bug RFP no arquivo debian/changelog. Deve ser informado no arquivo debian/changelog uma mensagem referenciando o fechamendo de um bug do tipo ITP ou RFP, em resumo:

  • ITP - Intenção de empacotar (“Intent To Package”) você mesmo.
  • RFP - Requisição de empacotamento (“Request For Package”) para uma outra pessoa.

Reportar bug do tipo ITP

É possível usar a ferramenta reportbug, uma ferramenta de linha de comando para reportar bugs do sistema Debian em conjunto com o msmtp. Os dois juntos permitem enviar emails para abertura de bugs diretamente da linha de comando, o msmtp pode ser útil também em outros contextos, como por exemplo no uso da ferramenta caff para assinaturas de chaves GPG, mas a configuração do reportbug e do msmtp está fora de escopo deste tutorial e você deve enviar o email usando seu cliente de email preferido. Mas se quiser se aventurar e usar o reportbug e o msmtp consulte os links abaixo.

Vamos utilizar o dpt gen-itp para gerar o conteúdo do email, basta executar o comando abaixo a partir do diretório do pacote, no meu caso é libgetopt-ex-hashed-perl. O gen-itp irá ler a descrição curta do debian/control e outras informações dos arquivos no debian/.


dpt gen-itp > /tmp/mail
cat /tmp/mail


From: =?UTF-8?B?Sm9lbmlvIE1hcnF1ZXMgZGEgQ29zdGEgPGpvZW5pb0Bqb2VuaW8ubWU+?=
To: Debian Bug Tracking System <submit@bugs.debian.org>
Subject: ITP: libgetopt-ex-hashed-perl -- Perl module to automatically store Getopt::Long options into Hash
Date: Wed, 15 May 2024 23:25:32 +0200

Package: wnpp
Owner: Joenio Marques da Costa <joenio@joenio.me>
Severity: wishlist
X-Debbugs-CC: debian-devel@lists.debian.org, debian-perl@lists.debian.org

* Package name    : libgetopt-ex-hashed-perl
  Version         : 1.0601
  Upstream Author : Kazumasa Utashiro
* URL             : https://metacpan.org/release/Getopt-EX-Hashed
* License         : Artistic or GPL-1+
  Programming Lang: Perl
  Description     : Perl module to automatically store Getopt::Long options into Hash

The Getopt::EX::Hashed is a module to automate a hash object to store command
line option values for Getopt::Long and compatible modules, including
Getopt::EX::Long.

The module name shares the Getopt::EX namespace, but it works independently
from other modules with the Getopt::EX prefix.

The package will be maintained under the umbrella of the Debian Perl Group.

--
Generated with the help of dpt-gen-itp(1) from pkg-perl-tools.

Copie e cole os campos de assunto, destinatário e corpo do email, veja exemplo abaixo usando o Thunderbird, use o seu cliente de email e envie a mensagem para submit@bugs.debian.org.

Aguarde alguns minutos e verifique a mensagem nos servidores do Debian, você deve receber uma cópia do email semelhante a esta mensagem aqui, ela mensagem contém o número do bug, adicione o número do bug no arquivo debian/changelog com a mensagem “(Closes: #<numero do bug>)”, use o comando dch para auxiliar nesta tarefa.


dch --closes 1071196

Você deve substituir o número 1071196 pelo número do seu bug, veja como ficou o changelog do libgetopt-ex-hashed-perl.

libgetopt-ex-hashed-perl (1.0601-1) UNRELEASED; urgency=low

  * Initial release. (Closes: #1071196)

 -- Joenio Marques da Costa <joenio@joenio.me>  Wed, 15 May 2024 21:14:29 +0200


git commit debian/changelog -m 'd/changelog: add ITP bug number'

Alterar pacote de UNRELEASED para unstable

Esta é a última mudança no pacote antes de fazer upload do pacote, o pacote deve ser indicado como unstable, isto significa que os pacotes sempre entram na distribuição unstable, a partir disso segue seu fluxo até chegar na versão stable, passando pela testing.

Atualizar debian/changelog e atualize no cabeçalho do arquivo de UNRELEASED para unstable. O comando dch -r (--release) atualizar automaticamente o debian/changelog de UNRELEASED para unstable, e atualiza a data.


dch --release



git commit debian/changelog -m 'd/changelog: ready for review and upload'

Fazer upload do pacote no repositório do time Debian Perl

Está tudo pronto para fazer upload, falta apenas ter acesso ao repositório do Debian Perl Group no Salsa, Salsa é uma instância do Gitlab e funciona como uma plataforma de desenvolvimento colaborativa dentro do Debian. Para escrever no repositório do Debian Perl Group é necessário fazer parte do time, para isso é necessário seguir os seguintes passos.

A conta no Salsa precisa ser validada por um administrador, isso pode levar algum tempo e deve-se aguardar. Use seu nome real ao inscrever-se pora reduzir falsos positivos na heurística de detecção de spammers, mais sobre Salsa em:

Configurar dpt com o token Salsa

Uma vez que seu usuário Salsa foi criado e você foi adicionado ao time Debian Perl Group, basta atualizar a configuração do dpt em ~/.dpt.conf e adicionar o TOKEN de acesso do Salsa para poder escrever nos repositórios do grupo e poder enviar as atualizações do pacote.

DPT_SALSA_PRIVATE_TOKEN=***COPIE EU TOKEN AQUI***

Uma vez tendo usuário no Salsa e fazendo parte do time Debian Perl Group, compartilhe o pacote enviando as atualizações para o repositório do grupo com o seguinte comando.

Upload

É necessário solicitar acesso ao Salsa do time Perl do Debian enviando um email com uma curta apresentação pessoal para o seguinte email debian-perl@lists.debian.org. Após ter acesso ao repositório do grupo Perl é hora de fazer upload do pacote no repositório do grupo, mas antes faça uma revisão final no pacote:

  • Verifique se o status do pacote em debian/changelog foi alterado de UNRELEASED para unstable
  • Garanta que há uma mensagem (Closes: #NNNNNN) no debian/changelog indicando o número do bug ITP
  • Verifique a versão correta de “Standards-Version:”, aqui a versão utilizada foi 4.3.0
  • Use o formato correto no arquivo debian/copyright, atualmente usar DEP-5
  • Verificar o COPYRIGHT de cada arquivo (usar grep ou ack) para buscar a quem pertence o copyright de cada arquivo
  • Registre um token em https://salsa.debian.org/profile/personal_access_tokens e defina este token na variável de ambiente DPT_SALSA_PRIVATE_TOKEN para que o dpt tenha acesso de escrita no servidor Salsa.

Feito as verificações finais, use o comando abaixo para criar e configurar um novo projeto no Salsa, e subir o repositório local do nosso novo pacote libgetopt-ex-hashed-perl.


dpt salsa pushrepo

O módulo Getopt::EX::Hashed empacotado para libgetopt-ex-hashed-perl durante a escrita deste post foi submetido ao repositório do Debian Perl Group e pode ser visualizado em:

Para saber mais detalhes de como fazer upload do seu pacote veja a documentação pushing to salsa.debian.org, além do token é necessário também fazer upload de sua chave ssh no Salsa, ele é uma instância do Gitlab, então basta acessar sua conta ir em preferências e configurar uma chave ssh por lá.

Algum tempo após o upload o pacote um DD (Debian Developer) irá revisar o pacote e caso encontre problemas vai solicitar alterações mudando o status em debian/changelog para UNRELEASED.

Bem, é isso, espero que este texto seja útil ajudando e incentivando mais pessoas a empacotar software no Debian, uma atividade muito importante e que requer um trabalho constante.

Video demo sobre o dpt

a imagem utilizada no cabeçalho do post foi copiada de https://www.deviantart.com/mdh3ll/art/Debian-shot-311580879