NOME¶

debhelper - a suite de ferramentas debhelper

RESUMO¶

dh_* [-v] [-a] [-i] [--no-act] [-ppackage] [-Npackage] [-Ptmpdir]

DESCRIÇÃO¶

Debhelper é usado para ajuda-lo a compilar um pacote Debian. A filosofia por detrás de debhelper é disponibilizar uma colecção de ferramentas pequenas, simples e de fácil compreensão que são usadas em debian/rules para automatizar vários aspectos comuns da compilação de um pacote. Isto significa menos trabalho para si, o empacotador. Também significa, até certo ponto, que estas ferramentas podem ser alteradas se a política de Debian alterar, e os pacotes que as usam irão precisar apenas de uma recompilação para ficarem em conformidade com a nova política.

Um ficheiro debian/rules típico que usa debhelper irá chamar vários comandos debhelper em sequência, ou usar dh(1) para automatizar este processo. Em /usr/share/doc/debhelper/examples/ estão exemplos de ficheiros de regras que usam debhelper.

Para criar um novo pacote Debian usando o debhelper, você pode copiar um dos ficheiros de regras exemplo e edita-lo à mão. Ou pode tentar o pacote dh-make, o qual contém um comando dh_make que automatiza parcialmente o processo Para uma introdução mais gentil, o pacote Debian maint-guide contém um tutorial acerca de como fazer o seu primeiro pacote usando o debhelper.

Excepto onde a ferramenta explicitamente denota, caso contrário, todas as ferramentas do debhelper assumem que são corridas a partir do directório raiz de um pacote fonte descompactado. Isto é feito para que possam localizar e encontrar ficheiros como debian/control quando necessário.

COMANDOS DO DEBHELPER¶

Aqui está a lista dos comandos debhelper que você pode usar. Veja os seus manuais para documentação adicional.

FICHEIROS DE CONFIGURAÇÃO DO DEBHELPER¶

Muitos comandos do debhelper usam ficheiros em debian/ para controlar o que fazem. Para além dos comuns debian/changelog e debian/control, que estão em todos os pacotes, e não apenas aqueles que usam debhelper, alguns ficheiros adicionais podem ser usados para configurar o comportamento de comandos debhelper específicos. Estes ficheiros são chamados tipicamente debian/pacote.foo (onde pacote é claro, é substituído pelo nome do pacote no qual se está a actuar).

Por exemplo, dh_installdocs usa ficheiros chamados debian/package.docs para listar os ficheiros de documentação que ira instalar. Veja os manuais individuais dos comandos para detalhes acerca dos nomes e formatos dos ficheiros que usam. Geralmente, estes ficheiros irão listar ficheiros onde se vai actuar, um ficheiro por linha. Alguns programas no debhelper usam pares de ficheiros e destinos ou formatos ligeiramente mais complicados.

Nota se existir apenas um pacote binário listado em debian/control, então o debhelper irá usar debian/foo quando não existe nenhum ficheiro debian/package.foo. Nos níveis de compatibilidade antes de 15, este regressar também ocorre para o primeiro pacote binário listado em debian/control quando existem múltiplos pacotes binários. No entanto, é geralmente uma boa ideia manter o prefixo package. pois é mais explícito e também necessário quando se actualiza para compatibilidade 15.

Adicionalmente, existem alguns casos especiais onde o debhelper irá sempre cair para uma versão de menos-prefixo. Estes são casos como debian/copyright e debian/changelog, onde os ficheiros são geralmente usados e necessários para todos os pacotes binário.

Em alguns casos raros, você pode querer ter versões diferentes destes ficheiros para arquitecturas ou sistemas operativos diferentes. Se existirem ficheiros chamados debian/pacote.foo.ARCH ou debian/pacote.foo.OS, onde ARCH e OS são o mesmo que o resultado de "dpkg-architecture -qDEB_HOST_ARCH" / "dpkg-architecture -qDEB_HOST_ARCH_OS", então eles irão ser usados em preferência de outros ficheiros mais gerais.

Maioritariamente, estes ficheiros de configuração são usados para especificar listas de vários tipos de ficheiros. Documentação ou ficheiros exemplo para instalar, ficheiros para mover, e etc. Quando apropriado, em casos como estes, você pode usar caracteres "wildcard" de shell standard (classes de caracteres ? e * e [..]) nos ficheiros. Também pode meter comentários neste ficheiros; as linhas começadas com # são ignoradas.

A sintaxe destes ficheiros é mantida intencionalmente muito simples para os tornar fáceis de ler, compreender e modificar.

OPÇÕES DO DEBHELPER PARTILHADAS¶

As seguintes opções de linha de comandos são suportadas por todos os programas do debhelper.

-v, --verbose

Modo detalhado: mostra os comandos que modificam o directório de compilação de pacotes.

Note que o modo detalhado pode também gerar resultados de outros comandos "internos" que não afectam diretamente o directório de compilação de pacotes.

--no-act

Não faz nada na realidade. Se usado com -v, o resultado é que o comando mostra o que iria fazer.

-a, --arch

Actua em pacotes dependentes da arquitectura que devem ser compilados para a arquitectura de compilação DEB_HOST_ARCH.

-i, --indep

Actua em todos os pacotes independentes da arquitectura.

-ppacote, --package=pacote

Actua no pacote chamado pacote. Esta opção pode ser especifica várias vezes para fazer o debhelper operar num determinado conjunto de pacotes.

-s, --same-arch

Alias descontinuado de -a.

Esta opção foi removida no nível de compatibilidade 12.

-Npacote, --no-package=pacote

Não actua no pacote especificado mesmo se uma opção -a, -i, ou -p listarem o pacote como um em que se deverá actuar.

--remaining-packages

Não actua nos pacotes que já foram actuados antes por este comando do debhelper (isto é, se o comando estiver presente no debhelper log do pacote). Por exemplo, se você precisar de chamar o comando com opções especiais apenas para um par de pacotes binários, passe esta opção para a última chamada do comando para processar o resto dos pacotes com as definições predefinidas.

-Ptmpdir, --tmpdir=tmpdir

Usa tmpdir para directório de compilação de pacotes. A predefinição é debian/pacote

--mainpackage=pacote

Descontinuado: Esta opção não tem uso prático em compatibilidade 15 ou posterior pois o comportamento que afeta foi removido na compatibilidade 15.

Esta opção pouco usada muda o pacote que o debhelper considera o "pacote principal", isto é, o primeiro listado em debian/control, e aquele para o qual os ficheiros debian/foo podem ser usados em vez dos ficheiros debian/package.foo usuais.

-O=opção|bundle

Isto é usado pelo dh(1) quando se passa opções específicas do utilizador a todos os comandos que corre. Se o comando suportar a opção ou opções especificadas, irá fazer efeito. Se o comando não suportar a opção (ou alguma parte do conjunto de opções), será ignorado.

OPÇÕES COMUNS DO DEBHELPER¶

As seguintes opções de linha de comandos são suportadas por alguns programas do debhelper. Veja o manual de cada programa para uma explicação completa sobre o que cada opção faz.

-n

Não modifique os scripts postinst, postrm, etc.

-Xitem, --exclude=item

Exclui um item do processamento. Esta opção pode ser usada várias vezes, para excluir mais do que uma coisa. O item é tipicamente parte de um nome de ficheiro, e qualquer ficheiro que contenha o texto especificado será excluído.

-A, --all

Faz com que ficheiros ou outros itens que são especificados na linha de comandos tenham efeito em TODOS os pacotes em que se actua, e não apenas o primeiro.

OPÇÕES DO SISTEMA DE COMPILAÇÃO¶

As seguintes opções de linha de comandos são suportadas por todos os comandos dh_auto_* do debhelper. Estes programas suportam uma variedade de sistemas de compilação, e normalmente determinam heuristicamente qual usar, e como os usar. Você pode usar estes opções de linha de comandos para sobrepor o comportamento predefinido. Tipicamente estas são passadas ao dh(1), o qual passa-as a todos os programas dh_auto_*.

-Sbuildsystem, --buildsystem=buildsystem

Força a utilização do |<buildsystem> especificado, em vez de tentar auto-seleccionar um que pode ser aplicável para o pacote.

Passa none como buildsystem para desactivar a auto-selecção.

-Ddirectory, --sourcedir=directory, --sourcedirectory=directory

Assume que a árvore fonte do pacote original está no directório especificado em vez de estar no directório de nível de topo da árvore de pacotes fonte de Debian.

Aviso: A variante --sourcedir corresponde a uma opção de nome semelhante em dh_install e dh_missing (etc.) por razões históricas. Apesar de terem nomes semelhantes, elas têm objectivos muito distintos e em alguns casos podem causar erros quando esta variante é passada ao dh (quando então passada para todas as ferramentas).

-B[directory], --builddir[=directory], --builddirectory[=directory]

Activa a compilação da fonte e usa o directório especificado como o directório de compilação. Se o parâmetro directório for omitido, é escolhido o directório de compilação predefinido.

Se esta opção não for especificada, a compilação será feita por predefinição na fonte a menos que o sistema de compilação requeira ou prefira a compilação da árvore de fonte. Em tal caso, será usado o directório de compilação predefinido mesmo se --builddirectory não seja especificado.

Se o sistema de compilação preferir a compilação da árvore fonte mas ainda permitir a compilação da fonte, a última pode ser re-activada ao passar-lhe um caminho para um directório de compilação que é o mesmo que o caminho para o directório fonte.

--parallel, --no-parallel

Controla se devem ser usadas compilações paralelas se o sistema de compilação o suportar. O número de trabalhos paralelos é controlado pela variável de ambiente DEB_BUILD_OPTIONS ("Debian Policy, secção 4.9.1") durante a compilação. Também pode servir como um limite específico do sistema de compilação.

Se nenhuma destas opções for especificada, presentemente o debhelper usa por predefinição --parallel em modo compatibilidade 10 (ou posterior) e --no-parallel em caso contrário.

Como uma optimização, o dh irá tentar evitar passar estas opções aos sub-processos, se estas forem desnecessárias e as únicas opções a passar. De notar que isto acontece quando DEB_BUILD_OPTIONS não tem um parâmetro parallel (ou o seu valor é 1).

--max-parallel=máximo

Esta opção implica --parallel e permite mais limitação ao número de trabalhos que podem ser usados numa compilação paralela. Se a compilação do pacote é conhecida por apenas funcionar em certos níveis de concorrência, você pode definir isto para o nível máximo que é sabido funcionar, ou que deseje suportar.

De notar que, definir o máximo para 1 é efectivamente o mesmo que usar --no-parallel.

--reload-all-buildenv-variables

Por predefinição, o dh(1) irá computar várias variáveis de ambiente (ex. ao usar dpkg-buildflags(1)) e guarda-los em cache para evitar que todas as ferramentas dh_auto_* os recompute.

Quando se passa esta opção, a ferramenta dh_auto_* concreta irá ignorar a cache de dh(1) e re-despoletar uma recompilação destas variáveis. Isto é útil nos casos muito raros onde o pacote precisa de fazer múltiplas compilações mas com diferentes opções ...FLAGS. Um exemplo concreto seria precisar de alterar o parâmetro -O em CFLAGS na segunda compilação:

    export DEB_CFLAGS_MAINT_APPEND=-O3
    %:
        dh $@
    override_dh_auto_configure:
        dh_auto_configure -Bbuild-deb ...
        DEB_CFLAGS_MAINT_APPEND=-Os dh_auto_configure \
           --reload-all-buildenv-variables -Bbuild-udeb ...
    

Sem --reload-all-buildenv-variables na segunda chamada ao dh_auto_configure(1), a alteração em DEB_CFLAGS_MAINT_APPEND seria ignorada pois dh_auto_configure(1) iria usar o valor em cache de <CFLAGS> definido por dh(1).

Esta opção está apenas disponível com debhelper (>= 12.7~) quando o pacote usar nível de compatibilidade 9 ou posterior.

--list, -l

Lista todos os sistemas de compilação suportados pelo debhelper neste sistema. A lista inclui ambos sistemas de compilação predefinidos e de terceiros (marcados como tal). Também mostra qual o sistema de compilação será seleccionado automaticamente, ou qual está especificado manualmente com a opção --buildsystem.

NÍVEIS DE COMPATIBILIDADE¶

De tempos a tempos, precisam de ser feitas grandes alterações no debhelper que não compatíveis com as versões anteriores, para o manter limpo e bem construído quando as necessidades alteram e o seu autor ganha mais experiência. Para prevenir que tais grandes alterações danifiquem os pacotes existentes, foi introduzido o conceito de níveis de compatibilidade no debhelper. Você deve dizer ao debhelper qual o nível de compatibilidade que ele deve usar, e ele modifica o seu comportamento de várias maneiras.

No debhelper actual, você pode especificar o nível de compatibilidade em debian/control ao adicionar um Build-Depends no pacote debhelper-compat. Por exemplo, para usar modo v13, assegure que debian/control tem:

  Build-Depends: debhelper-compat (= 13)

Isto também serve como uma dependência de compilação de versão apropriada numa versão suficiente do pacote debhelper, assim você não precisa de especificar uma dependência de compilação de versão separada no pacote debhelper a menos que precise de um lançamento pontual específico do debhelper (tal como para a introdução de uma nova funcionalidade ou correcção de bug dentro de um nível de compatibilidade).

Note que o debhelper não fornece debhelper-compat para os níveis de compatibilidade experimental ou beta; os pacotes que experimentem com esses níveis de compatibilidade devem meter o nível de compatibilidade no campo X-DH-Compat da estrofe Source no ficheiro debian/control (ou, se apenas para comandos selecionados, na variável de ambiente DH_COMPAT).

Historicamente, o debhelper requeria o nível de compatibilidade especificado no ficheiro debian/compat, e o debhelper até à versão 14 suporta isto para compatibilidade com as versões anteriores Para usar este método, o ficheiro debian/compat deve conter o nível de compatibilidade como um número singular, e nenhum outro conteúdo. Se você especificar o nível de compatibilidade neste método, o seu pacote vai também precisar duma dependência de compilação baseada em versão de uma versão do pacote debhelper igual (ou superior) ao nível de compatibilidade que o seu pacote usa. Assim, se você especificar o nível de compatibilidade 13 em debian/compat, assegure-se que debian/control contém:

  Build-Depends: debhelper (>= 13~)

Note que você deve usar exactamente um método para especificar o nível de compatibilidade predefinido do debhelper do pacote. Sempre que possível, é recomendado a build-dependency do debhelper-compat.

Se necessário, a variável de ambiente DH_COMPAT pode ser usada para sobrepor o nível de compatibilidade para um dado comando. Esta funcionalidade é maioritariamente útil seja para actualizar temporariamente alguns comandos para um novo nível de compatibilidade ou manter alguns comandos num nível de compatibilidade inferior. Esta funcionalidade é melhor ser usada com moderação pois introduz efectivamente casos-especiais no ficheiro debian/rules que podem ser surpreendentes para maintainers ou revisores (ou, a longo prazo, para si).

A menos que seja indicado o contrário, toda a documentação do debhelper assume que você está a usar o nível de compatibilidade mais recente, e na maioria dos casos não indica se o comportamento é diferente num nível de compatibilidade anterior, portanto se não está a usar o nível de compatibilidade mais recente, você é aconselhado a procurar em baixo por notas acerca do que é diferente nos níveis de compatibilidade anteriores.

NOTAS¶

  my $temp="set -e\nset -- @ARGV\n" . << 'EOF';
  #DEBHELPER#
  EOF
  if (system($temp)) {
     my $exit_code = ($? >> 8) & 0xff;
     my $signal = $? & 0x7f;
     if ($exit_code) {
         die("The debhelper script failed with error code: ${exit_code}");
     } else {
         die("The debhelper script was killed by signal: ${signal}");
     }
  }

AMBIENTE¶

Esta secção descreve algumas das variáveis de ambiente que influenciam o comportamento do debhelper ou de quem o debhelper interage.

É importante notar que estas que estas têm de ser mesmo variáveis de ambiente de modo a afectarem o comportamento do debhelper (e não simplesmente variáveis do Makefile). Para as especificar correctamente em debian/rules, assegure-se de lhes fazer "export". Por exemplo, "export DH_VERBOSE"

DH_VERBOSE

Definir para um valor não-vazio para activar o modo detalhado. Por favor veja a opção -v / --verbose para detalhes.

DH_QUIET

Definir para um valor não-vazio para activar o modo silencioso. O Debhelper não irá escrever os comandos a chamar o sistema de compilação do autor nem o dh irá escrever quais sub-comandos são chamados e dependendo do sistema de compilação do autor, poderá também tornar isso mais silencioso. Isto facilita a identificação de mensagens importantes mas torna os resultados inúteis como relatório do buildd.

É ignorado se DH_VERBOSE estiver também definido ou se for passado -v / --verbose.

DH_COMPAT

Especifica temporariamente em que nível de compatibilidade o debhelper deve correr, sobrepondo o nível de compatibilidade predefinido do pacote fonte.

DH_NO_ACT

Defina para 1 para activar o modo no-act.

DH_OPTIONS

Todas as ferramentas debhelper irão processar os argumentos de linha de comandos listados nesta variável antes de qualquer opção de comando (como se eles fossem anexados aos argumentos de linha de comandos). Infelizmente, algumas ferramentas disponibilizadas por terceiros podem não suportar esta variável e irão ignorar estes argumentos de linha de comandos.

Quando se usa dh(1), podem-se passar opções que irão ser passadas a cada comando do debhelper, o que é geralmente melhor do que usar DH_OPTIONS.

DH_ALWAYS_EXCLUDE

Se definido, isto adiciona o valor que está definido na variável às opções -X de todos os comandos que suportam a opção -X. Ainda mais, o dh_builddeb irá fazer rm -rf a tudo o que corresponda a esse valor na sua árvore de compilação do pacote.

Isto pode ser útil se você está a fazer uma compilação a partir de uma árvore fonte CVS, que no caso definindo DH_ALWAYS_EXCLUDE=CVS irá prevenir que quaisquer directórios CVS se esgueirem para o pacote que está a compilar. Ou, se um pacote tem um tarball de fonte que (não inteligentemente) inclui directórios CVS, você pode querer exportar DH_ALWAYS_EXCLUDE=CVS em debian/rules, para o fazer ter efeito onde o seu é compilado.

Várias coisas a excluir podem ser separadas com "dois pontos", como em DH_ALWAYS_EXCLUDE=CVS:.svn

DH_EXTRA_ADDONS

Se definido, isto adiciona os addons especificados do dh para serem corridos nos lugares apropriados na sequência de comandos. Isto é equivalente a especificar o addon a correr coma bandeira --with no ficheiro debian/rules file. Qualquer chamada --without que especifique um addon nesta variável de ambiente não será executada.

Isto destina-se a ser usado por downstreams ou configurações locais especificas que requeiram a execução dum addon do debhelper durante múltiplas compilações sem terem que aplica patch a um grande número de ficheiros de regras. Se de todo possível, isto deve ser evitado em favor de uma bandeira --with no ficheiro rules.

DH_COLORS, DPKG_COLORS

Estas variáveis podem ser usadas para controlar se os comandos do debhelper devem usar cores nos resultados textuais. Podem ser definidas para "always", "auto" (a predefinição), ou "never".

Note que DPKG_COLOR também afecta um número de ferramentas relacionadas ao dpkg e o debhelper usa-o na suposição que você quer a mesma definição de cor para o dpkg e debhelper. Na hipótese de você querer definição de cor diferente para o debhelper, pode usar DH_COLORS em vez disso ou em adição a DPKG_COLORS.

NO_COLOR

Se não for fornecido um pedido específico para cor (ex. DH_COLORS e DPKG_COLORS estão ambos não-definidos), a presença desta variável de ambiente faz com que a definição de cor predefinida seja "never".

A variável é definida de acordo com <https://no-color.org/>. Neste projecto, as variáveis de ambiente (tais como DH_COLORS) são consideradas um requisito explícito para cor.

CFLAGS, CPPFLAGS, CXXFLAGS, OBJCFLAGS, OBJCXXFLAGS, GCJFLAGS, FFLAGS, FCFLAGS, LDFLAGS

Por predefinição (em qualquer nível de compatibilidade não-abandonado). o debhelper irá automaticamente definir estas flags ao usar dpkg-buildflags(1), quando não estiverem definidas. Se você precisar de modificar as flags predefinidas, por favor use as funcionalidades de dpkg-buildflags(1) para o fazer (ex. DEB_BUILD_MAINT_OPTIONS=hardening=all ou DEB_CPPFLAGS_MAINT_APPEND=-DCUSTOM_MACRO=true) em vez de definir a variável concreta directamente.

HOME, XDG_*

Em compatibilidade 13 e posterior, estas variáveis de ambiente são reiniciadas antes de invocar o sistema de compilação do autor via ajudantes do dh_auto_*. As variáveis HOME (todos os ajudantes dh_auto_*) e XDG_RUNTIME_DIR (apenas dh_auto_test) irão ser definidas para um directório gravável. Todas as restantes variáveis e XDG_RUNTIME_DIR (excepto para durante dh_auto_test) irão ser limpas.

O directório HOME será criado como um directório vazio mas ele será reutilizado entre chamadas a dh_auto_*. Qualquer conteúdo irá persistir até ser explicitamente apagado ou dh_clean.

DEB_BUILD_OPTIONS

Por favor veja "Bandeiras suportadas em DEB_BUILD_OPTIONS" para esta variável de ambiente.

Por favor note que esta variável não deve ser alterada por maintainers de pacote dentro de debian/rules para mudar o comportamento do debhelper. Em vez disso, onde o maintainer do pacote precisar destas funcionalidades, eles devem procurar desactivar a funcionalidade relevante directamente (ex. ao sobrepor as ferramentas concretas).

DEB_BUILD_MAINT_OPTIONS

Esta é uma variável de ambiente especifica do dpkg (veja por ex. dpkg-buildflags(1)). A suite de ferramentas do debhelper ignora-a em silêncio.

Está documentada aqui porque tem um nome semelhante a DEB_BUILD_OPTIONS, o que faz com que algumas pessoas assumam em erro que o debhelper também vai reagir a esta variável.

VEJA TAMBÉM¶

debhelper-compat-upgrade-checklist(7)

Lista de níveis de compatibilidade suportados e uma lista de verificação de actualização para cada um deles.

/usr/share/doc/debhelper/examples/

Um conjunto de ficheiros debian/rules exemplo que usam debhelper.

<http://joeyh.name/code/debhelper/>

Sítio web do debhelper.

AUTOR¶

Joey Hess <joeyh@debian.org>

TRADUÇÃO¶

Américo Monteiro

Se encontrar algum erro na tradução deste documento, por favor comunique para Américo Monteiro a_monteiro@gmx.com ou Equipa Debian de Tradução Portuguesa traduz@debianpt.org.