debhelper(7) | Debhelper | debhelper(7) |
debhelper - a suite de ferramentas debhelper
dh_* [-v] [-a] [-i] [--no-act] [-ppackage] [-Npackage] [-Ptmpdir]
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.
Except where tool explicitly denotes otherwise, all of the debhelper tools assumes that they run from root directory of an unpacked source package. This is so they can locate find files like debian/control when needed.
Aqui está a lista dos comandos debhelper que você pode usar. Veja os seus manuais para documentação adicional.
Alguns comandos debhelper estão descontinuados e não devem ser usados.
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.
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.
Note for the first (or only) binary package listed in debian/control, debhelper will use debian/foo when there's no debian/package.foo file. However, it is often a good idea to keep the package. prefix as it is more explicit. The primary exception to this are files that debhelper by default installs in every binary package when it does not have a package prefix (such as debian/copyright or 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.
The syntax of these files is intentionally kept very simple to make them easy to read, understand, and modify.
If you need additional flexibility, many of the debhelper tools (e.g. dh_install(1)) support executing a config file as a script.
To use this feature, simply mark the config file as executable (e.g. chmod +x debian/package.install) and the tool will attempt to execute it and use the output of the script. In many cases, you can use dh-exec(1) as interpreter of the config file to retain most of the original syntax while getting the additional flexibility you need.
When using executable debhelper config files, please be aware of the following:
If you need the package to build on a file system where you cannot disable the executable bit, then you can use dh-exec(1) and its strip-output script.
As seguintes opções de linha de comandos são suportadas por todos os programas do debhelper.
This option is removed in compat 12.
Por exemplo, se o autor do programa juntar um debian/init que você não quer que dh_installinit instale, use --ignore=debian/init
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.
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_*.
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.
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).
De notar que, definir o máximo para 1 é efectivamente o mesmo que usar --no-parallel.
From time to time, major non-backwards-compatible changes need to be made to debhelper, to keep it clean and well-designed as needs change and its author gains more experience. To prevent such major changes from breaking existing packages, the concept of debhelper compatibility levels was introduced. You must tell debhelper which compatibility level it should use, and it modifies its behavior in various ways.
In current debhelper, you can specify the compatibility level in debian/control by adding a Build-Depends on the debhelper-compat package. For example, to use v12 mode, ensure debian/control has:
Build-Depends: debhelper-compat (= 12)
This also serves as an appropriate versioned build dependency on a sufficient version of the debhelper package, so you do not need to specify a separate versioned build dependency on the debhelper package unless you need a specific point release of debhelper (such as for the introduction of a new feature or bugfix within a compatibility level).
Note that debhelper does not provide debhelper-compat for experimental or beta compatibility levels; packages experimenting with those compatibility levels should use debian/compat or DH_COMPAT.
Prior versions of debhelper required specifying the compatibility level in the file debian/compat, and current debhelper still supports this for backward compatibility, though a package may not specify a compatibility level via multiple methods at once. To use this method, debian/compat should contain the compatibility level as a single number, and no other content. If you specify the compatibility level by this method, your package will also need a versioned build dependency on a version of the debhelper package equal to (or greater than) the compatibility level your package uses. So, if you specify compatibility level 12 in debian/compat, ensure debian/control has:
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.
Estes são os níveis de compatibilidade disponíveis:
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.
Este modo está descontinuado.
Este modo está descontinuado.
Este modo está descontinuado.
(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)
Os principais efeitos disto são:
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.
This compatibility feature had a bug since its inception in debhelper/9.20130516 that made it fail to apply in compat 9 and earlier. As there has been no reports of issues caused by this bug in those ~5 years, this item have been removed rather than fixed.
Por favor note que a ferramenta dh_installsystemd tem um comportamento ligeiramente diferente em alguns casos (ex. quando se usa o parâmetro --name).
A grande maioria dos pacotes não serão afectados por esta alteração.
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.
Migration note: A bug in debhelper 11 up to 11.1.5 made dh_installinfo incorrectly ignore --sourcedir.
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.
Note that if a given source package only contains a single binary package in debian/control or none of the packages are -doc packages, then this change is not relevant for that source package and you can skip to the next change.
By default, these tools will now attempt to determine a "main package for the documentation" (called a doc-main-package from here on) for every -doc package. If they find such a doc-main-package, they will now install the documentation into the path /usr/share/doc/doc-main-package in the given doc package. I.e. the path can change but the documentation is still shipped in the -doc package.
The --doc-main-package option can be used when the auto-detection is insufficient or to reset the path to its previous value if there is a reason to diverge from Debian policy recommendation.
Some documentation will not be affected by this change. These exceptions include the copyright file, changelog files, README.Debian, etc. These files will still be installed in the path /usr/share/doc/package.
Esta alteração fazer com que as ferramentas processem mais ficheiros que anteriormente.
As alterações a partir de v11 sã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.
If a particular upstream package does not use the correct default, the parameter can often be passed manually via dh_auto_configure(1). E.g. via the following example:
override_dh_auto_configure: dh_auto_configure -- --libexecdir=/usr/libexec
Note the -- before the --libexecdir parameter.
If you have an override for dh_installinit (e.g. to call it with --no-start) then you will probably need one for dh_installsystemd as well now.
This change makes dh_installinit inject a misc:Pre-Depends for init-system-helpers (>= 1.54~). Please ensure that the package lists ${misc:Pre-Depends} in its Pre-Depends field before upgrading to compat 12.
Changes from v12 are:
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).
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.
Note que não importa se um pacote está activado ou desactivado por predefinição.
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}"); } }
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.
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.
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.
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"
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.
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
This is intended to be used by downstreams or specific local configurations that require a debhelper addon to be run during multiple builds without having to patch a large number of rules file. If at all possible, this should be avoided in favor of a --with flag in the rules file.
Joey Hess <joeyh@debian.org>
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.
2019-02-23 | 12.1.1 |