# 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`).

Para mais informações, consulte a seção de alterações (Seção 4.4) do Manual de Políticas do Debian.

## 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.

Observe que no Ubuntu, nós preenchemos o campo `Maintainer` com um endereço geral porque qualquer um pode alterar qualquer pacote (isto difere do Debian onde mudanças de pacotes são restritas para um indivíduo ou time). Os pacotes no Ubuntu devem ter os campos `Maintainer` preenchidos com `Ubuntu Developers <ubuntu-devel-discuss@lists.ubuntu.com>`. Se o mantenedor for alterado, o valor original deverá ser colocado no campo `XSBC-Original-Maintainer`. Isto pode ser feito automaticamente com o script `update-maintainer`, disponível no pacote `ubuntu-dev-tools`. Para informações detalhadas veja o Debian Maintainer Field spec na wiki do Ubuntu.

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

Para mais informações, consulte a seção controle de arquivo (Capítulo 5) do Manual de políticas do Debian.

## 2.3. O arquivo de direitos autorais

Este arquivo dá informações de direitos autorais para os arquivos fontes originais e para o pacote. Ubuntu e a Política Debian (Seção 12.5) requerem que cada pacote instale uma cópia textual de seus direitos autorais e licenças em `/usr/share/doc/$(package_name)/copyright`.

Geralmente, informações sobre direitos autorais são encontradas no arquivo `COPYING` do diretório de arquivos fonte do programa. Este arquivo deve incluir informações como os nomes dos autores e do empacotador, a URL da qual o arquivo fonte foi baixado, uma linha com o ano e o titular do direito autoral e o próprio texto de direito autoral. Um exemplo de padrão seria:

    Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
    Upstream-Name: Hello
    Source: ftp://ftp.example.com/pub/games

    Files: *
    Copyright: Copyright 1998 John Doe <jdoe@example.com>
    License: GPL-2+

    Files: debian/*
    Copyright: Copyright 1998 Jane Doe <packager@example.com>
    License: GPL-2+

    License: GPL-2+
     This program is free software; you can redistribute it
     and/or modify it under the terms of the GNU General Public
     License as published by the Free Software Foundation; either
     version 2 of the License, or (at your option) any later
     version.
     .
     This program is distributed in the hope that it will be
     useful, but WITHOUT ANY WARRANTY; without even the implied
     warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
     PURPOSE.  See the GNU General Public License for more
     details.
     .
     You should have received a copy of the GNU General Public
     License along with this package; if not, write to the Free
     Software Foundation, Inc., 51 Franklin St, Fifth Floor,
     Boston, MA  02110-1301 USA
     .
     On Debian systems, the full text of the GNU General Public
     License version 2 can be found in the file
     `/usr/share/common-licenses/GPL-2'.

Este exemplo segue o formato Legível por Máquina debian/direito autoral. Você é incentivado a usar este formato também.

## 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

Se seus tarballs estão no Launchpad, o arquivo `debian/watch` é um pouco mais complicado (veja questão 21146 e falha 231797 por que é assim). Nesse caso, use algo como:

    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/`

http://wiki.debian.org/Projects/DebSrc3.0 resume as informações adicionais sobre a mudança para o formato 3.0 de pacotes fonte.

Consulte o “man dpkg-source” e a seção sobre fonte/formato (Seção 5.21) <http://www.debian.org/doc/manuals/maint-guide/dother.en.html#sourcef>`_ do Guia dos novos mantenedores do Debian” para detalhes adicionais.

## 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.