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.

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

    $ 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"
          }
       ]
    }

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

      # 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

      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

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 (obsoleto)

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

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.