Tutorial introdutório para fazer pacotes Debian. O tutorial não se aprofunda nos detalhes mais intrincados do empacotamento no Debian, mas mostra como fazer pacotes Debian para software simples de empacotar. Para mais tutoriais, veja Packaging.

Contents

  1. O que é um "pacote"?
  2. Requisitos
  3. Três conceitos centrais
  4. O fluxo de trabalho do empacotamento
    1. Etapa 1: Renomear o arquivo tarball upstream
    2. Etapa 2: Descompactar o arquivo tarball upstream
    3. Etapa 3: Adicionar os arquivos de empacotamento Debian
    4. Etapa 4: Construir o pacote
    5. Etapa 5: Instalar o pacote
  5. Conclusão
  6. Veja também

Escrito em 2010

Este tutorial descreve a prática recomendada em meados de 2010. A teoria não mudou, mas as ferramentas específicas não são mais recomendadas para uso geral.

Para mais guias, veja Packaging.

O que é um "pacote"?

Um pacote Debian é uma coleção de arquivos que permite que aplicativos ou bibliotecas sejam distribuídos através do sistema de gerenciamento de pacotes. O objetivo do empacotamento é permitir a automação da instalação, atualização, configuração e remoção de programas de computador para o Debian de maneira consistente. Um pacote consiste em um pacote-fonte e um ou mais pacotes binários. A Política Debian (Debian Policy) especifica o formato padrão para um pacote, que todos os pacotes devem seguir.

Os pacotes binários contêm executáveis, arquivos de configuração padrão, outros recursos necessários para que os executáveis ​​sejam executados, documentação, dados, ...

Os pacotes-fonte contêm a distribuição de código-fonte do(a) autor(a) original (upstream), configurações do sistema de construção do pacote, lista de dependências de tempo de execução e pacotes conflitantes, uma descrição legível por máquina de copyright e informações de licença, configurações iniciais do software, e muito mais.

O objetivo do empacotamento é produzir esses pacotes a partir da fonte não empacotada. O pacote-fonte (.dsc) e os pacotes binários (.deb) serão construídos para você por ferramentas como a dpkg-buildpackage.

Você pode ler mais sobre a anatomia de pacotes binários ou de pacotes-fonte em suas páginas wiki.

Os pacotes devem estar de acordo com a política Debian para serem aceitos nos repositórios de pacotes. Pacotes binários .deb construídos manualmente que não foram construídos a partir de um pacote-fonte não serão aceitos. Isso mantém a consistência e a reprodutibilidade.

Requisitos

Este tutorial presume que você entende:

Isso é tudo o que você precisa.

Pacotes necessários:

Três conceitos centrais

Os três conceitos centrais são:

O pacote-fonte mais simples consiste em três arquivos:

O fluxo de trabalho do empacotamento

Após o teste, o pacote-fonte e binários podem ser carregados no repositório Debian.

Para este tutorial, este tarball será usado como exemplo.

Etapa 1: Renomear o arquivo tarball upstream

As ferramentas de empacotamento exigem que o arquivo tarball esteja em conformidade com a convenção de nomenclatura.

O nome deve ser: nome do pacote-fonte, sublinha, número da versão upstream seguido por .orig.tar.gz. O nome do pacote-fonte deve estar em letras minúsculas e pode conter letras, dígitos e traços. Outros caracteres também são permitidos. Convenções de nomenclatura mais detalhadas podem ser encontradas em debmake doc.

Mudanças mínimas devem ser feitas no nome original para torná-lo compatível com o Debian. Se o nome original estiver de acordo com o padrão, você deve usá-lo.

No nosso exemplo, a upstream escolheu um nome adequado, "hithere", portanto não há necessidade de alterações.

Terminaremos com um arquivo chamado hithere_1.0.orig.tar.gz.

Observe que há uma sublinha (_), não um traço (-), no nome. Isso é importante.

  • $ mv hithere-1.0.tar.gz hithere_1.0.orig.tar.gz

Etapa 2: Descompactar o arquivo tarball upstream

O código-fonte será descompactado em um diretório de mesmo nome e com a versão upstream com um hífen no meio (não uma sublinha). Desse modo, o tarball upstream de exemplo deve ser descompactado em um diretório chamado "hithere-1.0".

Nesse caso, o tarball já descompacta no subdiretório correto, portanto nenhuma alteração é necessária.

  • $ tar xf hithere_1.0.orig.tar.gz

Etapa 3: Adicionar os arquivos de empacotamento Debian

Todos os arquivos a seguir serão colocados no subdiretório debian/ dentro do diretório de origem, portanto criamos esse diretório.

  • $ cd hithere-1.0
    $ mkdir debian

Vamos dar uma olhada nos arquivos que precisamos fornecer.

debian/changelog

O primeiro arquivo é o debian/changelog. Este é o registro (log) das mudanças no pacote Debian.

Não é necessário listar tudo o que foi alterado no código upstream, mas um resumo é útil para outras pessoas.

Como agora estamos fazendo a primeira versão, não há nada para registrar. No entanto, ainda assim precisamos fazer uma entrada no changelog porque as ferramentas de empacotamento lêem as informações do changelog: a mais importante, a versão do pacote.

debian/changelog tem um formato padrão. A maneira mais fácil de criá-lo é usando a ferramenta dch.

  • $ dch --create -v 1.0-1 -u low --package hithere

Isso resulta em um arquivo como este: 

hithere (1.0-1) UNRELEASED; urgency=low

  * Initial release. (Closes: #XXXXXX)

 -- Lars Wirzenius <liw@liw.fi>  Thu, 18 Nov 2010 17:25:32 +0000

Algumas notas:

debian/control

O arquivo de controle descreve o pacote-fonte e o pacote binário, e fornece algumas informações sobre eles, como seus nomes, quem é o(a) mantenedor(a) do pacote e assim por diante. Aqui está um exemplo: 

Source: hithere
Maintainer: Lars Wirzenius <liw@liw.fi>
Section: misc
Priority: optional
Standards-Version: 4.6.2
Build-Depends: debhelper-compat (= 13)

Package: hithere
Architecture: any
Depends: ${shlibs:Depends}, ${misc:Depends}
Description: greet user
 hithere greets the user, or the world.

Existem vários campos obrigatórios, mas você pode apenas tratá-los como mágicos por enquanto. Portanto, em debian/control existem dois trechos de código.

O primeiro trecho descreve o pacote-fonte com estes campos:

Source
O nome do pacote-fonte.
Maintainer
O nome e endereço de e-mail da pessoa responsável pelo empacotamento.
Priority

A prioridade do pacote (que pode ser 'required', 'important', 'standard' ou 'optional'). Em geral, um pacote é 'optional' a menos que seja 'essential' para um sistema funcional padrão, ou seja, inicializar ou acessar uma rede. De acordo com a Política Debian 4.5.1 (ou mais recente), a prioridade de pacote 'extra' está obsoleta.

Build-Depends
A lista de pacotes que precisam ser instalados para construir o pacote. Eles podem ou não ser necessários para realmente usar o pacote.

Todos os trechos de código após o primeiro descrevem os pacotes binários construídos a partir dessa fonte. Pode haver muitos pacotes binários construídos a partir de uma mesma fonte; nosso exemplo tem apenas um. Usamos estes campos:

A dependência de construção (Build-Dependency) debhelper-compat especifica o "nível de compatibilidade" para o nível da ferramenta debhelper via uma limitação de versão. O exemplo acima especifica a compatibilidade nível 13 (que substitui o arquivo obsoleto debian/compat).

Package
O nome do pacote binário. O nome pode ser diferente do nome do pacote-fonte.
Architecture
Especifica em quais arquiteturas de computador o pacote binário deve funcionar: i386 para CPUs Intel de 32 bits, amd64 para 64 bits, armel para processadores ARM, e assim por diante. O Debian funciona em cerca de uma dúzia de arquiteturas de computador no total, portanto este suporte de arquiteturas é crucial. O campo "Architecture" pode conter nomes de arquiteturas específicas, mas geralmente contém um de dois valores especiais.
any
(que vemos no exemplo) significa que o pacote pode ser construído para qualquer arquitetura. Em outras palavras, o código foi escrito para ser portável, portanto não faz muitas suposições sobre o hardware. No entanto, o pacote binário ainda precisará ser construído para cada arquitetura separadamente.
all
significa que o mesmo pacote binário funcionará em todas as arquiteturas sem ter que ser construído separadamente para cada uma. Por exemplo, um pacote que consiste apenas em scripts shell seria "all". Os scripts shell funcionam da mesma forma em qualquer lugar e não precisam ser compilados.
Depends

A lista de pacotes que devem ser instalados para o programa no pacote binário funcionar. Listar essas dependências manualmente é um trabalho tedioso e sujeito a erros. Para fazer isso funcionar de forma mais automática, o pedaço mágico ${shlibs:Depends} precisa estar lá para pacotes que contém bibliotecas compartilhadas construídas e executáveis. Outra coisa mágica está lá para o debhelper, o que completa o ${misc:Depends}. Para outras dependências, você precisará adicioná-las manualmente em Depends ou Build-Depends e a parte mágica ${...} somente funciona em Depends. Note que os pedaços mágicos ${...} somente funcionam em Depends, mas não em Build-Depends.

Description
A descrição completa do pacote binário. Destina-se a ser útil para usuários(as). A primeira linha é usada como uma breve descrição da sinopse (resumo) e o resto da descrição deve ser uma descrição independente mais longa do pacote.

O comando cme edit dpkg fornece uma interface gráfica para editar a maioria dos arquivos de empacotamento, incluindo debian/control. Consulte a página Gerenciando pacotes Debian com cme. O comando cme é distribuído no Debian no pacote cme. Você também pode editar apenas o arquivo debian/control com o comando cme edit dpkg-control.

debian/copyright

É um arquivo muito importante, mas por agora ficaremos felizes com um arquivo vazio. 

Para o Debian, esse arquivo é usado para controlar as informações legais relacionadas a direitos autorais sobre um pacote. No entanto, não é importante do ponto de vista técnico. Por enquanto, vamos nos concentrar nos aspectos técnicos. Voltaremos ao debian/copyright mais tarde, se houver interesse. 


debian/rules


Ele deve se parecer com isto: 
#!/usr/bin/make -f
%:
        dh $@
debian/rules pode se tornar um arquivo bastante complicado. No entanto, o comando dh no debhelper versão 7 tornou possível mantê-lo simples em muitos casos. 


debian/source/format


O arquivo final que precisamos é debian/source/format, que deve conter o número da versão para o formato do pacote-fonte, que é "3.0 (quilt)". 
3.0 (quilt)


Etapa 4: Construir o pacote




Primeira tentativa


Agora podemos construir o pacote. 
Existem muitos comandos que podemos usar, mas este é o que usaremos. Se executar o comando, obterá uma saída semelhante a esta: 
  • $ debuild -us -uc 
make[1]: Entering directory `/home/liw/debian-packaging-tutorial/x/hithere-1.0'
install hithere /home/liw/debian-packaging-tutorial/x/hithere-1.0/debian/hithere/usr/local/bin
install: cannot create regular file `/home/liw/debian-packaging-tutorial/x/hithere-1.0/debian/hithere/usr/local/bin': No such file or directory
make[1]: *** [install] Error 1
make[1]: Leaving directory `/home/liw/debian-packaging-tutorial/x/hithere-1.0'
dh_auto_install: make -j1 install DESTDIR=/home/liw/debian-packaging-tutorial/x/hithere-1.0/debian/hithere returned exit code 2
make: *** [binary] Error 29
dpkg-buildpackage: error: fakeroot debian/rules binary gave error exit status 2
debuild: fatal error at line 1325:
dpkg-buildpackage -rfakeroot -D -us -uc failed


Algo deu errado. Isso é o que geralmente acontece. Você faz o seu melhor criando os arquivos debian/*, mas sempre há algo que você não acerta. 
O que deu errado é esta parte: 
install hithere /home/liw/debian-packaging-tutorial/x/hithere-1.0/debian/hithere/usr/local/bin


O Makefile upstream está tentando instalar o programa compilado no local errado. 
Há algumas coisas acontecendo aqui: a primeira é sobre como funciona o empacotamento Debian. 


Correção


Quando o programa foi compilado e "instalado", ele não é instalado em /usr ou /usr/local como de costume, mas em algum lugar sob o subdiretório debian/. 
Nós criamos um subconjunto de todo o sistema de arquivos em debian/hithere e a seguir o colocamos no pacote binário. Portanto, a parte .../debian/hithere/usr/local/bin está boa, exceto que não deveria ser instalada em usr/local, mas diretamente sob usr. 
Precisamos fazer algo para que ele seja instalado no local correto (debian/hithere/usr/bin). 
A maneira certa de consertar isso é mudar debian/rules para que diga ao Makefile onde instalar as coisas. 
#!/usr/bin/make -f
%:
        dh $@

override_dh_auto_install:
        $(MAKE) DESTDIR=$$(pwd)/debian/hithere prefix=/usr install
É novamente um pouco de mágica, e para entendê-la você precisará saber como os Makefiles funcionam e os vários estágios de uma execução do debhelper. 
Por enquanto vou resumir dizendo que existe um comando que o debhelper executa que se encarrega de instalar os arquivos upstream, e este estágio é chamado de dh_auto_install. 
Precisamos sobrescrever este estágio, e fazemos isso com uma regra em debian/rules chamada override_dh_auto_install. 
A linha final no novo debian/rules é um pouco da tecnologia dos anos 1970 para invocar o Makefile upstream do debian/ rules com os argumentos corretos. 


Vamos tentar novamente


  • $ debuild -us -uc 
Ainda falha! 
install hithere /home/liw/debian-packaging-tutorial/x/hithere-1.0/debian/hithere/usr/bin


Agora estamos tentando instalar no lugar certo, mas ele não existe. Para corrigi-lo, precisamos informar as ferramentas de empacotamento para primeiro criar o diretório. 
Idealmente, o Makefile upstream criaria o próprio diretório, mas, neste caso, o(a) desenvolvedor(a) upstream estava com preguiça de fazê-lo. 


Outra correção


As ferramentas de empacotamento (especificamente a debhelper) fornecem uma maneira de fazer isso. 
usr/bin
usr/share/man/man1
A segunda linha cria o diretório para a página do manual. Vamos precisar disso mais tarde. Você deve ter cuidado ao manter esses arquivos *.dirs porque isso pode levar a diretórios vazios em versões futuras do seu pacote se os itens listados nesses arquivos não forem mais válidos. 


Vamos tentar mais uma vez


  • $ debuild -us -uc 
Agora a construção é bem-sucedida, mas ainda há alguns pequenos problemas. 
O debuild executa a ferramenta lintian, que verifica o pacote que foi compilado em busca de alguns erros comuns. Ele relata vários problemas para este novo pacote: 
Now running lintian...
W: hithere source: out-of-date-standards-version 3.9.0 (current is 3.9.1)
W: hithere: copyright-without-copyright-notice
W: hithere: new-package-should-close-itp-bug
W: hithere: wrong-bug-number-in-closes l3:#XXXXXX
Finished running lintian.


Esses erros eventualmente devem ser consertados, mas nenhum deles parece que será um problema para testar o pacote. Portanto, vamos ignorá-los por enquanto. 
Procure no diretório superior o pacote que foi compilado. 
  • $ ls .. 
hithere-1.0                  hithere_1.0-1_amd64.deb  hithere_1.0.orig.tar.gz
hithere_1.0-1_amd64.build    hithere_1.0-1.debian.tar.gz
hithere_1.0-1_amd64.changes  hithere_1.0-1.dsc




Etapa 5: Instalar o pacote


O comando a seguir instalará o pacote que você acabou de criar. 
NÃO execute-o em um computador, a menos que você não se importe de quebrá-lo. 
Máquinas virtuais são um bom lugar para fazer desenvolvimento. 
  • $ sudo dpkg -i ../hithere_1.0-1_amd64.deb 
[sudo] password for liw:
Selecting previously deselected package hithere.
(Reading database ... 154793 files and directories currently installed.)
Unpacking hithere (from ../hithere_1.0-1_amd64.deb) ...
Setting up hithere (1.0-1) ...
Processing triggers for man-db ...
liw@havelock$

Como testamos o pacote? Podemos executar o comando: 
  • $ hithere 
Ele funciona! 
Mas não está perfeito. Lembre-se, o lintian tinha coisas a dizer, o arquivo debian/copyright está vazio, etc. 
Temos um pacote que funciona, mas ainda não tem a alta qualidade que se espera de um pacote Debian. 


Conclusão


Depois de construir seus próprios pacotes, você eventualmente vai querer aprender como configurar seu repositório apt para que seu pacote seja fácil de instalar. A melhor ferramenta que conheço para isso é o reprepro. 
Para mais testes de seu pacote, dê uma olhada na ferramenta chamada piuparts (eu o escrevi originalmente, então é perfeito e nunca tem nenhum bug. er...) 
E, finalmente, se começar a fazer alterações no arquivo-fonte original upstream, você vai querer aprender sobre a ferramenta quilt. 
Outras coisas que você pode ler estão listadas na página Canto dos(as) Desenvolvedores(as) Debian (Debian Developers' Corner). 


Veja também


 CategoryPackaging