Capítulo 4. Archivos necesarios en el directorio debian

Tabla de contenidos

4.1. El archivo control
4.2. El archivo copyright
4.3. El archivo changelog
4.4. El archivo rules
4.4.1. Objetivos del archivo rules
4.4.2. Archivo rules predeterminado
4.4.3. Personalización del archivo rules

The rewrite of this tutorial document with updated contents and more practical examples is available as Guide for Debian Maintainers. Please use this new tutorial as the primary tutorial document.

Ahora hay un nuevo subdirectorio bajo el directorio principal del programa («gentoo-0.9.12»), que se llama debian. Hay algunos ficheros en este directorio que debemos editar para adaptar el comportamiento del paquete. La parte más importante es modificar los ficheros control, changelog, copyright y rules que son necesarios en todos los paquetes. [27]

Este fichero contiene varios valores que dpkg, dselect, apt-get, apt-cache, aptitude y otras herramientas de gestión de paquetes usarán para gestionar el paquete. Su contenido está concretado en Debian Policy Manual, 5 'Control files and their fields'.

Aquí está el fichero de control que dh_make construye para nosotros:

 1 Source: gentoo
 2 Section: unknown
 3 Priority: optional
 4 Maintainer: Josip Rodin <[email protected]>
 5 Build-Depends: debhelper (>=10)
 6 Standards-Version: 4.0.0
 7 Homepage: <insert the upstream URL, if relevant>
 8
 9 Package: gentoo
10 Architecture: any
11 Depends: ${shlibs:Depends}, ${misc:Depends}
12 Description: <insert up to 60 chars description>
13  <insert long description, indented with spaces>

(He añadido los números de línea)

Lines 1–7 are the control information for the source package. Lines 9–13 are the control information for the binary package.

La línea 1 es el nombre del paquete fuente.

La línea 2 es la sección de la distribución dentro de la que estará este paquete.

Como puede que hayas notado, Debian está dividida en secciones: main (principal, los programas libres o de código abierto), non-free (no libre, los programas que no son libres, que son de propietario) y contrib (programas libres que dependen de programas no libre o de propietario). Bajo ellas hay subdivisiones lógicas que describen en una palabra qué paquetes hay dentro. Así que tenemos admin para programas que sólo usa un administrador, base para las herramientas básicas, devel para las herramientas de programación, doc para la documentación, libs para las bibliotecas, mail para lectores y demonios de correo-e, net para aplicaciones y demonios de red, x11 para programas específicos de X11, y muchos más. [28]

Vamos a cambiarla para que ponga «x11». El prefijo main/ ya va implícito, así que podemos omitirlo.

La línea 3 describe cómo de importante es para el usuario la instalación de este paquete [29].

  • La prioridad optional se utiliza para paquetes nuevos que no entran en conflicto con otros de prioridad required, important o standard.

«Section» y «Priority» se usan en las interfaces como aptitude cuando ordenan los paquetes y seleccionan los predeterminados. Una vez que envíes el paquete a Debian, el valor de estos dos campos puede no ser aceptado por los responsables del archivo, en cuyo caso te lo notificarán por correo electrónico.

Como es un paquete de prioridad normal y no tiene conflictos con ningún otro, lo dejaremos con prioridad optional (opcional).

La línea 4 es el nombre y correo electrónico del desarrollador. Asegúrate de que este campo incluye una cabecera válida To («A:»), para una dirección de correo electrónico, porque después de que envíes el paquete, el sistema de seguimiento de errores («Bug Tracking System») utilizará esta dirección para enviarte los mensajes de los errores. Evita usar comas, el signo «&» y paréntesis.

Line 5 includes the list of packages required to build your package as the Build-Depends field. You can also have the Build-Depends-Indep field as an additional line here. [30] Some packages like gcc and make which are required by the build-essential package are implied. If you need to have other tools to build your package, you should add them to these fields. Multiple entries are separated with commas; read on for the explanation of binary package dependencies to find out more about the syntax of these lines.

  • Para todos los paquetes construidos con la orden dh en el archivo debian/rules, estará debhelper (>=9) en el campo Build-Depends para ajustarse a las normas de Debian respecto al objetivo clean.

  • Source packages which have binary packages with Architecture: any are rebuilt by the autobuilder. Since this autobuilder procedure installs only the packages listed in the Build-Depends field before running debian/rules build (see Sección 6.2, “Autobuilder”), the Build-Depends field needs to list practically all the required packages, and Build-Depends-Indep is rarely used.

  • En el caso de los paquetes de fuentes que incluyen paquetes binarios únicamente del tipo Architecture: all, el campo Build-Depends-Indep debe listar todos los paquetes excepto los listados en el campo Build-Depends para satisfacer los requerimientos de las normas de Debian respecto al objetivo clean.

En caso de duda, utiliza el campo Build-Depends [31].

Para saber qué paquetes son necesarios para compilar el tuyo ejecuta esta orden:

$ dpkg-depcheck -d ./configure

Para buscar manualmente las dependencias de compilación para el paquete /usr/bin/nombre_del_paquete, deberías ejecutar:

$ objdump -p /usr/bin/nombre_del_paquete | grep NEEDED

and for each library listed (e.g., libfoo.so.6), execute

$ dpkg -S libfoo.so.6

Debes utilizar la versión -dev de cada uno de los paquetes dentro de la entrada Build-Depends. Si usas ldd para este propósito, también te informará de las dependencias de bibliotecas indirectas, lo que puede llevar a que se introduzcan demasiadas dependencias de construcción.

gentoo también depende de xlibs-dev, libgtk1.2-dev y libglib1.2-dev para su construcción, así que lo añadiremos junto a debhelper.

La línea 6 es la versión de los estándares definidos en las normas de Debian que sigue este paquete, es decir, la versión del manual de normas que has leído mientras haces tu paquete (véase «Debian Policy Manual»).

En la línea 7 está la dirección URL de la página web del programa (donde has obtenido las fuentes).

La línea 9 es el nombre del paquete binario. Este suele ser el mismo que el del paquete fuente, aunque no es necesario que sea así siempre.

La linea 10 describe las arquitecturas en las que puede compilarse el paquete binario. Este valor suele ser uno de los listados a continuación dependiendo del tipo de paquete [32]:

  • Architecture: any

    • El paquete binario generado depende de la arquitectura si consiste en un programa escrito en un lenguaje compilado.

  • Architecture: all

    • El paquete binario generado es independiente de la arquitectura si consiste en archivos de texto, imágenes o guiones escritos en lenguajes interpretados.

Eliminamos la línea 10 debido a que el programa está escrito en C. dpkg-gencontrol(1) la rellenará con el valor apropiado cuando se compile este paquete en cualquier arquitectura para la cual pueda ser compilado.

Si tu paquete es independiente de la arquitectura (por ejemplo, un documento, un guión escrito en Perl o para el intérprete de órdenes), cambia esto a all, y consulta más adelante Sección 4.4, “El archivo rules sobre cómo usar la regla binary-indep en lugar de binary-arch para construir el paquete.

La línea 11 muestra una de las más poderosas posibilidades del sistema de paquetes de Debian. Los paquetes se pueden relacionar unos con otros de diversas formas. Aparte de Depends (depende de) otros campos de relación son Recommends (recomienda), Suggests (sugiere), Pre-Depends (predepende de), Breaks (rompe a), Conflicts (entra en conflicto con), Provides (provee), Replaces (reemplaza a).

Las herramientas de gestión de paquetes se comportan habitualmente de la misma forma cuando tratan con esas relaciones entre paquetes; si no es así, se explicará en cada caso. (véase dpkg(8), dselect(8), apt(8), aptitude(1), etc.)

He aquí una descripción simplificada de relaciones entre paquetes: [33]

  • Depends:

    No se instalará el programa a menos que los paquetes de los que depende estén ya instalados. Usa esto si tu programa no funcionará de ninguna forma (o se romperá fácilmente) a no ser que se haya instalado un paquete determinado.

  • Recommends:

    Esta opción es para paquetes cuya instalación no es estrictamente necesaria para el funcionamiento de tu programa pero que suelen utilizarse junto con tu programa. Cuando los usuarios instalen tu paquete, todas las interfaces de instalación aconsejaran la instalación de los paquetes recomendados. aptitude y apt-get instalan los paquetes recomendados (pero el usuario puede decidir no hacerlo). dpkg ignora el contenido de este campo.

  • Suggests:

    Utiliza esto para paquetes que funcionarán bien con tu programa pero que no son necesarios en absoluto. Es posible configurar aptitude para que instale los paquetes sugeridos, aunque no es la opción predeterminada. dpkg y apt-get ignorarán estas dependencias.

  • Pre-Depends:

    Esto es más fuerte que Depends. El paquete no se instalará a menos que los paquetes de los que pre-dependa estén instalados y correctamente configurados. Utiliza esto muy poco y sólo después de haberlo discutido en la lista de distribución ([email protected]). En resumidas cuentas: no lo utilices en absoluto :-)

  • Conflicts:

    El paquete no se instalará hasta que todos los paquetes con los que entra en conflicto hayan sido eliminados. Utiliza esto si tu programa no funcionará en absoluto (o fallará fácilmente) si un paquete en concreto está instalado.

  • Breaks:

    Si el paquete se instala, todos los paquetes de la lista se romperán. Normalmente, los paquetes incluidos en la lista Breaks tienen una cláusula de versión anterior. La solución es actualizar los paquetes de la lista a la versión más actual.

  • Provides:

    For some types of packages where there are multiple alternatives, virtual names have been defined. You can get the full list in the virtual-package-names-list.txt.gz file. Use this if your program provides a function of an existing virtual package.

  • Replaces:

    Usa esto si tu programa reemplaza ficheros de otro paquete o reemplaza totalmente otro paquete (generalmente se usa conjuntamente con Conflicts). Se sobrescribirán los ficheros de los paquetes indicados con los ficheros de tu paquete.

Todos estos campos tienen una sintaxis uniforme: se trata de una lista de nombres de paquetes separados por comas. Estos nombres de paquetes también puede ser listas de paquetes alternativos, separados por los símbolos de barra vertical «|» (símbolos tubería).

Los campos pueden restringir su aplicación a versiones determinadas de cada paquete nombrado. Esto se hace listando después de cada nombre de paquete individual las versiones entre paréntesis, e indicando antes del número de versión una relación de la siguiente lista. Las relaciones permitidas son: <<, <=, =, >= y >> para estrictamente anterior, anterior o igual, exactamente igual, posterior o igual o estrictamente posterior, respectivamente. Por ejemplo:

Depends: foo (>= 1.2), libbar1 (= 1.3.4)
Conflicts: baz
Recommends: libbaz4 (>> 4.0.7)
Suggests: quux
Replaces: quux (<< 5), quux-foo (<= 7.6)

La última funcionalidad que necesitas conocer es ${shlibs:Depends},${perl:Depends}, ${misc:Depends}, etc.

Después de que tu paquete se compile y se instale en el directorio temporal, dh_shlibdeps(1) lo escaneará en busca de binarios y bibliotecas para determinar las dependencias de bibliotecas compartidas. Esta lista se utiliza para la sustitución de ${shlibs:Depends}.

La orden dh_perl(1) genera las dependencias de Perl. Genera la lista de dependencias de perl o perlapi para cada paquete binario. Esta lista es utilizada para substituir a ${perl:Depends}.

Algunas órdenes de debhelper determinan las dependencias de los paquetes listados anteriormente. Cada orden generar una lista de los paquetes necesarios para cada paquete binario. La lista de estos paquetes se usará para substituir a ${misc:Depends}.

La orden dh_gencontrol(1) genera el archivo DEBIAN/control para cada paquete binario substituyendo ${shlibs:Depends}, ${perl:Depends}, ${misc:Depends}, etc.

Después de decir todo esto, podemos dejar la línea de Depends exactamente como está ahora e insertar otra línea tras ésta con el texto Suggests: file, porque gentoo utiliza algunas funciones proporcionadas por el paquete/programa file.

La línea 9 es la dirección URL del programa. Supongamos que es http://www.obsession.se/gentoo/.

La línea 12 es una descripción corta. La mayor parte de los monitores (en realidad, de las terminales en modo de texto) de la gente son de 80 columnas de ancho, así que no debería tener más de 60 caracteres. Cambiaré esto a fully GUI-configurable, two-pane X file manager. («Gestor de ficheros GTK+ completamente configurable por GUI»).

La línea 13 es donde va la descripción larga del paquete. Debería ser al menos de un párrafo que dé más detalles del paquete. La primera columna de cada línea debería estar vacía. No puede haber líneas en blanco, pero puedes poner un . (punto) en una columna para simularlo. Tampoco debe haber más de una línea en blanco después de la descripción completa [34].

Vamos a añadir los campos Vcs-* para documentar la localización del sistema de control de versiones (VCS) entre las lineas 6 y 7 [35]. Se supone que el paquete gentoo está alojado en el servicio «Debian Alioth Git» en git://git.debian.org/git/collab-maint/gentoo.git.

Aquí está el archivo control actualizado:

 1 Source: gentoo
 2 Section: x11
 3 Priority: optional
 4 Maintainer: Josip Rodin <[email protected]>
 5 Build-Depends: debhelper (>=10), xlibs-dev, libgtk1.2-dev, libglib1.2-dev
 6 Standards-Version: 4.0.0
 7 Vcs-Git: https://anonscm.debian.org/git/collab-maint/gentoo.git
 8 Vcs-browser: https://anonscm.debian.org/git/collab-maint/gentoo.git
 9 Homepage: http://www.obsession.se/gentoo/
10
11 Package: gentoo
12 Architecture: any
13 Depends: ${shlibs:Depends}, ${misc:Depends}
14 Suggests: file
15 Description: fully GUI-configurable, two-pane X file manager
16  gentoo is a two-pane file manager for the X Window System. gentoo lets the
17  user do (almost) all of the configuration and customizing from within the
18  program itself. If you still prefer to hand-edit configuration files,
19  they're fairly easy to work with since they are written in an XML format.
20  .
21  gentoo features a fairly complex and powerful file identification system,
22  coupled to an object-oriented style system, which together give you a lot
23  of control over how files of different types are displayed and acted upon.
24  Additionally, over a hundred pixmap images are available for use in file
25  type descriptions.
26  .
29  gentoo was written from scratch in ANSI C, and it utilizes the GTK+ toolkit
30  for its interface.

(He añadido los números de línea)

Este fichero contiene la información sobre los recursos, licencia y derechos de autoría de las fuentes originales del paquete. El formato no está definido en las normas, pero sí sus contenidos en «Debian Policy Manual, 12.5 "Copyright information" y DEP-5: Machine-parseable debian/copyright proporciona directrices sobre su formato.

dh_make proporciona una plantilla para el archivo copyright. Con la opción --copyright gpl2 se consigue la plantilla para el paquete gentoo con la licencia GPL-2.

You must fill in missing information to complete this file, such as the place you got the package from, the actual copyright notice, and the license. For certain common free software licenses (GNU GPL-1, GNU GPL-2, GNU GPL-3, LGPL-2, LGPL-2.1, LGPL-3, GNU FDL-1.2, GNU FDL-1.3, Apache-2.0, 3-Clause BSD, CC0-1.0, MPL-1.1, MPL-2.0 or the Artistic license), you can just refer to the appropriate file in the /usr/share/common-licenses/ directory that exists on every Debian system. Otherwise, you must include the complete license.

En resumen, el archivo copyright del paquete gentoo debería ser similar a esto:

 1 Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
 2 Upstream-Name: gentoo
 3 Upstream-Contact: Emil Brink <[email protected]>
 4 Source: http://sourceforge.net/projects/gentoo/files/
 5
 6 Files: *
 7 Copyright: 1998-2010 Emil Brink <[email protected]>
 8 License: GPL-2+
 9
10 Files: icons/*
11 Copyright: 1998 Johan Hanson <[email protected]>
12 License: GPL-2+
13
14 Files: debian/*
15 Copyright: 1998-2010 Josip Rodin <[email protected]>
16 License: GPL-2+
17
18 License: GPL-2+
19  This program is free software; you can redistribute it and/or modify
20  it under the terms of the GNU General Public License as published by
21  the Free Software Foundation; either version 2 of the License, or
22  (at your option) any later version. 
23  .
24  This program is distributed in the hope that it will be useful,
25  but WITHOUT ANY WARRANTY; without even the implied warranty of
26  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
27  GNU General Public License for more details.
28  .
29  You should have received a copy of the GNU General Public License along
30  with this program; if not, write to the Free Software Foundation, Inc.,
31  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
32  .
33  On Debian systems, the full text of the GNU General Public
34  License version 2 can be found in the file
35  '/usr/share/common-licenses/GPL-2'.

(He añadido los números de línea)

Por favor, sigue el COMO redactado por «ftpmasters» y enviado a «debian-devel-announce»: http://lists.debian.org/debian-devel-announce/2006/03/msg00023.html.

Este es un fichero requerido, con un formato especial descrito en Debian Policy Manual, 4.4 "debian/changelog". Este es el formato utilizado por dpkg y otros programas para obtener el número de versión, revisión, distribución y urgencia de tu paquete.

Para ti es también importante, ya que es bueno tener documentados todos los cambios que hayas hecho. Esto ayudará a las personas que se descarguen tu paquete para ver si hay temas pendientes en el paquete que deberían conocer de forma inmediata. Se guardará como /usr/share/doc/gentoo/changelog.Debian.gz en el paquete binario.

dh_make genera uno predeterminado, el cual es como sigue:

1  gentoo (0.9.12-1) unstable; urgency=medium
2
3   * Initial release. (Closes: #nnnn)  <nnnn is the bug number of your ITP>
4
5  -- Josip Rodin <[email protected]>  Mon, 22 Mar 2010 00:37:31 +0100
6

(He añadido los números de línea)

Line 1 is the package name, version, distribution, and urgency. The name must match the source package name; distribution should be unstable, and urgency should be set to medium unless there is any particular reason for other values.

Lines 3-5 are a log entry, where you document changes made in this package revision (not the upstream changes — there is a special file for that purpose, created by the upstream authors, which you will later install as /usr/share/doc/gentoo/changelog.gz). Let's assume your ITP (Intent To Package) bug report number was 12345. New lines must be inserted just below the uppermost line that begins with * (asterisk). You can do it with dch(1). You can edit this manually with a text editor as long as you follow the formatting convention used by the dch(1).

In order to prevent a package being accidentally uploaded before completing the package, it is a good idea to change the distribution value to an invalid distribution value of UNRELEASED.

Terminarás con algo así:

1  gentoo (0.9.12-1) UNRELEASED; urgency=low
2
3   * Initial Release. Closes: #12345
4   * This is my first Debian package.
5   * Adjusted the Makefile to fix $(DESTDIR) problems.
6
7  -- Josip Rodin <[email protected]>  Mon, 22 Mar 2010 00:37:31 +0100
8

(He añadido los números de línea)

Cuando estés satisfecho con los cambios realizados y estén documentados en el fichero changelog, entonces cambie el nombre de la distribución de UNRELEASED a unstable (o bien a experimental). [36]

Puedes leer más sobre cómo actualizar el fichero changelog más adelante en Capítulo 8, Actualizar el paquete .

Now we need to take a look at the exact rules that dpkg-buildpackage(1) will use to actually create the package. This file is in fact another Makefile, but different from the one(s) in the upstream source. Unlike other files in debian, this one is marked as executable.

Cada archivo rules, como cualquier otro archivo Makefile, se compone de varias reglas, cada una de ellas define el objetivo y cómo se ejecuta [37]. Cada nueva regla empieza con la declaración del objetivo en la primera columna. Las líneas siguientes empiezan con un código de tabulación (ASCII 9) y especifican cómo llevar a cabo ese objetivo. Las líneas en blanco o que empiezan con # se tratan como comentarios y se ignoran [38].

A rule that you want to execute is invoked by its target name as a command line argument. For example, debian/rules build and fakeroot make -f debian/rules binary execute rules for build and binary targets, respectively.

A continuación se proporciona una explicación simplificada de los distintos objetivos.

  • clean (obligatorio): elimina todos los archivos generados, compilados o innecesarios del árbol de directorios de las fuentes.

  • build (obligatorio): para la construcción de archivos compilados a partir de los archivos fuente o la construcción de documentos formateados.

  • objetivo build-arch (obligatorio): para la compilación de las fuentes en programas compilados (dependientes de la arquitectura) en el árbol de directorios de compilación.

  • objetivo build-indep (obligatorio): para la compilación de las fuentes en documentos formateados (independientes de la arquitectura) en el árbol de directorios de compilación.

  • install (opcional): para la instalación en la estructura de directorios temporal bajo el directorio debian de los archivos para cada uno de los paquetes binarios. Si existe el objetivo binary*, dependerá de este.

  • binary (obligatorio): para la construcción de cada uno de los paquetes binarios (combinado con los objetivos binary-arch y binary-indep) [39].

  • binary-arch (obligatorio): para la construcción de paquetes dependientes de la arquitectura (Architecture: any) [40].

  • binary-indep (obligatorio): para la construcción de paquetes independientes de la arquitectura (Architecture: all) [41].

  • get-orig-source (opcional): para obtener la versión más reciente de las fuentes originales desde el lugar de almacenaje del autor.

Probablemente ya te hayas perdido, pero todo quedará más claro después de ver el fichero rules que dh_make pone por omisión.

La nueva versión de dh_make genera un archivo rules muy simple pero poderoso utilizando la orden dh:

 1 #!/usr/bin/make -f
 2 # See debhelper(7) (uncomment to enable)
 3 # output every command that modifies files on the build system.
 4 #DH_VERBOSE = 1
 5 
 6 # see FEATURE AREAS in dpkg-buildflags(1)
 7 #export DEB_BUILD_MAINT_OPTIONS = hardening=+all
 8
 9 # see ENVIRONMENT in dpkg-buildflags(1)
10 # package maintainers to append CFLAGS
11 #export DEB_CFLAGS_MAINT_APPEND  = -Wall -pedantic
12 # package maintainers to append LDFLAGS
13 #export DEB_LDFLAGS_MAINT_APPEND = -Wl,--as-needed
14 
15
16 %:
17         dh $@ 

(He añadido los números de línea y añadido algunos comentarios. En el fichero debian/rules los espacios iniciales de las líneas son tabulaciones)

Probablemente estés familiarizado con líneas como la primera de guiones escritos en shell o Perl. Esta línea indica que el fichero debe ejecutarse con/usr/bin/make.

La linea 4 debe descomentarse para asignar el valor 1 a la variable DH_VERBOSE. Entonces, la orden dh mostrará (en el terminal) las órdenes dh_* ejecutadas por dh. Puedes añadir la linea export DH_OPTIONS=-v aquí. Así podrás ver la salida de la ejecución de cada orden dh_* y solucionar los problemas que se produzcan. Esto te ayudará a entender como funciona el archivo rules y a solucionar problemas. Esta nueva orden dh es parte fundamental de las herramientas debhelper y no te esconde nada.

Lines 16 and 17 are where all the work is done with an implicit rule using the pattern rule. The percent sign means "any targets", which then call a single program, dh, with the target name. [42] The dh command is a wrapper script that runs appropriate sequences of dh_* programs depending on its argument. [43]

  • debian/rules clean ejecuta dh clean, que a su vez ejecuta lo siguiente:

    dh_testdir
    dh_auto_clean
    dh_clean
    
  • debian/rules build runs dh build, which in turn runs the following:

    dh_testdir
    dh_auto_configure
    dh_auto_build
    dh_auto_test
    
  • fakeroot debian/rules binary runs fakeroot dh binary, which in turn runs the following[44]:

    dh_testroot
    dh_prep
    dh_installdirs
    dh_auto_install
    dh_install
    dh_installdocs
    dh_installchangelogs
    dh_installexamples
    dh_installman
    dh_installcatalogs
    dh_installcron
    dh_installdebconf
    dh_installemacsen
    dh_installifupdown
    dh_installinfo
    dh_installinit
    dh_installmenu
    dh_installmime
    dh_installmodules
    dh_installlogcheck
    dh_installlogrotate
    dh_installpam
    dh_installppp
    dh_installudev
    dh_installwm
    dh_installxfonts
    dh_bugfiles
    dh_lintian
    dh_gconf
    dh_icons
    dh_perl
    dh_usrlocal
    dh_link
    dh_compress
    dh_fixperms
    dh_strip
    dh_makeshlibs
    dh_shlibdeps
    dh_installdeb
    dh_gencontrol
    dh_md5sums
    dh_builddeb
    
  • fakeroot debian/rules binary-arch runs fakeroot dh binary-arch, which in turn runs the same sequence as fakeroot dh binary but with the -a option appended for each command.

  • fakeroot debian/rules binary-indep runs fakeroot dh binary-indep, which in turn runs almost the same sequence as fakeroot dh binary but excluding dh_strip, dh_makeshlibs, and dh_shlibdeps with the -i option appended for each remaining command.

La función de las órdenes dh_* puede deducirse de su nombre [45]. A continuación se resume las funciones de las órdenes más importantes asumiendo que se utiliza un sistema de compilación basado en un archivo Makefile [46]:

  • dh_auto_clean normalmente ejecuta lo siguiente, siempre que exista un fichero Makefile con el objetivo distclean[47].

    make distclean
    
  • dh_auto_configure ejecuta lo siguiente si existe el archivo ./configure (se han abreviado los argumentos para facilitar la lectura).

    ./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var ...
    
  • dh_auto_build ejecuta lo siguiente para ejecutar el primer objetivo del archivo Makefile (supuesto que este existe).

    make
    
  • dh_auto_test ejecuta lo siguiente si existe el objetivo test en el archivo Makefile [48].

    make test
    
  • dh_auto_install ejecuta lo siguiente si en el archivo Makefile existe el objetivo install (se ha truncado la linea para permitir su lectura).

    make install \
      DESTDIR=/ruta/a/paquete_versión-revisión/debian/paquete
    

Los objetivos que deben ejecutarse con la orden fakeroot contienen dh_testroot. Si no utilizas la orden para simular la ejecución por el usuario «root», se producirá un error que detendrá la ejecución.

Es importante tener presente que el archivo rules que genera dh_make es sólo una sugerencia. Será suficiente para la mayoría de los paquetes simples, pero no dejes de adaptarlo a tus necesidades en paquetes más complejos.

A pesar de que install no es un objetivo obligatorio, se admite su uso. fakeroot dh install se comporta como fakeroot dh binary pero se detiene después de dh_fixperms.

Puedes realizar muchos cambios para adaptar el archivo rules construido por la orden dh.

La orden dh $@ permite las siguientes adaptaciones [49]:

  • Añadir la orden dh_python2 (la mejor opción para Python) [50].

    • Añade el paquete python en el campo Build-Depends.

    • Utiliza dh $@ --with python2 en su lugar.

    • Esto gestiona el módulo Python utilizando las funcionalidades de python.

  • Añadir la orden pysupport. (obsoleto)

    • Añade el paquete python-support en el campo Build-Depends.

    • Utiliza dh $@ --with pysupport.

    • Esto gestiona el módulo Python utilizando las funcionalidades de python-support.

  • Añadir la orden dh_pycentral. (obsoleto)

    • Añade el paquete python-central en el campo Build-Depends.

    • Utiliza dh $@ --with python-central en su lugar.

    • Esto desactiva la orden dh_pysupport.

    • Esto gestiona el módulo Python utilizando las funcionalidades de python-central.

  • Añadir la orden dh_installtex.

    • Añade el paquete tex-common en el campo Build-Depends.

    • Utiliza dh $@ --with tex en su lugar.

    • Esto registra el tipo de letra «Type 1», los patrones de separación de palabras («hyphenation patterns») o los formatos TeX.

  • Añadir las órdenes dh_quilt_patch y dh_quilt_unpatch.

    • Añade el paquete quilt en el campo Build-Depends.

    • Utiliza dh $@ --with quilt en su lugar.

    • Esto aplica o revierte los parches en los archivos de las fuentes originales, basándose en los ficheros del directorio debian/patches en los paquetes con el formato 1.0.

    • Esta adaptación no es necesaria para los paquetes con el nuevo formato 3.0 (quilt).

  • Añadir la orden dh_dkms.

    • Añade el paquete dkms en el campo Build-Depends.

    • Utiliza dh $@ --with dkms en su lugar.

    • Esto controla correctamente el uso de DKMS en la construcción de paquetes del núcleo.

  • Añadir las ordenes dh_autotools-dev_updateconfig y dh_autotools-dev_restoreconfig.

    • Añade el paquete autotools-dev en el campo Build-Depends.

    • Utiliza dh $@ --with autotools-dev en su lugar.

    • Esto actualiza y restaura config.sub y config.guess.

  • Añadir la orden dh_autoreconf y dh_autoreconf_clean.

    • Añade el paquete dh-autoreconf en el campo Build-Depends.

    • Utiliza dh $@ --with autoreconf en su lugar.

    • Así se actualiza los archivos del sistema de compilación GNU y los restaura después de la compilación.

  • Añadir la orden dh_girepository.

    • Añade el paquete gobject-introspection en el campo Build-Depends.

    • Utiliza dh $@ --with gir en su lugar.

    • Esto calcula las dependencias de paquetes de envío de datos de introspección de «GObject» y genera la substitución de la variable ${gir:Depends} por las dependencias del paquete.

  • Añadir la funcionalidad de autocompletar a bash.

    • Añade el paquete bash-completion en el campo Build-Depends.

    • Utiliza dh $@ --with bash-completion en su lugar.

    • Esto instala la función autocompletar de bash utilizando el archivo de configuración de debian/nombre_del_paquete.bash-completion.

Muchas de las órdenes dh_* invocadas por la nueva orden dh son personalizables mediante sus archivos de configuración en el directorio debian. Véase Capítulo 5, Otros ficheros en el directorio debian. y los manuales (las «manpage») para cada orden.

Algunas órdenes dh_* invocadas por la nueva orden dh pueden precisar la adición de argumentos (opciones), la ejecución de órdenes adicionales u omitirlas del todo. Para estos casos, deberás añadir el objetivo override_dh_nombre_de_la_orden con las reglas a ejecutar en el archivo rules sólo para la orden dh_nombre_de_la_orden que vas a cambiar. Se trata de decir ejecútame a mí en su lugar [51].

Las ordenes dh_auto_* hacen más cosas que las expuestas aquí. El uso de ordenes equivalentes más sencillas en lugar de éstas en los objetivos override_dh_* (excepto el objetivo override_dh_auto_clean) es una mala idea ya que puede eliminar funciones inteligentes de debhelper.

Si vas a guardar los datos de configuración del paquete gentoo en el directorio /etc/gentoo en lugar del directorio habitual /etc, debes anular la ejecución del argumento predeterminado --sysconfig=/etc de la orden dh_auto_configure por ./configure con lo siguiente:

override_dh_auto_configure:
        dh_auto_configure -- --sysconfig=/etc/gentoo

The arguments given after -- are appended to the default arguments of the auto-executed program to override them. Using the dh_auto_configure command is better than directly invoking the ./configure command here since it will only override the --sysconfig argument and retain any other, benign arguments to the ./configure command.

Si el Makefile de las fuentes de gentoo requiere la especificación del objetivo build para compilarlo [52], puedes añadir un objetivo override_dh_auto_build para anularlo.

override_dh_auto_build:
        dh_auto_build -- build

De esta forma se garantiza la ejecución de $(MAKE) con todos los argumentos predeterminados dados por la orden dh_auto_build y del argumento build.

Si el Makefile de las fuentes de gentoo requiere la especificación del objetivo packageclean para limpiarlo, en lugar de los objetivos distclean o clean en el archivo Makefile, puedes añadir un objetivo override_dh_auto_clean para habilitarlo.

override_dh_auto_clean:
        $(MAKE) packageclean

Si el Makefile de las fuentes de gentoo contiene un objetivo test que no deseas que se ejecute en la construcción del paquete Debian, puedes usar un objetivo override_dh_auto_test sin órdenes para ignorarlo.

override_dh_auto_test:

Si gentoo contiene el poco frecuente archivo de cambios del autor con el nombre FIXES, dh_installchangelogs no lo instalará por omisión. La orden dh_installchangelogs requiere como argumento FIXES para instalarlo [53].

override_dh_installchangelogs:
        dh_installchangelogs FIXES

Cuando utilizas el nuevo programa dh, la utilización explícita de objetivos como los listados en Sección 4.4.1, “Objetivos del archivo rules (excepto get-orig-source) puede dificultar la correcta comprensión de sus efectos exactos. Por favor, limita el uso de objetivos explícitos a objetivos del tipo override_dh_* y de forma que sean completamente independientes entre sí (siempre que sea posible).



[27] En este capitulo, los archivos del directorio debian se nombran sin el antecedente debian/ para simplificar y siempre que no haya posibilidad de equívocos.

[31] Este caso poco frecuente, está documentado en Debian Policy Manual, Footnotes 55. Esto se debe al funcionamiento de dpkg-buildpackage, no al uso de la orden dh en el archivo debian/rules. Esto también se aplica al «auto build system for Ubuntu».

[34] Las descripciones deben redactarse en inglés. Las traducciones de estas descripciones son proporcionados por The Debian Description Translation Project - DDTP.

[36] Si utiliza la orden dch -r para realizar este último cambio, asegúrese que guarda el archivo changelog explícitamente con el editor.

[37] You can start learning how to write a Makefile from Debian Reference, 12.2. "Make". The full documentation is available as http://www.gnu.org/software/make/manual/html_node/index.html or as the make-doc package in the non-free archive area.

[39] Este objetivo es utilizado por dpkg-buildpackage como en Sección 6.1, “(Re)construcción completa”.

[40] Este objetivo es utilizado por dpkg-buildpackage -B como en Sección 6.2, “Autobuilder”.

[41] Este objetivo es utilizado por dpkg-buildpackage -A.

[42] This uses the new debhelper v7+ features. Its design concepts are explained in Not Your Grandpa's Debhelper presented at DebConf9 by the debhelper upstream. Under lenny, dh_make created a much more complicated rules file with explicit rules and many dh_* scripts listed for each one, most of which are now unnecessary (and show the package's age). The new dh command is simpler and frees us from doing the routine work "manually". You still have full power to customize the process with override_dh_* targets. See Sección 4.4.3, “Personalización del archivo rules. It is based only on the debhelper package and does not obfuscate the package building process as the cdbs package tends to do.

[43] You can verify the actual sequences of dh_* programs invoked for a given target without really running them by invoking dh target --no-act or debian/rules -- 'target --no-act'.

[44] El siguiente ejemplo presupone que su fichero debian/compat tiene un valor igual o superior a 9 para evitar invocar cualquier orden «python» automáticamente.

[45] Para una descripción completa de la función de cada guión dh_* y de sus opciones, lee los manuales respectivos así como la documentación de debhelper.

[46] These commands support other build environments, such as setup.py, which can be listed by executing dh_auto_build --list in a package source directory.

[47] En realidad busca el primer objetivo distclean, realclean o clean disponible en el Makefile y lo ejecuta.

[48] En realidad busca el primero de los objetivos test o check en el archivo Makefile y lo ejecuta.

[49] Si un paquete instala el archivo /usr/share/perl5/Debian/Debhelper/Sequence/nombre_personalizado.pm puedes activar la función adaptada con dh $@ --with nombre_personalizado.

[50] Es preferible el uso de la orden dh_python2 respecto a la orden dh_pysupport u dh_pycentral. No uses la orden dh_python.

[51] En lenny, cuando querías cambiar el comportamiento de un programa dh_* tenías que encontrar la línea adecuada en el archivo rules y cambiarla.

[52] dh_auto_build sin argumentos ejecutará el primer objetivo del archivo Makefile.

[53] Los archivos debian/changelog y debian/NEWS siempre se instalan automáticamente. También se busca el archivo de cambios del autor para cambiar el nombre a minúsculas y por su coincidencia con changelog, changes, changelog.txt, y changes.txt.