dh - sequenciador de comandos do debhelper
dh sequence [
--with addon[
,addon ...]]
[
--list] [
debhelper opções]
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.
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.
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).
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.
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).
As a special optimization,
dh will skip a target if it is completely
empty and does not depend on any other target. This is mostly useful for
override targets, where the command will simply be skipped without the
overhead of invoking a dummy target.
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)
As of debhelper 13.10, you can use
dh_assistant(1) to see which override
and hook targets will be seen by
dh. Here is an example run of
dh_assistant(1) along with its output:
$ 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"
}
]
}
The
commands-not-in-path is useful for spotting mistakes in the hook
target names. A non-empty value implies one of more hook targets are related
to a command that is either not installed or no command with that name exists
at all. It is generally worth double checking these.
Additionally, the
is-empty attribute for each hook target can be used for
seeing whether a hook target triggers the "Completely empty targets"
optimization.
If you are interested in the other attributes, please read the
dh_assistant(1) for the details.
Verifying targets are picked up by dh (when debhelper is older than
13.10)
On older versions of debhelper, you have to use
dh with
--no-act.
You can use the following command as an example:
$ 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.
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.
-
--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.
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
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.
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.
debhelper(7)
Este programa é parte do debhelper.
Joey Hess <
[email protected]>
Américo Monteiro
Se encontrar algum erro na tradução deste documento, por favor
comunique para Américo Monteiro
[email protected] ou Equipa
Debian de Tradução Portuguesa
[email protected].