Capítulo 4. Archivos necesarios en el directorio `debian`

# Capítulo 4. Archivos necesarios en el directorio `debian`

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]

## 4.1. El archivo `control`

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 <joy-mg@debian.org>
     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 (debian-devel@lists.debian.org). 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 <joy-mg@debian.org>
     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)

## 4.2. El archivo `copyright`

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 <emil@obsession.se>
     4 Source: http://sourceforge.net/projects/gentoo/files/
     5
     6 Files: *
     7 Copyright: 1998-2010 Emil Brink <emil@obsession.se>
     8 License: GPL-2+
     9
    10 Files: icons/*
    11 Copyright: 1998 Johan Hanson <johan@tiq.com>
    12 License: GPL-2+
    13
    14 Files: debian/*
    15 Copyright: 1998-2010 Josip Rodin <joy-mg@debian.org>
    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.

## 4.3. El archivo `changelog`

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 <joy-mg@debian.org>  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 <joy-mg@debian.org>  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 .

## 4.4. El archivo `rules`

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.

### 4.4.1. Objetivos del archivo `rules`

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.

### 4.4.2. Archivo `rules` predeterminado

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.

### 4.4.3. Personalización del archivo `rules`

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.

[28] Consulta normas de Debian, 2.4 'Secciones' y Lista de secciones en `sid`.

[29] Véase Debian Policy Manual, 2.5 'Priorities'.

[30] Consulta Debian Policy Manual, 7.7 'Relationships between source and binary packages - Build-Depends, Build-Depends-Indep, Build-Conflicts, Build-Conflicts-Indep'.

[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».

[32] Véase Debian Policy Manual 5.6.8 "Architecture" para más detalles.

[33] Consulta Debian Policy Manual, 7 "Declaring relationships between packages".

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

[35] Véase Developer's Reference, 6.2.5. "Version Control System location".

[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.

[38] Debian Policy Manual, 4.9 "Main building script: debian/rules" explica los detalles.

[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`.

Capítulo 3. Modificar las fuentes |  | Capítulo 5. Otros ficheros en el directorio `debian`.