Provided by: debhelper_13.14.1ubuntu5_all bug

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

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