Ubuntu logo

Packaging Guide

2. Visão básica do diretório debian/

Este artigo explicará sucintamente sobre os diferentes arquivos contidos no diretório debian/, importantes ao empacotamento Ubuntu. Os mais importantes são changelog, control, copyright e rules. Eles são obrigatórios para todos os pacotes. Diversos arquivos adicionais dentro de debian/ podem ser usados para personalizar e configurar o comportamento do pacote. Alguns desses arquivos são abordados neste artigo, o que não significa que esta seja a lista completa.

2.1. O registro de mudanças

Este arquivo é, como seu nome implica, uma listagem das mudanças feitas em cada versão. Tem um formato específico que dá o nome do pacote, versão, distribuição, mudanças e quem fez as mudanças em um momento determinado. Se você tiver uma chave GPG (see: Getting set up), certifique-se de usar no changelog o mesmo nome e endereço de e-mail da chave. O documento a seguir é um modelo de changelog:

package (version) distribution; urgency=urgency

 * change details
  - more change details
 * even more change details

-- maintainer name <email address>[two spaces]  date

O formato (principalmente da data) é importante. A data deve estar no formato da RFC 5322, o qual pode ser obtido pelo uso do comando date -R. Por conveniência, o comando dch pode ser usado para editar o arquivo de mudanças. Ele atualizará a data automaticamente.

Pontos menos importantes são indicados por um traço “-”, enquanto os pontos mais importantes usam um asterisco “*”.

Se você estiver empacotando do zero, dch --create (dch está no pacote devscripts) criará um debian/changelog padrão para você.

Aqui está um exemplo de arquivo “changelog” para hello:

hello (2.8-0ubuntu1) trusty; urgency=low

  * New upstream release with lots of bug fixes and feature improvements.

-- Jane Doe <packager@example.com>  Thu, 21 Oct 2013 11:12:00 -0400

Observe que a versão tem um -0ubuntu1 acrescentado a ela, isso é a revisão da distro, usada para que o empacotamento possa ser atualizado (para corrigir falhas, por exemplo) com novos envios para a mesma versão de lançamento do fonte.

Ubuntu e Debian são ligeiramente diferentes nos esquemas de versionamento de pacotes para evitar pacotes conflitantes com a mesma versão de código fonte. Se um pacote Debian foi mudado no Ubuntu, ele terá ubuntuX (onde X é o número da revisão Ubuntu) acrescentado ao final da versão Debian. Então, se o pacote Debian hello 2.6-1 sofresse alterações pelo Ubuntu, sua versão seria 2.6-1ubuntu1. Se um pacote para determinada aplicação não existir no Debian, então a revisão Debian será 0 (exemplo, 2.6-0ubuntu1).

For further information, see the changelog section (Section 4.4) of the Debian Policy Manual.

2.2. O arquivo de controle

O arquivo control contém a informação que os gerenciadores de pacotes (tais como apt-get, synaptic e adept) usam, como dependências em tempo de construção de pacote, informações sobre o mantenedor e muito mais.

Para o pacote hello do Ubuntu, o arquivo control parece alguma coisa assim:

Source: hello
Section: devel
Priority: optional
Maintainer: Ubuntu Developers <ubuntu-devel-discuss@lists.ubuntu.com>
XSBC-Original-Maintainer: Jane Doe <packager@example.com>
Standards-Version: 3.9.5
Build-Depends: debhelper (>= 7)
Vcs-Bzr: lp:ubuntu/hello
Homepage: http://www.gnu.org/software/hello/

Package: hello
Architecture: any
Depends: ${shlibs:Depends}
Description: The classic greeting, and a good example
 The GNU hello program produces a familiar, friendly greeting. It
 allows non-programmers to use a classic computer science tool which
 would otherwise be unavailable to them. Seriously, though: this is
 an example of how to do a Debian package. It is the Debian version of
 the GNU Project's `hello world' program (which is itself an example
 for the GNU Project).

O primeiro parágrafo descreve o pacote fonte, incluindo a lista de pacotes necessários para construir o pacote a partir do fonte no campo Build-Depends. Também contém algumas meta-informações tais como o nome do mantenedor, a versão de Política Debian que cumpre tal pacote, a localização do repositório de controle de versão de empacotamento e a página de internet do programa original.

Note that in Ubuntu, we set the Maintainer field to a general address because anyone can change any package (this differs from Debian where changing packages is usually restricted to an individual or a team). Packages in Ubuntu should generally have the Maintainer field set to Ubuntu Developers <ubuntu-devel-discuss@lists.ubuntu.com>. If the Maintainer field is modified, the old value should be saved in the XSBC-Original-Maintainer field. This can be done automatically with the update-maintainer script available in the ubuntu-dev-tools package. For further information, see the Debian Maintainer Field spec on the Ubuntu wiki.

Cada parágrafo adicional descreve um pacote binário a ser construído.

For further information, see the control file section (Chapter 5) of the Debian Policy Manual.

2.4. O arquivo de regras

O último arquivo que devemos olhar é o rules. Ele faz todo trabalho de criar nosso pacote. Ele é um Makefile com regras para compilar e instalar a aplicação, então criar o arquivo .deb a partir dos arquivos instalados. Ele também tem uma regra para limpar todos os arquivos de construção para que você possa apenas com os arquivos fonte.

Aqui é uma versão simplificada do arquivo de regras criado pelo dh_make (que pode ser encontrado no pacote dh-make):

#!/usr/bin/make -f
# -*- makefile -*-

# Uncomment this to turn on verbose mode.
#export DH_VERBOSE=1

%:
       dh  $@

Vamos passar com mais detalhes sobre este arquivo. O que ele faz é passar por todas as regras de construção que debian/rules é chamado com argumentos para /usr/bin/dh, no qual ele mesmo chamará todos os comandos dh_* necessários.

“dh” executa uma sequência de comandos debhelper. As sequências suportadas correspondem às regras de um arquivo “debian/rules”: “build”, “clean”, “install”, “binary-arch”, “binary-indep” e “binary”. Para ver quais comandos são executados em cada regra, execute:

$ dh binary-arch --no-act

Comandos na sequência binary-indep são passados com a opção “-i” para garantir que funcionarão apenas em pacotes binário independentes e comandos na sequência binary-arch são passados com a opção “-a” para garantir que funcionarão apenas em pacotes dependentes de arquiteturas.

Cada comando debhelper gravará em debian/package.debhelper.log quando executado com sucesso. (O qual dh_clean apaga.) então dh pode dizer quais comandos foram executados, para quais pacotes e assim evitar rodar os mesmos comandos novamente.

Cada vez que o dh roda, ele examina o registro e procura pelo último comando registrado que está numa sequência especificada. Então, ele continua com o comando seguinte. As opções –until`, --before, --after e --remaining podem sobrescrever este comportamento.

Se o “debian/rules” contiver um alvo com um nome como “override_dh_command”, então quando ele receber este comando o “dh” executará aquele alvo a partir do arquivo rules, em vez de executar o comando real. A substituição do alvo pode então executar o comando com opções adicionais, ou executar comandos totalmente diferentes. (Note que para usar este recurso, você deve construir as dependências com o debhelper 7.0.50 ou superior.)

Veja em /usr/share/doc/debhelper/examples/ e man dh para mais exemplos. Veja também a seção de regras (Seção 4.9) do Manual de Políticas do Debian.

2.5. Arquivos adicionais

2.5.1. O arquivo de instalação

O arquivo install` é usado por ``dh_install para instalar arquivos no pacote binário. Ele possui dois casos de uso padrão:

  • Para arquivos de instalação dentro do seu pacote que não são manipulados pelo sistema de construção do upstream.

  • Dividindo um grande e único pacote fonte em múltiplos pacotes binários.

No primeiro caso, o arquivo install deveria ter uma linha por arquivo instalado, especificando ambos arquivos e o local da instalação. Por exemplo, o seguinte arquivo install instalaria o script foo na fonte do pacote do diretório raiz para usr/bin e um atalho no diretório debian para usr/share/applications:

foo usr/bin
debian/bar.desktop usr/share/applications

When a source package is producing multiple binary packages dh will install the files into debian/tmp rather than directly into debian/<package>. Files installed into debian/tmp can then be moved into separate binary packages using multiple $package_name.install files. This is often done to split large amounts of architecture independent data out of architecture dependent packages and into Architecture: all packages. In this case, only the name of the files (or directories) to be installed are needed without the installation directory. For example, foo.install containing only the architecture dependent files might look like:

usr/bin/
usr/lib/foo/*.so

Enquanto foo-common.install contendo apenas o arquivo independente da arquitetura pode parecer como:

/usr/share/doc/
/usr/share/icons/
/usr/share/foo/
/usr/share/locale/

Isso criará dois pacotes binários, foo e foo-common. Ambos necessitam de seu próprio parágrafo em debian/control.

Veja “man dh_install” e a “seção de arquivo de instalação (Seção 5,11) <http://www.debian.org/doc/manuals/maint-guide/dother.en.html#install>”_ do Novo Guia dos Mantenedores do Debian para detalhes adicionais.

2.5.2. O arquivo watch

O arquivo “debian/watch” nos permite verificar automaticamente a existência de novas versões no upstream usando a ferramenta “uscan” encontrada no pacote “devscripts”. A primeira linha do arquivo watch deve ser a versão do formato (3, quando este texto foi escrito), enquanto que as linhas seguintes contém quaisquer URLs a serem analisadas. Por exemplo:

version=3

http://ftp.gnu.org/gnu/hello/hello-(.*).tar.gz

Ao executar uscan no diretório raiz dos fontes irá comparar o número da versão no upstream em debian/changelog com a última versão disponível no upstream. Se uma nova versão upstream for encontrada, ela será baixada automaticamente. Por exemplo:

$ uscan
hello: Newer version (2.7) available on remote site:
  http://ftp.gnu.org/gnu/hello/hello-2.7.tar.gz
  (local version is 2.6)
hello: Successfully downloaded updated package hello-2.7.tar.gz
    and symlinked hello_2.7.orig.tar.gz to it

If your tarballs live on Launchpad, the debian/watch file is a little more complicated (see Question 21146 and Bug 231797 for why this is). In that case, use something like:

version=3
https://launchpad.net/flufl.enum/+download http://launchpad.net/flufl.enum/.*/flufl.enum-(.+).tar.gz

Para maiores informações, veja man uscan e a seção do arquivo watch (Seção 4.11) do Manual de políticas do Debian.

Para uma lista dos pacotes cujo arquivo “watch” relata não estarem sincronizados com o upstream, consulte Ubuntu External Health Status.

2.5.3. O arquivo source/format

Este arquivo indica o formato do pacote fonte. Ele deve conter uma única linha indicando o formato desejado:

  • 3.0 (native) para pacotes nativos do Debian (sem versão do upstream)

  • 3.0 (quilt) para pacotes com um tarball separado do upstream

  • 1.0 para pacotes que desejam declarar explicitamente o formato padrão

Atualmente, o formato fonte do pacote será padronizada para 1.0 se o arquivo não existir. Você pode fazer isso explicitamente no arquivo/formato fonte. Se você escolher não utilizar este arquivo para definir o formato fonte, o Lintian irá lhe avisar sobre o arquivo ausente. Este aviso é apenas uma informação e pode ser ignorado com segurança.

Você é encorajado a usar o mais recente formato de fonte, o 3.0. Ele fornece uma quantia de novos recursos:

  • Suporte para formatos de compressão adicionais: bzip2, lzma e xz

  • Suporte para múltiplos tarballs do upstream

  • Não é necessário reempacotar o tarball do upstream para retirar o diretório debian

  • Mudanças específicas do Debian não são armazenadas em um único .diff.gz, mas em múltiplos patches compatíveis com o quilt em debian/patches/

https://wiki.debian.org/Projects/DebSrc3.0 summarizes additional information concerning the switch to the 3.0 source package formats.

See man dpkg-source and the source/format section (Section 5.21) of the Debian New Maintainers’ Guide for additional details.

2.6. Recursos adicionais

In addition to the links to the Debian Policy Manual in each section above, the Debian New Maintainers’ Guide has more detailed descriptions of each file. Chapter 4, “Required files under the debian directory” further discusses the control, changelog, copyright and rules files. Chapter 5, “Other files under the debian directory” discusses additional files that may be used.