Scroll to navigation

DH(1) Debhelper 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.

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

Se você desejar confirmar que o dh viu um alvo de sobreposição ou hook, 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

Se você escolher envolver um alvo hook em condicionais makefile, por favor tenha em mente que dh computa todos os alvos hook em adiantado e guarda em cache o resultado para essa execução. Mais ainda, as condicionais serão invocadas novamente quando dh chamar o alvo hook mais tarde e irá assumir que a resposta não mudou.

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

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.

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

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

DEBHELPER PROVIDED DH ADDONS

The primary purpose of dh addons is to provide easy integration with third-party provided features for debhelper. However, debhelper itself also provide a few sequences that can be useful in some cases. These are documented in this list:

A special addon for controlling whether dh (in compat 10 or later) will create stamp files to tell whether the build target has been run successfully. See "INTERNALS" for more details.

This addon is active by default but can disabled by using dh $@ --without build-stamp

Adds dh_dwz(1) to the sequence in compat level 11 or below. Obsolete in compat 12 or later.
This addon adds tools related to ELF files to the sequence such as dh_strip(1) and dh_shlibdeps(1)

This addon is conditionally active by default for architecture specific packages - that is, it is skipped for arch:all packages. In the special case where you need these tools to work on arch:all packages, you can use --with elf-tools to activate it unconditionally.

Adds dh_installinitramfs(1) to the sequence in compat level 11 or below. Obsolete in compat 12 or later.
This is reserved for internal usage.
A special-purpose addon that makes debhelper run in "single binary" mode.

When active, it will pass --destdir=debian/package/ to dh_auto_install(1). This makes every file "installed" by the upstream build system part of the (only) binary package by default without having to use other helpers such as dh_install(1).

The addon will refuse to activate when the source package lists 2 or more binary packages in debian/control as a precaution.

Before compat 15. this behaviour was the default when there was only a single binary package listed in debian/control. In compat 15 and later, this addon must explicitly be activated for this feature to work.

The rationale for requiring this as an explicit choice is that if it is implicit then debhelper will silently change behaviour on adding a new binary package. This has caused many RC bugs when maintainers renamed a binary and added transitional packages with the intention of supporting seamless upgrades. The result would often be two empty binary packages that were uploaded to archive with users frustrated as their "upgrade" removed their programs.

Adds dh_systemd_enable(1) and dh_systemd_start(1) to the sequence in compat level 10 or below. Obsolete in compat 11 or later.

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 corrê-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 testá-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.

2021-09-23 13.5.2