Provided by: debhelper_13.24.2ubuntu1_all 
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.
13.24.2ubuntu1 2025-05-22 DH(1)