DH(1)

NOME
dh - sequenciador de comandos do debhelper

RESUMO
dh sequence [--with addon[,addon ...]] [--list] [debhelper opções]

DESCRIÇÃO
dh corre uma sequência de comandos do debhelper. As sequências suportadas correspondem aos alvos de um ficheiro debian/rules: build-arch, build-indep, build, clean, install-indep, install-arch, install, binary-arch, binary-indep, e binary.

ALVOS DE SOBREPOSIÇÃO E HOOK
Um ficheiro debian/rules que use dh pode sobrepor o comando que é executado em qualquer passo numa sequência, ao se definir um alvo de sobreposição. É também possível injectar um comando antes ou depois de qualquer passo sem afectar o próprio passo.

  Injectando comandos antes e depois de um passo
Nota: Esta funcionalidade requer debhelper 12.8 ou posterior e o pacote tem de usar modo de compatibilidade 10 ou posterior.

Para injectar comandos antes de dh_command, adicione um alvo chamado execute_before_dh_command aos ficheiros rules. De modo semelhante, se precisar de injectar comandos após dh_command, adicione o alvo execute_after_dh_command. Ambos alvos podem ser usados para o mesmo dh_command e também mesmo que o comando seja sobreposto (como descrito em "Sobrepor um comando" em baixo).

Quando estes alvos estão definidos, dh irá chamar os alvos respetivamente antes ou depois de quando iria invocar dh_command (ou os seus alvos de sobreposição).

  Sobrepor um comando
Para sobrepor o dh_command, adicione um alvo chamado override_dh_command ao ficheiro de regras. Em vez de correr normalmente dh_command, o dh irá chamar esse alvo. O alvo de sobreposição pode depois correr o comando com opções adicionais, ou em vez disso correr comandos completamente diferentes. Veja exemplos em baixo.

A partir do debhelper versão 13.25, os alvos de sobreposição (mas não os outros alvos de hook) podem usar a variável de makefile $(DH_OVERRIDDEN_COMMAND) para correr o comando a ser sobreposto exatamente como estava. Isto pode ser útil se você quiser adicionar opções extra como:

    # Estes exemplos requerem debhelper/13.25 ou posterior
    override_dh_auto_configure:
        $(DH_OVERRIDDEN_COMMAND) -- --with-foo --with-bar

    override_dh_auto_test:
        fakeroot $(DH_OVERRIDDEN_COMMAND)

Note que esta variável é apenas útil se quiser correr o comando original com algo extra. Se você desejar apenas correr o comando original sem alterações, use execute_before_dh_foo ou/e execute_after_dh_foo em vez disto.

Tenha cuidado com esta variável. Em versões antigas do debhelper, a variável não está definida, o que causa que expanda para nada. Dependendo do que mais está na linha, isto pode não causar uma falha onde seria esperada.

Adicionalmente, tenha cuidado com erros de escrita. O Inglês tem uma irregularidade gramatical aqui, onde override tem um d (nome de alvo; imperativo) enquanto que OVERRIDDEN tem dois Ds (nome de variável; partícula no passado). É infeliz e confuso, mas é assim que a gramática de Inglês funciona.

  Alvos de sobreposição e hook dependentes/independentes da arquitectura
Os alvos de sobreposição e hook também podem ser definidos para correr apenas quando se compila pacotes dependentes ou independentes da arquitectura. Use alvos com nomes como override_dh_command-arch e execute_after_dh_command-indep.

Esta funcionalidade está disponível desde debhelper 8.9.7 (para alvos de sobreposição) e 12.8 (para alvos hook).

  Alvos completamente vazios
Como uma optimização especial, dh irá saltar um alvo se este estiver completamente vazio e não depender de nenhum outro alvo. Isto é muito útil para alvos de sobreposição, onde o comando irá simplesmente ser saltado sem a sobrecarga de invocar um alvo fantoche.

Note que o alvo tem de estar completamente vazio para isto funcionar:

     # Skip dh_bar - the good and optimized way
     # Some rationale for skipping dh_bar goes here
     override_dh_bar:

     # Skip dh_foo - the slow way
     override_dh_foo:
        # Some rationale for skipping dh_foo goes here
        # (these comments causes a dummy target to be run)

  Verificando se os alvos são apanhados pelo dh
A partir do debhelper 13.10, você pode usar dh_assistant(1) para ver quais alvos de sobreposição e hook irão ser vistos pelo dh. Aqui está um exemplo de execução do dh_assistant(1) juntamente com os seus resultados:

    $ dh_assistant detect-hook-targets
    {
       "commands-not-in-path": [
          "dh_foo"
       ],
       "hook-targets": [
          {
             "command": "dh_strip_nondeterminism",
             "is-empty": true,
             "package-section-param": null,
             "target-name": "override_dh_strip_nondeterminism"
          },
          {
             "command": "dh_foo",
             "is-empty": false,
             "package-section-param": "-a",
             "target-name": "override_dh_foo-arch"
          }
       ]
    }

O commands-not-in-path é útil para detetar enganos nos nomes de alvo hook. Um valor não-vazio implica que um ou mais alvos hook estão relacionados com um comando que ou não está instalado ou não existe de todo um comando com esse nome. Geralmente é de valor verificar bem estes casos.

Adicionalmente, o atributo is-empty para cada alvo hook pode ser usado para se ver se um alvo hook despoleta a optimização "Completely empty targets".

Se você está interessado noutros atributos, por favor leia o dh_assistant(1) para detalhes.

Verificando se os alvos são apanhados pelo dh (quando o debhelper é mais antigo que 13.10)

Em versões antigas do debhelper, você tem de usar dh com --no-act. Você pode usar o seguinte comando como um exemplo:

    $ dh binary --no-act | grep dh_install | head -n5
         dh_installdirs
         dh_install
         debian/rules execute_after_dh_install
         dh_installdocs
         dh_installchangelogs

O debian/rules execute_after_dh_install no resultado, que assinala que dh registou um alvo execute_after_dh_install e o iria correr directamente após dh_install(1).

Note que "Alvos completamente vazios" irão ser omitidos na listagem em cima. Isto torna um pouco mais difícil detectar se você está a olhar para a omissão de um nome de comando. Mas caso contrário, o princípio continua o mesmo.

  Ressalvas com alvos hook e condicionais makefile
If you choose to wrap a hook target in makefile conditionals, please be aware that dh computes all the hook targets ahead of time and caches the result for that run. Furthermore, the conditionals will be invoked again when dh calls the hook target later and will assume the answer did not change.

A análise e cache ocorre muitas vezes entes de dh saber se vai compilar pacotes arch:any (-a) ou/e arch:all (-i), o que pode produzir resultados confusos - especialmente quando dh_listpackages(1) é parte da condicional.

A maioria dos problemas podem ser evitados ao tornar o alvo hook incondicional e depois ter o "corpo" a ser parcial ou completamente condicional. Com exemplo:

      # SIMPLE: It is well-defined what happens.  The hook target
      # is always considered.  The "maybe run this" bit is
      # conditional but dh_foo is definitely skipped.
      #
      # Note: The conditional is evaluated "twice" where its
      # influences what happens.  Once when dh check which hook
      # targets exist and once when the override_dh_foo hook target
      # is run.  If *either* times return false, "maybe run this"
      # is skipped.
      override_dh_foo:
      ifneq (...)
          maybe run this
      endif

      # SIMPLE: This is also well-defined.  The hook target is always
      # run and dh_bar is skipped.  The "maybe run this" bit is
      # conditional as one might expect.
      #
      # Note: The conditional is still evaluated multiple times (in
      # different process each time).  However, only the evaluation
      # that happens when the hook target is run influences what
      # happens.
      override_dh_bar:
          : # Dummy command to force the target to always be run
      ifneq (...)
          maybe run this
      endif

      # COMPLICATED: This case can be non-trivial and have sharp edges.
      # Use at your own peril if dh_listpackages in the conditional.
      #
      # Here, either dh_baz is run normally OR "maybe run this" is run
      # instead.
      #
      # And it gets even more complicated to reason about if dh needs to
      # recurse into debian/rules because you have an "explicit"
      # standard target (e.g. a "build-arch:" target separate from "%:").
      ifneq (...)
      override_dh_baz:
          maybe run this
      endif

Estas receitas são também relevantes para alvos de dependência condicional, os quais são muitas vezes vistos numa variante do seguinte exemplo:

      COND_TASKS =
      ifneq (...)
      COND_TASKS += maybe-run-this
      endif
      ...

      maybe-run-this:
          ...

      # SIMPLE: It is well-defined what happens.  Either the
      # $(COND_TASKS) are skipped or run.
      #
      # Note: The conditional is evaluated "twice" where its
      # influences what happens.  Once when dh check which hook
      # targets exist and once when the override_dh_foo hook target
      # is run.  If *either* times return false, $(COND_TASKS)
      # is skipped.
      override_dh_foo: $(COND_TASKS)

      # SIMPLE: This is also well-defined.  The hook target is always
      # run and dh_bar is skipped.  The $(COND_TASKS) bit is
      # conditional as one might expect.
      #
      # Note: The conditional is still evaluated multiple times (in
      # different process each time).  However, only the evaluation
      # that happens when the hook target is run influences what
      # happens.
      override_dh_bar: $(COND_TASKS)
          : # Dummy command to force the target to always be run

      # COMPLICATED: This case can be non-trivial and have sharp edges.
      # Use at your own peril if dh_listpackages in the conditional.
      #
      ifneq (...)
      override_dh_baz: $(COND_TASKS)
      endif

Em caso de dúvida, escolha o caso SIMPLE relevante nos exemplos em cima que corresponda à sua necessidade.

OPÇÕES

--with addon[,addon ...]
    Adiciona os comandos debhelper especificados pelo addon indicado aos lugares apropriados na sequência de comandos que é executada. Esta opção pode ser repetida mais do que uma vez, ou pode-se listar múltiplos addons separados por vírgulas. Isto é usado quando existe um pacote de terceiros que disponibiliza comandos do debhelper. Veja o ficheiro PROGRAMMING para documentação acerca da sequência de interface de addons.

    Uma relação Build-Depends no pacote dh-sequence-addon implica um addon --with. Isto evita a necessidade de um --with explícito em debian/rules que apenas duplica o que já está declarado via dependências de compilação em debian/control. A relação pode (desde 12.5) ser feita opcionalmente via por exemplo, build-profiles. Isto permite-lhe facilmente desativar um addon que é apenas útil com certos perfis (ex. para facilitar bootstrapping).

    Desde o debhelper 12.5, que addons podem ser também activados em modo indep-only (via Build-Depends-Indep) ou modo arch-only (via Build-Depends-Arch). Tais addons estão apenas activos na sequência particular (ex. binary-indep) o qual simplifica a gestão de dependências para compilações cruzadas (cross-builds).

    Por favor note que os addons activados via Build-Depends-Indep ou Build-Depends-Arch estão sujeitos a limitações adicionais para assegurar que o resultado é determinista mesmo quando o addon está indisponível (ex. durante limpeza). Isto sugere que alguns addons são incompatíveis com essas restrições e só podem ser usadas via Build-Depends (ou manualmente via debian/rules). Actualmente, tais addons podem apenas adicionar comandos a sequências.

--without addon
    O inverso de --with, desactiva a utilização do addon indicado. Esta opção pode ser repetida mais do que uma vez, ou pode desactivar vários addons se os listar separados por vírgulas.

--list, -l
    Lista todos os addons disponíveis.

    Quando chamado apenas com esta opção, o dh pode ser chamado a partir de qualquer directório (isto é, não precisa de acesso a ficheiros de um pacote fonte).

--no-act
    Escreve comandos que iriam correr para uma determinada sequência, mas não os corre.

    Note que o dh normalmente evita correr comandos que sabe que não fazem nada. Com --no-act, é escrito em sequência a lista completa dos comandos.

Outras opções passadas a dh são passadas a cada comando que ele corre. Isto pode ser usado para definir uma opção como -v ou -X ou -N, assim como para opções mais especializadas.

EXEMPLOS
Para ver quais comandos estão incluídos numa sequência, sem realmente fazer nada:

        dh binary-arch --no-act

Este é um ficheiro de regras muito simples, para pacotes onde as sequências de comandos predefinidas funcionam sem opções adicionais.

        #!/usr/bin/make -f
        %:
                dh $@

Muitas vezes você vai querer passar uma opção a um comando debhelper específico. A maneira mais fácil de o fazer é adicionar um alvo de sobreposição a esse comando.

        #!/usr/bin/make -f
        %:
                dh $@

        override_dh_strip:
                dh_strip -Xfoo

        override_dh_auto_configure:
                dh_auto_configure -- --with-foo --disable-bar

Por vezes os automatismos dh_auto_configure(1) e dh_auto_build(1) não conseguem adivinhar que fazer com um pacote estranho. Aqui está como evitar correr outros comandos quaisquer e em vez disso correr os seus próprios comandos.

        #!/usr/bin/make -f
        %:
                dh $@

        override_dh_auto_configure:
                ./mondoconfig

        override_dh_auto_build:
                make universe-explode-in-delight

Outro caso comum é esperar fazer algo manualmente antes ou depois de um comando debhelper particular ser executado.

        #!/usr/bin/make -f
        %:
                dh $@

        # Example assumes debhelper/12.8 and compat 10+
        execute_after_dh_fixperms:
                chmod 4755 debian/foo/usr/bin/foo

Se você está num debhelper ou nível de compatibilidade antigo, o exemplo de cima terá que ser escrito assim:

        #!/usr/bin/make -f
        %:
                dh $@

        # Older debhelper versions or using compat 9 or lower.
        override_dh_fixperms:
                dh_fixperms
                chmod 4755 debian/foo/usr/bin/foo

Por predefinição, as ferramentas Python não são acionadas, devido às alterações contínuas nessa área. Aqui está como usar o dh_python2.

        #!/usr/bin/make -f
        %:
                dh $@ --with python2

Aqui está como forçar o uso do sistema de compilação Module::Build do Perl, o qual pode ser necessário e o debhelper erradamente detectar que o pacote usa MakeMaker.

        #!/usr/bin/make -f
        %:
                dh $@ --buildsystem=perl_build

Aqui está um exemplo de criar uma sobreposição ao local onde os comandos dh_auto_* encontram a fonte do pacote, para um pacote cuja fonte está localizada num sub-directório.

        #!/usr/bin/make -f
        %:
                dh $@ --sourcedirectory=src

E aqui está um exemplo de como dizer aos comandos dh_auto_* para compilarem num sub-directório, o qual será removido em clean.

        #!/usr/bin/make -f
        %:
                dh $@ --builddirectory=build

Se o seu pacote poder ser compilado em paralelo, por favor use compatibilidade 10 ou passe --parallel ao dh. Assim o dpkg-buildpackage -j irá funcionar.

        #!/usr/bin/make -f
        %:
                dh $@ --parallel

Se o seu pacote não pode ser compilado correctamente usando múltiplos processos, por favor passe --no-parallel ao dh (ou ao comando dh_auto_* relevante):

        #!/usr/bin/make -f
        %:
                dh $@ --no-parallel

Aqui está um modo de prevenir que o dh corra vários comandos que você não quer que corram, ao definir alvos de sobreposição vazios para cada comando.

        #!/usr/bin/make -f
        %:
                dh $@

        # Comandos a não correr:
        override_dh_auto_test override_dh_compress override_dh_fixperms:

Pode-se separar um processo de compilação longo para um pacote de documentação separado usando sobreposições independentes da arquitectura. Estes serão saltados quando se corre as sequências build-arch e binary-arch.

        #!/usr/bin/make -f
        %:
                dh $@

        override_dh_auto_build-indep:
                $(MAKE) -C docs

        # Nenhum teste necessário para documentação
        override_dh_auto_test-indep:

        override_dh_auto_install-indep:
                $(MAKE) -C docs install

Adicionando ao exemplo em cima, suponha que precisa de fazer chmod a um ficheiro, mas apenas quando compila o pacote dependente da arquitectura, pois ele não está presente quando compila apenas a documentação.

        # Example assumes debhelper/12.8 and compat 10+
        execute_after_dh_fixperms-arch:
                chmod 4755 debian/foo/usr/bin/foo

ADDONS DH FORNECIDOS PELO DEBHELPER
O objetivo principal dos addons do dh é fornecer integração fácil com funcionalidades fornecidas por terceiros para o debhelper. No entanto, o próprio debhelper também fornece algumas sequências que podem ser úteis em alguns casos. Estas estão documentadas nesta lista:

build-stamp
    Um addon especial para controlar se dh (em compatibilidade 10 ou posterior) irá criar ficheiros stamp para dizer se o alvo de compilação correu com sucesso. Veja "INTERNOS" para mais detalhes.

    Este addon está activo por predefinição mas pode ser desactivado ao usar dh $@ --without build-stamp

dwz Adiciona dh_dwz(1) à sequência.

    Note que isto é apenas relevante em modos de compatibilidade abaixo de 11 ou em compatibilidade 14+. Estava ligado por predefinição nas compatibilidades 12 e 13.

elf-tools
    Este addon adiciona ferramentas relativas a ficheiros ELF à sequência tal como dh_strip(1) e dh_shlibdeps(1)

    Este addon está activo condicionalmente por predefinição para pacotes específicos de arquitectura - isto é, é saltado para pacotes arch:all. Num caso especial que você precise destas ferramentas a funcionar em pacotes arch:all, você pode usar --with elf-tools para o activar incondicionalmente.

installinitramfs (obsoleto)
    Adiciona dh_installinitramfs(1) à sequência em compatibilidade 11 ou inferior. Obsoleto compatibilidade 12 ou posterior.

root-sequence (interno)
    Isto está reservado para uso interno.

single-binary
    Um addon de objetivo-especial que faz o debhelper em modo "binário único".

    Quando activo, irá passar --destdir=debian/package/ ao dh_auto_install(1). Isto faz com que todos os ficheiros "instalados" pelo sistema de compilação do autor façam parte do (único) pacote binário por predefinição sem ter que se usar outros ajudantes como o dh_install(1).

    Como precaução o addon irá recusar activar-se quando o pacote fonte listar 2 ou mais pacotes binários em debian/control.

    Antes da compatibilidade 15, este comportamento era o predefinido quando havia apenas um único pacote binário listado em debian/control. Em compatibilidade 15 e posterior, este addon tem de ser activado explicitamente para que esta funcionalidade funcione.

    A razão para se requerer isto como uma escolha explícita é que se fosse implícita então o debhelper iria mudar o comportamento em silêncio ao se adicionar um novo pacote binário. Isto causou muitos bugs RC quando os maintainers renomeavam um binário e adicionavam pacotes de transição com a intenção de suportar actualizações perfeitas. O resultado era muitas vezes dois pacotes binários vazios que eram enviados para o arquivo com os utilizadores frustrados pois a sua "actualização" removeu os seus programas.

systemd (obsoleto)
    Adiciona dh_systemd_enable(1) e dh_systemd_start(1) à sequência em nível de compatibilidade 10 ou inferior. Obsoleto em compatibilidade 11 ou posterior.

INTERNOS
Se você está curioso sobre o funcionamento interno do dh, aqui está como funciona por baixo da capota.

No modo compatibilidade 10 (ou posterior), o dh cria um ficheiro stamp <debian/debhelper-build-stamp> após os passo(s) de compilação estarem completos para evitar voltar a corre-los. É possível evitar o ficheiro stamp ao passar --without=build-stamp para dh. Isto faz com que compilações "não limpas" se comportem mais como o que algumas pessoas esperam à custa de possivelmente correrem a compilação e testa-la duas vezes (a segunda vez como root ou sob fakeroot(1)).

Dentro de um alvo de sobreposição, os comandos dh_* irão criar um ficheiro de registo debian/package.debhelper.log para manter acompanhamento de para quais pacotes os comando(s) têm corrido. Estes ficheiros log são depois removidos assim que o alvo de sobreposição estiver completo.

No modo de compatibilidade 9 e anteriores, cada comando do debhelper irá gravar em debian/pacote.debhelper.log quando é corrido com sucesso. (O qual dh_clean apaga.) Portanto o dh consegue dizer quais comandos já foram corridos, para quais pacotes, e evita correr esses comandos de novo.

De cada vez que dh corre (no nível de compatibilidade 9 ou anterior), examina o relatório, e encontra o último comando registado que está na sequência especificada. Depois continua com o próximo comando da sequência.

Uma sequência também pode correr alvos dependentes em debian/rules. Por exemplo, a sequência "binary" corre o alvo "install".

dh usa a variável de ambiente DH_INTERNAL_OPTIONS para passar informação através dos comandos debhelper que são corridos dentro de alvos de sobreposição. O conteúdo (e de facto a existência) desta variável de ambiente. como o nome sugere, está sujeito a alterações em qualquer altura.

Aos comandos nas sequências build-indep, install-indep e binary-indep é passada a opção -i para assegurar que eles apenas trabalham em pacotes independentes da arquitectura, e aos comandos nas sequências build-arch, install-arch e binary-arch é passada a opção -a para assegurar que eles apenas trabalham em pacotes dependentes da arquitectura.

VEJA TAMBÉM
debhelper(7)

Este programa é parte 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.