Provided by: debhelper_12.10ubuntu1_all 
NOME
debhelper - a suite de ferramentas debhelper
RESUMO
dh_* [-v] [-a] [-i] [--no-act] [-ppackage] [-Npackage] [-Ptmpdir]
DESCRIÇÃO
Debhelper é usado para ajudá-lo a compilar um pacote Debian. A filosofia por detrás de
debhelper é disponibilizar uma colecção de ferramentas pequenas, simples e de fácil
compreensão que são usadas em debian/rules para automatizar vários aspectos comuns da
compilação de um pacote. Isto significa menos trabalho para si, o empacotador. Também
significa, até certo ponto, que estas ferramentas podem ser alteradas se a política de
Debian alterar, e os pacotes que as usam irão precisar apenas de uma recompilação para
ficarem em conformidade com a nova política.
Um ficheiro debian/rules típico que usa debhelper irá chamar vários comandos debhelper em
sequência, ou usar dh(1) para automatizar este processo. Em
/usr/share/doc/debhelper/examples/ estão exemplos de ficheiros de regras que usam
debhelper.
Para criar um novo pacote Debian usando o debhelper, você pode copiar um dos ficheiros de
regras exemplo e editá-lo à mão. Ou pode tentar o pacote dh-make, o qual contém um comando
dh_make que automatiza parcialmente o processo Para uma introdução mais gentil, o pacote
Debian maint-guide contém um tutorial acerca de como fazer o seu primeiro pacote usando o
debhelper.
Excepto onde a ferramenta explicitamente denota, caso contrário, todas as ferramentas do
debhelper assumem que são corridas a partir do directório raiz de um pacote fonte
descompactado. Isto é feito para que possam localizar e encontrar ficheiros como
debian/control quando necessário.
COMANDOS DO DEBHELPER
Aqui está a lista dos comandos debhelper que você pode usar. Veja os seus manuais para
documentação adicional.
#LISTA#
Comandos Descontinuados
Alguns comandos debhelper estão descontinuados e não devem ser usados.
#LISTA_DE_DESCONTINUADOS#
Outros comandos
Se o nome dum programa começa com dh_, e o programa não está nas listas em cima, então não
faz parte do pacote debhelper, mas mesmo assim deverá funcionar como os outros programas
descritos nesta página.
FICHEIROS DE CONFIGURAÇÃO DO DEBHELPER
Muitos comandos do debhelper usam ficheiros em debian/ para controlar o que fazem. Para
além dos comuns debian/changelog e debian/control, que estão em todos os pacotes, e não
apenas aqueles que usam debhelper, alguns ficheiros adicionais podem ser usados para
configurar o comportamento de comandos debhelper específicos. Estes ficheiros são chamados
tipicamente debian/pacote.foo (onde pacote é claro, é substituído pelo nome do pacote no
qual se está a actuar).
Por exemplo, dh_installdocs usa ficheiros chamados debian/package.docs para listar os
ficheiros de documentação que ira instalar. Veja os manuais individuais dos comandos para
detalhes acerca dos nomes e formatos dos ficheiros que usam. Geralmente, estes ficheiros
irão listar ficheiros onde se vai actuar, um ficheiro por linha. Alguns programas no
debhelper usam pares de ficheiros e destinos ou formatos ligeiramente mais complicados.
Nota para o primeiro (ou único) pacote binário listado em debian/control, o debhelper irá
usar debian/foo quando não existe nenhum ficheiro debian/package.foo. No entanto, é
geralmente uma boa ideia manter o prefixo package. pois é mais explícito. A principal
excepção a isto são ficheiro que o debhelper instala por predefinição em todos os pacotes
binários quando não tem um prefixo de pacote (tal como debian/copyright ou
debian/changelog).
Em alguns casos raros, você pode querer ter versões diferentes destes ficheiros para
arquitecturas ou sistemas operativos diferentes. Se existirem ficheiros chamados
debian/pacote.foo.ARCH ou debian/pacote.foo.OS, onde ARCH e OS são o mesmo que o resultado
de "dpkg-architecture -qDEB_HOST_ARCH" / "dpkg-architecture -qDEB_HOST_ARCH_OS", então
eles irão ser usados em preferência de outros ficheiros mais gerais.
Maioritariamente, estes ficheiros de configuração são usados para especificar listas de
vários tipos de ficheiros. Documentação ou ficheiros exemplo para instalar, ficheiros para
mover, e etc. Quando apropriado, em casos como estes, você pode usar caracteres "wildcard"
de shell standard (classes de caracteres ? e * e [..]) nos ficheiros. Também pode meter
comentários neste ficheiros; as linhas começadas com # são ignoradas.
A sintaxe destes ficheiros é mantida intencionalmente muito simples para os tornar fáceis
de ler, compreender e modificar.
Substitutions in debhelper config files
In compatibility level 13 and later, it is possible to use simple substitutions in some
debhelper config files (particularly, the configuration files for dh_install(1)).
All substitution variables are of the form ${foo} and the braces are mandatory. Variable
names are case-sensitive and consist of alphanumerics (a-zA-Z0-9), hyphens (-),
underscores (_), and colons (:). The first character must be an alphanumeric.
If you need a literal dollar sign that cannot trigger a substitution, you can either use
the ${Dollar} substitution or the sequence ${}.
The following expansions are available:
DEB_HOST_*, DEB_BUILD_*, DEB_TARGET_*
Expands to the relevant dpkg-architecture(1) value (similar to dpkg-architecture
-qVARIABLE_HERE).
When in doubt, the DEB_HOST_* variant is the one that will work both for native and
cross builds.
For performance reasons, debhelper will attempt to resolve these names from the
environment first before consulting dpkg-architecture(1). This is mostly mentioned
for completeness as it will not matter for most cases.
Dollar
Expands to a single literal $-symbol. This symbol will never be considered part of a
substitution variable. That is:
# Triggers an error
${NO_SUCH_TOKEN}
# Expands to the literal value "${NO_SUCH_TOKEN}"
${Dollar}{NO_SUCH_TOKEN}
This variable equivalent to the sequence ${} and the two can be used interchangeably.
Newline, Space, Tab
Expands to a single ASCII newline, space and tab respectively.
This can be useful if you need to include a literal whitespace character (e.g. space)
where it would otherwise be stripped or used as a separator.
env:NAME
Expands to the environment variable NAME. The environment variable must be set (but
can be set to the empty string).
Note that all variables must expand to a defined value. As an example, if debhelper sees
${env:FOO}, then it will insist that the environment variable FOO is set (it can be set to
the empty string).
Substitution limits
To avoid infinite loops and resource exhaustion, debhelper will stop with an error if the
text contains many substitution variables (50) or they expand beyond a certain size (4096
characters or 3x length of the original input - whichever is bigger).
Ficheiros de configuração do debhelper executáveis.
Se precisar de flexibilidade adicional, muitas das ferramentas debhelper (ex,
dh_install(1)) suportam executar um ficheiro de configuração como um script.
Para usar esta funcionalidade, simplesmente marque o ficheiro de configuração como
executável (ex. chmod +x debian/package.install) e a ferramenta irá tentar executá-lo e
usar o resultado do script. Em muitos casos, você pode usar dh-exec(1) como interpretador
do ficheiro de configuração para reter a maioria da sintaxe original enquanto obtém a
flexibilidade adicional que precisa.
Quando usar ficheiros de configuração executáveis do debhelper, por favor tenha em atenção
o seguinte:
• O ficheiro de configuração executável must termina com sucesso (isto é, o seu código
de retorne deve indicar sucesso).
• In compatibility level 13+, the output will be subject to substitutions (see
"Substitutions in debhelper config files") where the tool support these. Remember to
be careful if your generator also provides substitutions as this can cause unnecessary
confusion.
Otherwise, the output will be used exactly as-is. Notably, debhelper will not expand
wildcards or strip comments or strip whitespace in the output.
Se precisar que o pacote compile num sistema de ficheiros onde não pode desactivar o bit
de executável, então você pode usar dh-exec(1) o o seu script strip-output.
OPÇÕES DO DEBHELPER PARTILHADAS
As seguintes opções de linha de comandos são suportadas por todos os programas do
debhelper.
-v, --verbose
Modo detalhado: mostra todos os comandos que modificam o directório de compilação de
pacotes.
--no-act
Não faz nada na realidade. Se usado com -v, o resultado é que o comando mostra o que
iria fazer.
-a, --arch
Actua em pacotes dependentes da arquitectura que devem ser compilados para a
arquitectura de compilação DEB_HOST_ARCH.
-i, --indep
Actua em todos os pacotes independentes da arquitectura.
-ppacote, --package=pacote
Actua no pacote chamado pacote. Esta opção pode ser especifica várias vezes para fazer
o debhelper operar num determinado conjunto de pacotes.
-s, --same-arch
Alias descontinuado de -a.
Esta opção foi removida no nível de compatibilidade 12.
-Npacote, --no-package=pacote
Não actua no pacote especificado mesmo se uma opção -a, -i, ou -p listarem o pacote
como um em que se deverá actuar.
--remaining-packages
Não actua nos pacotes que já foram actuados antes por este comando do debhelper (isto
é, se o comando estiver presente no debhelper log do pacote). Por exemplo, se você
precisar de chamar o comando com opções especiais apenas para um par de pacotes
binários, passe esta opção para a última chamada do comando para processar o resto dos
pacotes com as definições predefinidas.
-Ptmpdir, --tmpdir=tmpdir
Usa tmpdir para directório de compilação de pacotes. A predefinição é debian/pacote
--mainpackage=pacote
Esta opção pouco usada muda o pacote que o debhelper considera o "pacote principal",
isto é, o primeiro listado em debian/control, e aquele para o qual os ficheiros
debian/foo podem ser usados em vez dos ficheiros debian/package.foo usuais.
-O=opção|bundle
Isto é usado pelo dh(1) quando se passa opções específicas do utilizador a todos os
comandos que corre. Se o comando suportar a opção ou opções especificadas, irá fazer
efeito. Se o comando não suportar a opção (ou alguma parte do conjunto de opções),
será ignorado.
OPÇÕES COMUNS DO DEBHELPER
As seguintes opções de linha de comandos são suportadas por alguns programas do debhelper.
Veja o manual de cada programa para uma explicação completa sobre o que cada opção faz.
-n Não modifique os scripts postinst, postrm, etc.
-Xitem, --exclude=item
Exclui um item do processamento. Esta opção pode ser usada várias vezes, para excluir
mais do que uma coisa. O item é tipicamente parte de um nome de ficheiro, e qualquer
ficheiro que contenha o texto especificado será excluído.
-A, --all
Faz com que ficheiros ou outros itens que são especificados na linha de comandos
tenham efeito em TODOS os pacotes em que se actua, e não apenas o primeiro.
OPÇÕES DO SISTEMA DE COMPILAÇÃO
As seguintes opções de linha de comandos são suportadas por todos os comandos dh_auto_* do
debhelper. Estes programas suportam uma variedade de sistemas de compilação, e normalmente
determinam heurísticamente qual usar, e como os usar. Você pode usar estes opções de linha
de comandos para sobrepor o comportamento predefinido. Tipicamente estas são passadas ao
dh(1), o qual passa-as a todos os programas dh_auto_*.
-Ssistemacompilação, --buildsystem=sistemacompilação
Força a utilização do |<sistemacompilação> especificado, em vez de tentar auto-
seleccionar um que pode ser aplicável para o pacote.
Pass none as buildsystem to disable auto-selection.
-Ddirectory, --sourcedir=directory, --sourcedirectory=directory
Assume que a árvore fonte do pacote original está no directório especificado em vez de
estar no directório de nível de topo da árvore de pacotes fonte de Debian.
-B[directory], --builddir[=directory], --builddirectory[=directory]
Activa a compilação da fonte e usa o directório especificado como o directório de
compilação. Se o parâmetro directório for omitido, é escolhido o directório de
compilação predefinido.
Se esta opção não for especificada, a compilação será feita por predefinição na fonte
a menos que o sistema de compilação requeira ou prefira a compilação da árvore de
fonte. Em tal caso, será usado o directório de compilação predefinido mesmo se
--builddirectory não seja especificado.
Se o sistema de compilação preferir a compilação da árvore fonte mas ainda permitir a
compilação da fonte, a última pode ser re-activada ao passar-lhe um caminho para um
directório de compilação que é o mesmo que o caminho para o directório fonte.
--parallel, --no-parallel
Controla se devem ser usadas compilações paralelas se o sistema de compilação o
suportar. O número de trabalhos paralelos é controlado pela variável de ambiente
DEB_BUILD_OPTIONS ("Debian Policy, secção 4.9.1") durante a compilação. Também pode
servir como um limite específico do sistema de compilação.
Se nenhuma destas opções for especificada, presentemente o debhelper usa por
predefinição --parallel em modo compatibilidade 10 (ou posterior) e --no-parallel em
caso contrário.
Como uma optimização, o dh irá tentar evitar passar estas opções aos sub-processos, se
estas forem desnecessárias e as únicas opções a passar. De notar que isto acontece
quando DEB_BUILD_OPTIONS não tem um parâmetro parallel (ou o seu valor é 1).
--max-parallel=máximo
Esta opção implica --parallel e permite mais limitação ao número de trabalhos que
podem ser usados numa compilação paralela. Se a compilação do pacote é conhecida por
apenas funcionar em certos níveis de concorrência, você pode definir isto para o nível
máximo que é sabido funcionar, ou que deseje suportar.
De notar que, definir o máximo para 1 é efectivamente o mesmo que usar --no-parallel.
--reload-all-buildenv-variables
By default, dh(1) will compute several environment (e.g. by using dpkg-buildflags(1))
and cache them to avoid having all dh_auto_* tool recompute them.
When passing this option, the concrete dh_auto_* tool will ignore the cache from dh(1)
and retrigger a rebuild of these variables. This is useful in the very rare case
where the package need to do multiple builds but with different ...FLAGS options. A
concrete example would be needing to change the -O parameter in CFLAGS in the second
build:
export DEB_CFLAGS_MAINT_APPEND=-O3
%:
dh $@
override_dh_auto_configure:
dh_auto_configure -Bbuild-deb ...
DEB_CFLAGS_MAINT_APPEND=-Os dh_auto_configure \
--reload-all-buildenv-variables -Bbuild-udeb ...
Without --reload-all-buildenv-variables in the second call to dh_auto_configure(1),
the change in DEB_CFLAGS_MAINT_APPEND would be ignored as dh_auto_configure(1) would
use the cached value of CFLAGS set by dh(1).
This option is only available with debhelper (>= 12.7~) when the package uses
compatibility level 9 or later.
--list, -l
Lista todos os sistemas de compilação suportados pelo debhelper neste sistema. A lista
inclui ambos sistemas de compilação predefinidos e de terceiros (marcados como tal).
Também mostra qual o sistema de compilação será seleccionado automaticamente, ou qual
está especificado manualmente com a opção --buildsystem.
NÍVEIS DE COMPATIBILIDADE
De tempos a tempos, precisam de ser feitas grandes alterações no debhelper que não
compatíveis com as versões anteriores, para o manter limpo e bem construído quando as
necessidades alteram e o seu autor ganha mais experiência. Para prevenir que tais grandes
alterações danifiquem os pacotes existentes, foi introduzido o conceito de níveis de
compatibilidade no debhelper. Você deve dizer ao debhelper qual o nível de compatibilidade
que ele deve usar, e ele modifica o seu comportamento de várias maneiras.
No debhelper actual, você pode especificar o nível de compatibilidade em debian/control ao
adicionar um Build-Depends no pacote debhelper-compat. Por exemplo, para usar modo v12,
assegure que debian/control tem:
Build-Depends: debhelper-compat (= 12)
Isto também serve como uma dependência de compilação de versão apropriada numa versão
suficiente do pacote debhelper, assim você não precisa de especificar uma dependência de
compilação de versão separada no pacote debhelper a menos que precise de um lançamento
pontual específico do debhelper (tal como para a introdução de uma nova funcionalidade ou
correcção de bug dentro de um nível de compatibilidade).
Note que o debhelper não fornece debhelper-compat para os níveis de compatibilidade
experimental ou beta; os pacotes que experimentem com esses níveis de compatibilidade
devem usar debian/compat ou DH_COMPAT.
As versões anteriores do debhelper requeriam o nível de compatibilidade especificado no
ficheiro debian/compat, e o debhelper actual ainda suporta isto para compatibilidade com
as versões anteriores, apesar de um pacote não poder especificar um nível de
compatibilidade via múltiplos métodos de uma vez. Para usar este método, debian/compat
deve conter o nível de compatibilidade como um número singular, e nenhum outro conteúdo.
Se você especificar o nível de compatibilidade neste método, o seu pacote vai também
precisar duma dependência de compilação baseada em versão de uma versão do pacote
debhelper igual (ou superior) ao nível de compatibilidade que o seu pacote usa. Assim, se
você especificar o nível de compatibilidade 12 em debian/compat, assegure-se que
debian/control tem:
Build-Depends: debhelper (>= 12~)
A menos que seja indicado o contrário, toda a documentação do debhelper assume que você
está a usar o nível de compatibilidade mais recente, e na maioria dos casos não indica se
o comportamento é diferente num nível de compatibilidade anterior, portanto se não está a
usar o nível de compatibilidade mais recente, você é aconselhado a procurar em baixo por
notas acerca do que é diferente nos níveis de compatibilidade anteriores.
Níveis de compatibilidade suportados
Estes são os níveis de compatibilidade disponíveis:
v5 Este é o nível de compatibilidade mais baixo suportado.
Se você está a actualizar a partir de um nível de compatibilidade anterior, por favor
reveja debhelper-obsolete-compat(7).
Este modo está descontinuado.
v6 As alterações a partir de v5 são:
- Os comandos que geram fragmentos de script de mantenedor irão ordenar os
fragmentos em ordem reversa para os scripts prerm e postrm.
- dh_installwm irá instalar uma ligação escrava de manual para
x-window-manager.1.gz, se vir o manual em usr/share/man/man1 no directório de
compilação do pacote.
- O dh_builddeb anteriormente não apagava nada que correspondesse a
DH_ALWAYS_EXCLUDE, se estivesse definida uma lista de coisas a excluir, como
CVS:.svn:.git. Mas agora fá-lo.
- dh_installman permite a sobreposição de manuais existentes no directório de
compilação do pacote. Nos níveis de compatibilidade anteriores recusava-se em
silêncio a fazer isto.
Este modo está descontinuado.
v7 As alterações a partir de v6 são:
- dh_install, irá regressar a procurar por ficheiros em debian/tmp se não os
encontrar no directório actual (ou onde você lhe disser para procurar usando
--sourcedir). Isto permite ao dh_install inter-operar com o dh_auto_install, o
qual instala para debian/tmp, sem precisar de nenhuns parâmetros especiais.
- dh_clean irá ler debian/clean e apagar os ficheiros listados lá.
- dh_clean irá apagar ficheiros *-stamp do nível de topo.
- dh_installchangelogs irá adivinhar qual ficheiro está no relatório de
alterações da origem se nenhum for especificado.
Este modo está descontinuado.
v8 As alterações a partir de v7 são:
- Os comandos irão falhar em vez de emitirem avisos quando lhes são passadas
opções desconhecidas.
- dh_makeshlibs irá correr dpkg-gensymbols em todas as bibliotecas partilhadas
para as quais gera ficheiros shlibs. Portanto o -X pode ser usado para excluir
bibliotecas. Também, as bibliotecas em localizações fora do habitual que o
dpkg-gensymbols não tenha processado antes serão passadas para ele, uma
alteração no comportamento que pode causar que alguns pacotes falhem a
compilar.
- dh requer que a sequência a correr seja especificada como o primeiro
parâmetro, e quaisquer switches que venham depois dela. Isto é, use dh $@
--foo", e não "dh --foo $@
- dh_auto_* prefere usar o Module::Build do Perl em preferência de Makefile.PL.
Este modo está descontinuado.
v9 As alterações a partir de v8 são:
- Suporte a multi-arquitectura. Em particular, dh_auto_configure passa
directórios de multi-arquitectura ao autoconf em --libdir e --libexecdir.
- O dh tem conhecimento das dependências habituais entre metas em debian/rules.
Por isso, o "dh binary" irá correr quaisquer metas de build, build-arch,
build-indep, install, etc que existam no ficheiro de regras. Não há
necessidade de definir uma meta binário explícito com dependências explícitas
em outras metas.
- dh_strip comprime ficheiros de símbolos de depuração para reduzir o tamanho
instalado dos pacotes -dbg.
- dh_auto_configure não inclui o nome do pacote fonte em --libexecdir quando usa
autoconf.
- dh não tem por predefinição a activação de --with=python-support
(Obsoleto: Pois a ferramenta dh_pysupport foi removida a partir de Debian
stretch. Desde o debhelper/10.3, dh já não se activa esta sequência add-on
independentemente do nível de compatibilidade)
- Todos os programas debhelper dh_auto_* e dh definem variáveis de ambiente
listadas por dpkg-buildflags, a menos que elas estejam já definidas.
- dh_auto_configure passa as dpkg-buildflags CFLAGS, CPPFLAGS, e LDFLAGS para
Makefile.PL e Build.PL de perl.
- dh_strip põe símbolos de depuração separados numa localização baseada no seu
build-id.
- Os ficheiros de configuração executáveis do debhelper são corridos e os seus
resultados usados como configuração.
v10 As alterações a partir de v9 são:
- dh_installinit não irá mais instalar um ficheiro chamado debian/pacote como um
script de iniciação (init).
- O dh_installdocs irá dar erro se detectar links criados com --link-doc entre
pacotes de arquitectura "all" e não-"all" porque isso faz quebrar binNMUs.
- O dh_installdeb já não instala um ficheiro debian/pacote.shlibs
disponibilizado pelo mantenedor. Em vez disso, isto agora é feito pelo
dh_makeshlibs.
- O dh_installwm recusa-se a criar um pacote quebrado se não encontrar nenhuma
página de manual (necessário para registo para a alternativa do x-window-
manager).
- Debhelper irá predefinir para --parallel em todos os sistemas de compilação
que suportam compilação paralela. Isto pode ser desactivado usando
--no-parallel ou passando --max-parallel com o valor de 1.
- O comando dh não irá aceitar nenhum dos parâmetros de "controle de sequência
manua" descontinuados (--before, --after, etc.). Por favor utilize metas de
sobreposição em vez destes.
Retroactively applied to earlier compat levels: dh no longer accepts any of
these since debhelper/12.4.
- O comando dh não irá mais usar ficheiros log para seguir quais comandos foram
executados. O comando dh ainda mantêm o seguimento se já correu a sequência de
"compilação" e salta-a se já o fez.
Os principais efeitos disto são:
- Com isto, é agora mais fácil de depurar as sequências install ou/e binary
porque agora podem ser trivialmente re-executadas (sem ter que fazer um
ciclo de "limpar e recompilar" completo.
- O principal embargo é que dh_* agora apenas mantêm acompanhamento do que
aconteceu numa meta de sobreposição singular. Quanto todas as chamadas a
um dado comando dh_cmd acontecem na mesma meta de sobreposição tudo irá
funcionar como dantes.
Exemplo de onde pode falhar:
override_dh_foo:
dh_foo -pmy-pkg
override_dh_bar:
dh_bar
dh_foo --remaining
Neste caso, a chamada a dh_foo --remaining irá também incluir my-pkg,
desde que dh_foo -pmy-pkg tenha corrido numa meta de sobreposição
separada. Este problema não está imitado a --remaining, mas também inclui
-a, -i, etc.
- O comando dh_installdeb agora faz "escape de shell" às linhas no ficheiro de
configuração de maintscript. Esta foi a intenção original mas não trabalhava
correctamente e os pacotes começaram a confiar no "escapar de shell"
incompleto (ex. ao mencionar nomes de ficheiros).
- O comando dh_installinit agora usa por predefinição --restart-after-upgrade.
Para pacotes que precisam do comportamento anterior, por favor use
--no-restart-after-upgrade.
- A sequência autoreconf é agora activada por predefinição. Por favor passe
--without autoreconf ao dh se isto não for desejável para um determinado
pacote
- A sequência systemd é agora activada por predefinição. Por favor passe
--without systemd ao dh se isto não for desejável para um determinado pacote.
- Rectroactivamente removido dh já não cria o directório de compilação do pacote
quando salta a execução de comandos debhelper. Isto não vai afectar pacotes
que apenas compilam com comandos debhelper, mas pode expor bugs em comandos
não incluídos no debhelper.
Esta funcionalidade de compatibilidade tinha um bug desde a sua inserção no
debhelper/9.20130516 que o fazia falhar ao aplicar em compatibilidade 9 e
anteriores. Como não tem havido relatórios de problemas causados por este bug
nesses -5 anos, este item foi removido em vez de corrigido.
v11 This mode is discouraged.
The compat 11 is discouraged for new packages as it suffers from feature interaction
between dh_installinit and dh_installsystemd causing services to not run correctly in
some cases. Please consider using compatibility mode 10 or 12 instead. More details
about the issue are available in Debian#887904 and
<https://lists.debian.org/debian-release/2019/04/msg01442.html>.
As alterações a partir de v10 são:
- dh_installinit já não instala ficheiros service ou tmpfile, nem gera scripts
do mantenedor para esses ficheiros, Por favor use o novo ajudante
dh_installsystemd
- Os ajudantes dh_systemd_enablee dh_systemd_start foram substituídos pelo novo
ajudante dh_installsystemd. Pela mesma razão, a sequência do systemd para dh
foi também removida. Se você precisar de desactivar a ferramenta de ajuda
dh_installsystemd, por favor use um alvo de sobreposição vazio.
Por favor note que a ferramenta dh_installsystemd tem um comportamento
ligeiramente diferente em alguns casos (ex. quando se usa o parâmetro --name).
- dh_installdirs já não cria directórios debian/pacote a menos que tal seja
explicitamente pedido (ou se tiver de criar um sub-directório nele).
A grande maioria dos pacotes não serão afectados por esta alteração.
- O sistema de compilação makefile agora passa INSTALL="install
--strip-program=true" para o make(1). Sistemas de compilação derivativos (ex.
configure ou cmake) não são afectados por esta alteração.
- O sistema de compilação autoconf agora passa --runstatedir=/run para
./configure.
- O sistema de compilação cmake agora passa -DCMAKE_INSTALL_RUNSTATEDIR=/run
para cmake(1).
- dh_installman irá agora preferir detectar a linguagem a partir do nome de
caminho em vez de a extensão.
- dh_auto_install irá agora apenas criar o directório de destino que precisa.
Anteriormente, iria criar o directório de compilação de pacote para todos os
pacotes. Isto não vai afectar pacotes que apenas compilam com comandos
debhelper, mas pode expor bugs em comandos não incluídos no debhelper.
- Os ajudantes dh_installdocs, dh_installexamples, dh_installinfo, e
dh_installman agora dão erro se a sua configuração tiver um padrão que não
coincida com nada ou faça referência a um caminho que não exista.
Excepções conhecidas incluem compilar com o perfil nodoc, onde as ferramentas
de cima irão permitir em silêncio correspondências falhadas onde os padrões
são usados para especificar documentação.
- Os ajudantes dh_installdocs, dh_installexamples, dh_installinfo, e
dh_installman agora aceitam o parâmetro --sourcedir com o mesmo significado
que dh_install. Mais ainda, eles agora também retornam (em fall back) a
debian/tmp como dh_install.
Nota de migração: Um bug no debhelper 11 até ao 11.1.5 faz com que
dh_installinfo ignore incorrectamente --sourcedir.
- Os sistemas de compilação perl-makemaker e perl-build já não passam -I. ao
perl. Os pacotes que ainda precisam deste comportamento podem emula-lo ao usar
a variável de ambiente PERL5LIB. Ex. ao adicionar export PERL5LIB=. no seu
ficheiro debian/rules (ou semelhante).
- A variável de ambiente PERL_USE_UNSAFE_INC já não é definida pelo dh ou
nenhuma das ferramentas dh_auto_*. Ela foi adicionada como um meio de contorno
temporário evitar muitos pacotes a falharem a compilação ao mesmo tempo.
Note que este item irá eventualmente tornar-se obsoleto pois o auto pretende
abandonar o suporte para a variável de ambiente PERL_USE_UNSAFE_INC. Quando o
perl abandonar o para ala, então esta variável será também removida
retroactivamente dos níveis de compatibilidade existentes.
- O ajudante dh_makeshlibs irá agora terminar em erro se objdump retornar uma
saída não-zero a partir da análise de um determinado ficheiro.
- As ferramentas dh_installdocs e dh_installexamples podem agora instalar a
maioria da documentação num caminho diferente para cumprir com a recomendação
da política Debian §12.3 (desde versão 3.9.7).
Note que um dado pacote fonte apenas contém um único pacote binário em
debian/control ou nenhum dos pacotes são pacotes -doc, então esta alteração
não é relevante para esse pacote fonte e você pode saltar a próxima alteração.
Por predefinição, estas ferramentas irão agora tentar determinar um "pacote
principal para a documentação" (chamado um doc-main-package daqui em diante)
para cada pacote -doc. Se encontrarem o tal doc-main-package, irão agora
instalar a documentação em /usr/share/doc/doc-main-package no pacote doc
fornecido. Isto é, o caminho pode mudar mas a documentação será na mesma
enviada no pacote -doc.
A opção --doc-main-package pode ser usada quando a auto-detecção é
insuficiente ou para reiniciar o caminho para o seu valor anterior se existir
razão para divergir da recomendação da politica Debian.
Alguma documentação não será afectada por esta alteração. Estas excepções
incluem o ficheiro copyright, ficheiros changelog, README.Debian, etc. Estes
ficheiros serão na mesma instalados no caminho /usr/share/doc/pacote.
- As ferramentas dh_strip e dh_shlibdeps já não usam mais padrões de nomes de
ficheiros para determinar quais ficheiros processar. Em vez disso, elas abrem
o ficheiro e procuram um cabeçalho ELF para determinar se um dado ficheiro é
um objecto partilhado ou um executável ELF.
Esta alteração fazer com que as ferramentas processem mais ficheiros que
anteriormente.
v12 Este é o modo de operação recomendado.
As alterações a partir de v11 são:
- A ferramenta dh_makeshlibs agora gera ficheiros shlibs com dependência de
versão por predefinição. Isto significa que -VUpstream-Version (a.k.a. -V) é
agora a predefinição.
If an unversioned dependency in the shlibs file is wanted, this can be
obtained by passing -VNone instead. However, please see dh_makeshlibs(1) for
the caveat of unversioned dependencies.
- A opção -s (--same-arch) foi removida. Por favor use -a (--arch) em vez desta.
- Invocar dh_clean -k agora causa um erro em vez de um aviso de descontinuação.
- A opção --no-restart-on-upgrade em dh_installinit foi removida. Por favor use
o novo nome --no-stop-on-upgrade
- Existia um bug nas funções doit (e similares) a partir de
Debian::Debhelper::Dh_Lib que fazia aparece uma linha de comandos numa
circunstância particular. Este bug foi agora removido e irá fazer com que os
ajudantes que contavam com esse bug falhem com um erro de "comando não
encontrado".
- O --list-missing e --fail-missing em dh_install foram removidos. Por favor use
dh_missing e as suas opções correspondentes, o qual pode também ver os
ficheiros instalados por outros ajudantes.
- O ajudante dh_installinit já não instala configuração para o sistema de init
upstart. Em vez disso, irá abortar a compilação se encontrar um ficheiro de
configuração upstart antigo. O erro está lá para lembrar ao mantenedor do
pacote para assegurar a remoção apropriada dos ficheiros de configuração
empacotados em versões anteriores do pacote (caso existam).
- A ferramenta dh_installdeb irá fazer validação básica de alguns comandos
dpkg-maintscript-helper(1) e irá terminar em erro se os comandos parecerem ser
inválidos.
- A ferramenta dh_missing irá agora usar por predefinição --list-missing.
- A ferramenta dh_makeshlibs irá agora apenas passar bibliotecas para
dpkg-gensymbols(1) se o binário ELF tiver um SONAME (contendo ".so").
- A ferramenta dh_compress não mais comprime exemplos (isto é, nada instalado em
</usr/share/doc/pacote/examples>.)
- A sequência standard em dh agora inclui dh_dwz e dh_installinitramfs por
predefinição. Isto tornas as sequências dwz e installinitramfs obsoletas e
elas agora irão falhar com um erro. Se desejar saltar estes comandos, por
favor insira um alvo de sobreposição vazio para eles em debian/rules (ex.
override_dh_dwz:)
- Os sistemas de compilação meson e autoconf não mais definem explicitamente a
variável --libexecdir e assim apoia-se na predefinição do sistema de
compilação - O qual deve ser /usr/libexec (por FHS 3.0, adoptado em Debian
Policy 4.1.5).
Se um determinado pacote original do autor não usar a predefinição correcta, o
parâmetro pode muitas vezes ser passado manualmente via dh_auto_configure(1).
Por exemplo via seguinte exemplo:
override_dh_auto_configure:
dh_auto_configure -- --libexecdir=/usr/libexec
Note o -- antes do parâmetro --libexecdir.
- A ferramenta dh_installdeb não mais instala o ficheiro conffiles fornecido
pelo mantenedor. O ficheiro torneou-se maioritariamente obsoleto desde o nível
de compatibilidade 3, onde dh_installdeb começo a computar automaticamente o
ficheiro de controle conffiles resultante.
- A ferramenta dh_installsystemd não mais se apoia em dh_installinit para lidar
com os serviços do systemd que têm uma alternativa de sysvinit. ambas
ferramentas devem agora ser usadas em tais casos para assegurar que o serviço
é arrancado correctamente sob ambos sysvinit e systemd.
Se tiver uma sobreposição para dh_installinit (ex. para chamá-lo com
--no-start) então irá provavelmente precisar agora também de um para
dh_installsystemd.
Esta alteração faz dh_installinit injectar um misc:Pre-Depends para init-
system-helpers (>= 1.54~). Por favor assegure que o pacote lista
${misc:Pre-Depends} no seu campo Pre-Depends antes de actualizar para a
compatibilidade 12.
- Esta ferramenta de terceiros dh_golang (do pacote dh-golang) agora por
predefinição honra a variável DH_GOLANG_EXCLUDES para instalação fonte em
pacotes -dev e não apenas durante o processo de compilação. Por favor defina
DH_GOLANG_EXCLUDES_ALL para falso para reverter para o comportamento anterior.
Veja Debian::Debhelper::Buildsystem::golang(3pm) para detalhes e exemplos
- dh_installsystemduser é agora incluído na sequência standard do dh por
predefinição.
- O sistema de compilação python-distutils foi agora removido. Por favor use o
sistema de compilação de terceiros pybuild em substituição.
v13 Este nível de compatibilidade ainda está aberto em desenvolvimento; use com cuidado.
As alterações a partir de v12 são:
- O sistema de compilação meson+ninja agora usa meson test em vez de ninja test
quando corre a suite de testes. Qualquer sobreposição de dh_auto_test que
passe parâmetros extra ao testador original do autor deve ser revista, pois o
meson test não é compatível em linha de comandos com o ninja test.
- All debhelper like tools based on the official debhelper library (including dh
and the official dh_* tools) no longer accepts abbreviated command parameters.
At the same time, dh now optimizes out calls to redundant dh_* helpers even
when passed long command line options.
- The ELF related debhelper tools (dh_dwz, dh_strip, dh_makeshlibs,
dh_shlibdeps) are now only run for arch dependent packages by default (i.e.
they are excluded from *-indep targets and are passed -a by default). If you
need them for *-indep targets, you can add an explicit Build-Depends on dh-
sequence-elf-tools.
- The third-party gradle build system (from gradle-debian-helper package) now
runs the upstream-provided test suite automatically. To suppress such
behavior, override dh_auto_test.
- The dh_installman tool now aborts if it sees conflicting definitions of a
manpage. This typically happens if the upstream build system is installing a
compressed version and the package lists an uncompressed version of the
manpage in debian/package.manpages. Often the easiest fix is to remove the
manpage from debian/package.manpages (assuming both versions are identical).
- The dh_auto_* helpers now resets the environment variables HOME and common
XDG_* variable. HOME and XDG_RUNTIME_DIR are each set to a distinct writable
directory. The rest of the environment variables are cleared.
- The dh command will now error if an override or hook target for an obsolete
command are present in debian/rules (e.g. override_dh_systemd_enable:).
- The dh_missing command will now default to --fail-missing. This can be
reverted to a non-fatal warning by explicitly passing --list-missing like it
was in compat 12.
If you do not want the warning either, please omit the call to dh_missing. If
you use the dh command sequencer, then you can do this by inserting the an
empty override target in the debian/rules file of the relevant package. As an
example:
# Disable dh_missing
override_dh_missing:
- The dh command sequencer now runs dh_installtmpfiles in the default sequence.
The dh_installtmpfiles takes over handling of tmpfiles.d configuration files.
Related functionality in dh_installsystemd is now disabled.
Note that dh_installtmpfiles responds to debian/package.tmpfiles where
dh_installsystemd used a name without the trailing "s".
- Many dh_* tools now support limited variable expansion via the ${foo} syntax.
In many cases, this can be used to reference paths that contain either spaces
or dpkg-architecture(1) values. While this can reduce the need for dh-exec(1)
in some cases, it is not a replacement dh-exec(1) in general. If you need
filtering, renaming, etc., the package will still need dh-exec(1).
Please see "Substitutions in debhelper config files" for syntax and available
substitution variables. To dh_* tool writers, substitution expansion occurs
as a part of the filearray and filedoublearray functions.
- The dh command sequencer will now skip all hook and override targets for
dh_auto_test, dh_dwz and dh_strip when DEB_BUILD_OPTIONS lists the relevant
nocheck / nostrip options.
Any package relying on these targets to always be run should instead move
relevant logic out of those targets. E.g. non-test related packaging code
from override_dh_auto_test would have to be moved to
execute_after_dh_auto_build or execute_before_dh_auto_install.
- The cmake buildsystem now passes -DCMAKE_SKIP_INSTALL_ALL_DEPENDENCY=ON to
cmake(1) to speed up automatic installation process. If for some reason you
need previous behavior, override the flag:
dh_auto_configure -- -DCMAKE_SKIP_INSTALL_ALL_DEPENDENCY=OFF ...
NOTAS
Suporte a pacotes de múltiplos binários
Se o seu pacote fonte gerar mais do que um pacote binário, os programas do debhelper, por
predefinição, irão actuar em todos os pacotes binários quando correm. No caso do seu
pacote fonte gerar um pacote dependente de arquitectura, e outro pacote independente da
arquitectura, este não é o comportamento correcto, porque você precisa de gerar os pacotes
dependentes de arquitectura na meta debian/rules binary-arch, e os pacotes independentes
de arquitectura na meta debian/rules binary-indep.
Para facilitar isto, e também para lhe dar mais controle sobre em quais pacotes os
programas debhelper actuam, todos os programas debhelper aceitam os parâmetros -a, -i, -p,
e -s. Estes parâmetros são cumulativos. Se nenhum for usado, os programas debhelper por
predefinição actuam em todos os pacotes listados no ficheiro de controle, com as excepções
em baixo.
Primeiro, qualquer pacote cujo campo Architecture em debian/control não corresponda à
arquitectura DEB_HOST_ARCH será excluído ("Debian Policy, secção 5.6.8").
Também, alguns pacotes adicionais podem ser excluídos com base no conteúdo da variável de
ambiente DEB_BUILD_PROFILES e nos campos Build-Profiles nas estrofes de pacotes binários
em debian/control, de acordo com a política proposta em
<https://wiki.debian.org/BuildProfileSpec>.
Interacção entre selecções de pacotes e Build-Profiles
Build-Profiles afectam quais pacotes são incluídos nos mecanismos de selecção de pacotes
do debhelper. Geralmente, as selecções de pacotes são descritas a partir do pressuposto
que todos os pacotes estão activados. Esta secção descreve como as selecções reagem quando
um pacote é desactivado devido a Build-Profiles activos (ou a falta de Build-Profiles
activos).
-a/--arch, -i/--indep OU nenhuma opção de selecção (uma chamada "dh_X" crua)
O pacote desactivado por Build-Profiles é excluído em silêncio da selecção.
Note que vai receber um aviso se todos os pacotes relacionados com estas selecções
estiverem desactivados. Nesse caso, geralmente não faz nenhum sentido sequer fazer a
compilação.
-N package / --no-package package
A opção é aceite e efectivamente não faz nada.
-p package / --package package
A opção é aceite, mas o debhelper não irá actuar no pacote.
Note que não importa se um pacote está activado ou desactivado por predefinição.
Geração automática de scripts de instalação Debian
Alguns comandos do debhelper irão gerar automaticamente partes de scripts de mantenedor
Debian. Se desejar que estas coisas geradas automaticamente sejam incluídas nos sues
scripts de mantenedor Debian existentes, então você precisa adicionar #DEBHELPER# aos seus
scripts, no local onde o código deverá ser adicionado. #DEBHELPER# será substituído por
qualquer código auto-gerado quando você correr o dh_installdeb.
Se não existir nenhum script e o debhelper precisar de adicionar algo a ele, então o
debhelper irá criar o script completo.
Todos os comandos debhelper que geram código automaticamente deste modo permitem que o
seja desactivado pelo parâmetro -n (ver em cima).
Note que o código inserido será código shell, portanto você não pode usá-lo directamente
num script de Perl. Se desejar embebê-lo num script Perl, aqui está um modo de o fazer
(note que Eu certifico-me que $1, $2, etc são definidos com o comando "set"):
my $temp="set -e\nset -- @ARGV\n" . << 'EOF';
#DEBHELPER#
EOF
if (system($temp)) {
my $exit_code = ($? >> 8) & 0xff;
my $signal = $? & 0x7f;
if ($exit_code) {
die("The debhelper script failed with error code: ${exit_code}");
} else {
die("The debhelper script was killed by signal: ${signal}");
}
}
Geração automática de dependências variadas.
Alguns programas debhelper podem fazer com que o pacote gerado precise de depender de
alguns outros pacotes. Por exemplo, se você usar o dh_installdebconf(1), o seu pacote irá
geralmente depender do debconf. Ou se você usar dh_installxfonts(1), o seu pacote irá
geralmente depender de uma versão particular do xutils. Acompanhar estas dependências
variadas pode ser aborrecido pois elas dependem de como o debhelper faz as coisas, então o
debhelper oferece um modo de automatizar isto.
Todos os comandos deste tipo, além de documentar quais dependências podem ser necessárias
nos seus manuais, irão gerar automaticamente um substvar chamado ${misc:Depends}. Se você
colocar esse testemunho no seu ficheiro debian/control, será expandido às dependências que
o debhelper descobre que você precisa.
Isto é inteiramente independente do standard ${shlibs:Depends} gerado pelo
dh_makeshlibs(1), e do ${perl:Depends} gerado pelo dh_perl(1). Você pode escolher usar
qualquer um destes, se as escolhas do debhelper não corresponderem à realidade.
Directórios de compilação de pacotes
Por predefinição, todos os programas do debhelper assumem que o directório temporário
usado para montar a árvore de ficheiros num pacote é debian/pacote.
Por vezes, você pode querer usar outro directório temporário. Isto é suportado pela
bandeira -P, por exemplo, "dh_installdocs -Pdebian/tmp", irá usar debian/tmp como
directório temporário. Note que se você usar -P, os programas debhelper só podem actuar
num pacote de cada vez. Por isso se tem um pacote que compila muitos pacotes binários, irá
também precisar de usar a bandeira -p para especificar em qual pacote binário o programa
debhelper irá actuar.
udebs
Debhelper inclui suporte para udebs. Para criar um udeb com o debhelper, adicione
"Package-Type: udeb" à estrofe do pacote em debian/control. O Debhelper irá tentar criar
udebs em conformidade com a política do instalador debian, ao finalizar os ficheiros de
pacotes gerados com .udeb, não instalando nenhuma documentação num udeb, saltando os
scripts preinst, postrm, prerm, e config, etc.
AMBIENTE
As seguintes variáveis de ambiente podem influenciar o comportamento do debhelper. É
importante notar que estas que estas têm de ser mesmo variáveis de ambiente de modo a
funcionarem correctamente (e não simplesmente variáveis do Makefile). Para as especificar
correctamente em debian/rules, assegure-se de lhes fazer "export". Por exemplo, "export
DH_VERBOSE"
DH_VERBOSE
Defina para 1 para activar o modo detalhado. O debhelper irá mostrar os resultados de
cada comando que corre. Também activa relatórios de compilação detalhados para alguns
sistemas de compilação como o autoconf.
DH_QUIET
Definir para 1 para activar o modo silencioso. O Debhelper não irá escrever os
comandos a chamar o sistema de compilação do autor nem o dh irá escrever quais sub-
comandos são chamados e dependendo do sistema de compilação do autor, poderá também
tornar isso mais silencioso. Isto facilita a identificação de mensagens importantes
mas torna os resultados inúteis como relatório do buildd. É ignorado se DH_VERBOSE for
também definido.
DH_COMPAT
Especifica temporariamente em que nível de compatibilidade o debhelper deve correr,
sobrepondo qualquer valor especificado via Build-Depend em debhelper-compat ou via
ficheiro debian/compat.
DH_NO_ACT
Defina para 1 para activar o modo no-act.
DH_OPTIONS
All debhelper tools will parse command line arguments listed in this variable before
any command option (as if they had been prepended to the command line arguments).
Unfortunately, some third-party provided tools may not support this variable and will
ignore these command line arguments.
Quando se usa dh(1), podem-se passar opções que irão ser passadas a cada comando do
debhelper, o que é geralmente melhor do que usar DH_OPTIONS.
DH_ALWAYS_EXCLUDE
Se definido, isto adiciona o valor que está definido na variável às opções -X de todos
os comandos que suportam a opção -X. Ainda mais, o dh_builddeb irá fazer rm -rf a tudo
o que corresponda a esse valor na sua árvore de compilação do pacote.
Isto pode ser útil se você está a fazer uma compilação a partir de uma árvore fonte
CVS, que no caso definindo DH_ALWAYS_EXCLUDE=CVS irá prevenir que quaisquer
directórios CVS se esgueirem para o pacote que está a compilar. Ou, se um pacote tem
um tarball de fonte que (não inteligentemente) inclui directórios CVS, você pode
querer exportar DH_ALWAYS_EXCLUDE=CVS em debian/rules, para o fazer ter efeito onde o
seu é compilado.
Várias coisas a excluir podem ser separadas com "dois pontos", como em
DH_ALWAYS_EXCLUDE=CVS:.svn
DH_EXTRA_ADDONS
Se definido, isto adiciona os addons especificados do dh para serem corridos nos
lugares apropriados na sequência de comandos. Isto é equivalente a especificar o addon
a correr coma bandeira --with no ficheiro debian/rules file. Qualquer chamada
--without que especifique um addon nesta variável de ambiente não será executada.
Isto destina-se a ser usado por downstreams ou configurações locais especificas que
requeiram a execução dum addon do debhelper durante múltiplas compilações sem terem
que aplica patch a um grande número de ficheiros de regras. Se de todo possível, isto
deve ser evitado em favor de uma bandeira --with no ficheiro rules.
DH_COLORS, DPKG_COLORS
These variables can be used to control whether debhelper commands should use colors in
their textual output. Can be set to "always", "auto" (the default), or "never".
Note that DPKG_COLOR also affects a number of dpkg related tools and debhelper uses it
on the assumption that you want the same color setting for dpkg and debhelper. In the
off-hand chance you want different color setting for debhelper, you can use DH_COLORS
instead or in addition to DPKG_COLORS.
NO_COLOR
If no explicit request for color has been given (e.g. DH_COLORS and DPKG_COLORS are
both unset), the presence of this environment variable cause the default color setting
to be "never".
The variable is defined according to <https://no-color.org/>. In this project, the
environment variables (such as DH_COLORS) are considered an explicit request for
color.
CFLAGS, CPPFLAGS, CXXFLAGS, OBJCFLAGS, OBJCXXFLAGS, GCJFLAGS, FFLAGS, FCFLAGS, LDFLAGS
By default (in any non-deprecated compat level), debhelper will automatically set
these flags by using dpkg-buildflags(1), when they are unset. If you need to change
the default flags, please use the features from dpkg-buildflags(1) to do this (e.g.
DEB_BUILD_MAINT_OPTIONS=hardening=all or
DEB_CPPFLAGS_MAINT_APPEND=-DCUSTOM_MACRO=true) rather than setting the concrete
variable directly.
HOME, XDG_*
In compat 13 and later, these environment variables are reset before invoking the
upstream build system via the dh_auto_* helpers. The variables HOME and
XDG_RUNTIME_DIR will be set to a writable directory. The remaining variables will be
cleared.
The directories will be created as empty directories but they will be reused between
calls to dh_auto_*. Any content will persist until explicitly deleted or dh_clean.
VEJA TAMBÉM
/usr/share/doc/debhelper/examples/
Um conjunto de ficheiros debian/rules exemplo que usam debhelper.
<http://joeyh.name/code/debhelper/>
Sítio web 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.