Capítulo 5. Otros ficheros en el directorio debian.

Tabla de contenidos

5.1. Archivo README.Debian (LÉEME.debian)
5.2. Archivo compat
5.3. Archivo conffiles
5.4. Archivos nombre_del_paquete.cron.*
5.5. Archivo dirs
5.6. Archivo nombre_del_paquete.doc-base
5.7. Archivo docs
5.8. Archivo emacsen-*
5.9. Archivo nombre_del_paquete.examples
5.10. Archivos nombre_del_paquete.init y nombre_del_paquete.default
5.11. Archivo install
5.12. Archivo nombre_del_paquete.info
5.13. Archivo nombre_del_paquete.links
5.14. Archivos {nombre_del_paquete.source/} lintian-overrides
5.15. Archivos manpage.*
5.15.1. Archivo manpage.1.ex
5.15.2. Archivo manpage.sgml.ex
5.15.3. Archivo manpage.xml.ex
5.16. Archivo nombre_del_paquete.manpages
5.17. Archivo NEWS
5.18. Archivos {pre,post}{inst,rm}
5.19. Archivo nombre_del_paquete.symbols
5.20. Archivo TODO
5.21. Archivo watch
5.22. Archivo source/format
5.23. Archivo source/local-options
5.24. Archivo source/options
5.25. Archivos patches/*

The dh_make command had major updates since this old document was written. So some parts of this document aren't applicable any more.

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.

The debmake command is used in place of the dh_make command in my new Guide for Debian Maintainers.

Para controlar el trabajo de debhelper en la compilación del paquete, puedes añadir archivos de configuración en el directorio debian. En este capítulo se resumirá lo que puede hacerse con cada uno de ellos y su formato. Por favor, lee «Debian Policy Manual» y «Debian Developer's Reference» para más información.

The dh_make command will create some template configuration files under the debian directory. Take a look at all of them.

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.

En otros casos, dh_make no puede construir plantillas de configuración para debhelper. En estos casos, deberás construir tu mismo los archivos con un editor.

Si quieres utilizar estos archivos en la construcción de tu paquete, haz lo siguiente.

Los archivos de configuración construidos por debhelper que no tienen el prefijo nombre_del_paquete tales como install se aplicaran al primer paquete binario. Si hay varios paquetes binarios, sus configuraciones se especificaran con el prefijo de paquete binario correspondiente en su nombre: así tendrás los archivos paquete-1.install, paquete-2.install, etc.

Cualquier detalle extra o discrepancias entre el programa original y su versión debianizada debería documentarse aquí.

dh_make construye uno predeterminado, y éste es su aspecto:

gentoo for Debian
-----------------
<possible notes regarding this package - if none, delete this file>
 -- Josip Rodin <[email protected]>, Wed, 11 Nov 1998 21:02:14 +0100

Dado que no tenemos que poner nada aquí, elimínalo.Véase dh_installdocs(1).

The compat file defines the debhelper compatibility level. Currently, you should set it to the debhelper v10 as follows:

$ echo 10 > debian/compat

You may use compat level v9 in certain circumstances for compatibility with older systems. However, using any level below v9 is not recommended and should be avoided for new packages.

Una de las cosas más molestas de los programas es cuando pasas mucho tiempo y esfuerzo adaptando un programa (como usuario) y una actualización destroza todos tus cambios. Debian resuelve este problema marcando los ficheros de configuración. [54] Así, cuando actualizas un paquete se te pregunta si deseas mantener la nueva configuración o no.

Desde la versión 3 de debhelper, dh_installdeb(1) considera automáticamente a todos los archivos ubicados en el directorio /etc como «conffiles» (archivos de configuración gestionados por el sistema de paquetes). Así, si todos los «conffiles» están en este directorio no es necesario que los incluyas en este archivo. Para la mayoría de paquetes, la única ubicación de los «conffiles» es /etc por lo que no es necesario generar este archivo.

En el caso de que tu programa utilice ficheros de configuración pero también los reescriba él mismo es mejor no marcarlos como «conffiles». Si lo haces, dpkg informará a los usuarios que verifiquen los cambios de estos ficheros cada vez que lo actualicen.

Si el programa que estás empaquetando requiere que cada usuario modifique los archivos de configuración del directorio /etc, hay dos formas para no marcarlos como archivos «conffiles» y que no sean manipulados por dpkg:

  • Construir un enlace simbólico de los archivos ubicados en /etc que apunten a archivos ubicados en el directorio /var generados por guiones del desarrollador («maintainer scripts»).

  • Poner los archivos generados por los guiones del desarrollador en el directorio /etc.

Para más información sobre los guiones del desarrollador véase Sección 5.18, “Archivos {pre,post}{inst,rm} .

Si tu paquete requiere tareas periódicas para funcionar adecuadamente, puedes usar este fichero como patrón. Puedes establecer la realización de tareas que se ejecuten cada hora, día, semana, mes, o en cualquier otro período de tiempo. Los nombres de los archivos son:

  • nombre_del_paquete.cron.hourly - instalados como /etc/cron.hourly/nombre_del_paquete: se ejecutan cada hora.

  • nombre_del_paquete.cron.daily - instalados como /etc/cron.daily/nombre_del_paquete: se ejecutan cada día, habitualmente por la mañana temprano.

  • nombre_del_paquete.cron.weekly - instalados como /etc/cron.weekly/nombre_del_paquete: se ejecutan cada semana, habitualmente en la mañana del domingo.

  • nombre_del_paquete.cron.hourly - instalados como /etc/cron.hourly/nombre_del_paquete: se ejecutan cada hora.

  • nombre_del_paquete.cron.d - instalados como /etc/cron.d/package: para cualquier otro período de tiempo.

Para los archivos mencionados, su formato es el de guiones «shell». La única excepción son los archivos nombre_del_paquete.cron.d que deben ajustarse al formato descrito en crontab(5).

No es necesario determinar un archivo cron.* para configurar la rotación de registros, para hacer eso consulta dh_installlogrotate(1) y logrotate(8).

Este fichero especifica los directorios que se necesitan pero que por alguna razón no se crean en un proceso de instalación normal (make install DESTDIR=... invocado por dh_auto_install). Generalmente es debido a un problema con el archivo Makefile.

Los archivos listados en el archivo install no requieren la construcción previa de los directorios. Véase Sección 5.11, “Archivo install .

Es recomendable ejecutar en primer lugar la instalación y solo hacer uso de este archivo si se produce algún problema. No debe ponerse la barra inicial en los nombres de los directorios listados en el archivo dirs.

Si tu paquete tiene documentación además de las páginas de manual y de información, puedes utilizar el archivo doc-base para registrarla de modo que el usuario pueda encontrar esta documentación suplementaria con dhelp(1), dwww(1) o doccentral(1).

La documentación incluirá archivos HTML, PS y PDF ubicados en /usr/share/doc/nombre_del_paquete/.

A continuación se muestra cómo es el fichero doc-base de gentoo, gentoo.doc-base:

Document: gentoo
Title: Gentoo Manual
Author: Emil Brink
Abstract: This manual describes what Gentoo is, and how it can be used.
Section: File Management
Format: HTML
Index: /usr/share/doc/gentoo/html/index.html
Files: /usr/share/doc/gentoo/html/*.html

Para más información sobre el formato del archivo véase install-docs(8) y el manual Debian doc-base en la copia local /usr/share/doc/doc-base/doc-base.html/index.html proporcionada por el paquete doc-base.

Para más detalles sobre la instalación de documentación adicional, lee Sección 3.3, “Instalación de los archivos en su destino” .

Este fichero especifica los nombres de los ficheros de documentación que dh_installdocs(1) instalará en el directorio temporal.

Por omisión, se incluirán todos los archivos existentes en los directorios de más alto nivel del código con los nombres BUGS, README*, TODO etc.

También incluiré algunos otros para gentoo:

  BUGS
  CONFIG-CHANGES
  CREDITS
  ONEWS
  README
  README.gtkrc
  TODO

Si tu paquete proporciona ficheros Emacs que pueden ser compilados a bytes («bytescompile») en el momento de la instalación, puedes usar estos ficheros.

El programa dh_installemacsen(1) instalará estos archivos en el directorio temporal .

Elimínalos si no los necesitas.

La orden dh_installexamples(1) instala los archivos y directorios listados en este archivo como archivos de ejemplos.

Si tu paquete es un demonio que necesita ejecutarse en el arranque del sistema, obviamente has desatendido mi recomendación inicial, ¿o no? :-)

Please read dh_installinit(1) dh_installsystemd(1) to provide startup script.

The package.default file will be installed as /etc/default/package. This file sets defaults that are sourced by the init script. This package.default file is most often used to set some default flags or timeouts. If your init script has certain configurable features, you can set them in the package.default file, instead of in the init script itself.

Si el programa original incluye un archivo guión init, tu puedes hacer uso de él o bien descartarlo. Si optas por no hacer uso del guión guión init original, deberás construir uno nuevo en debian/nombre_del_paquete.init. En cualquier caso deberás construir los enlaces simbólicos rc* aunque el guión init original parezca correcto y se instale en el lugar adecuado. Para ello, deberás reescribir el objetivo dh_installinit en el archivo rules con las siguientes líneas:

override_dh_installinit:
        dh_installinit --onlyscripts

Elimina el fichero si no lo necesitas.

If there are files that need to be installed into your package but your standard make install won't do it, put the filenames and destinations into this install file. They are installed by dh_install(1).[55] You should first check that there is not a more specific tool to use. For example, documents should be in the docs file and not in this one.

El archivo install tendrá una línea para cada uno de los archivos a instalar, con el nombre del archivo (relativo al directorio superior de la compilación) seguido de un espacio y a continuación el directorio de instalación (relativo al directorio superior de instalación). Suponiendo que el archivo binario src/archivo_binario no se instalase, deberías utilizar el archivo install como sigue:

src/archivo_binario usr/bin

Al instalarse el paquete, se instalará el archivo binario /usr/bin/nombre_archivo_binario.

En el archivo install puedes escribir el nombre del archivo sin el directorio de instalación siempre que no cambie la ruta relativa de directorio. Este formato se usa en paquetes grandes que separan el resultado de la compilación en múltiples paquetes binarios haciendo uso de nombre_del_paquete-1.install, nombre_del_paquete-2.install, etc.

La orden dh_install retrocederá al directorio debian/tmp para buscar los archivos si no los encuentra en el directorio actual (o en la ubicación que hayas establecido para la búsqueda con --sourcedir).

Si tu paquete utiliza páginas de información («info pages»), podrás instalarlas utilizando dh_installinfo(1) que utilizará el listado del archivo nombre_del_paquete.info.

Si es necesario generar enlaces simbólicos adicionales, como responsable del paquete, en los directorios de compilación del paquete, puedes instalarlos utilizando dh_link(1) haciendo una lista de las rutas completas de los ficheros de origen y de destino en un fichero nombre_del_paquete.links.

If lintian reports an erroneous diagnostic for a case where Debian policy allows exceptions to some rule, you can use package.lintian-overrides or source/lintian-overrides to quieten it. Please read the Lintian User's Manual (https://lintian.debian.org/manual/index.html) and refrain from abusing this.

nombre_del_paquete.lintian-overrides es para un paquete binario con el nombre nombre_del_paquete y es instalado en usr/share/lintian/overrides/nombre_del_paquete por la orden dh_lintian.

El archivo source/lintian-overrides es para los paquetes de fuentes y no se instala.

El/los programa/s debería/n tener una página de manual. Tendrás que escribirla si no existe. La orden dh_make construye varios archivos de plantilla para las páginas de manual. Deberás copiarlos y editarlos para cada programa que no tenga página de manual. Asegúrate de eliminar los que no utilices.

Las páginas de manual se escriben normalmente con nroff(1). La plantilla manpage.1.ex está escrita con nroff. Consulta la página de manual man(7) para una breve descripción sobre como editar el archivo.

El nombre del archivo de manual debería incluir el nombre del programa que está documentando, así que lo renombraremos de manpage a gentoo. El nombre del fichero incluye también .1 como primer sufijo, lo que significa que es una página de manual para una programa de usuario. Asegúrate de verificar que esa sección es la correcta. Aquí tienes una pequeña lista de las secciones de las páginas de manual.

Así que la página de manual de gentoo debería nombrarse como gentoo.1. No había una página de manual gentoo.1 en el paquete fuente así que la escribí renombrando la plantilla manpage.1.ex como gentoo.1 y modificándola usando la información del ejemplo y de los documentos del programador original.

Utiliza la orden help2man para generar la página de manual a partir de la información dada por «--help» y --version» para cada programa [56].

Si tu paquete tiene páginas de manual, deberías instalarlas con dh_installman(1) listando los archivos correspondientes en el archivo nombre_del_paquete.manpages.

Para instalar el archivo docs/gentoo.1 del paquete gentoo como su manual, construirás el archivo gentoo.manpages con el contenido:

docs/gentoo.1

La orden dh_installchangelogs(1) instala este archivo.

Los archivos postinst, preinst, postrm y prerm [57] se denominan guiones del desarrollador. Son guiones que se colocan en el área de control del paquete y que dpkg ejecuta cuando tu paquete se instala, se actualiza o se elimina.

Por ahora, deberías intentar evitar editar manualmente estos guiones del desarrollador si puedes porque suelen hacerse muy complejos. Para más información lee «Debian Policy Manual, 6 "Package maintainer scripts and installation procedure"», y echa un vistazo a los ejemplos proporcionados por dh_make.

Si a pesar de mis advertencias, adaptas los guiones del desarrollador para el paquete, asegúrate de comprobar su funcionamiento no sólo para la instalación y actualización del paquete, sino también para su desinstalación y eliminación completa.

Las actualizaciones a una nueva versión deben ser «silenciosas» y no intrusivas. Los usuarios no deberían darse cuenta de la actualización, salvo quizás para descubrir que se han arreglado errores antiguos y porque hay alguna nueva funcionalidad.

Cuando la actualización es necesariamente intrusiva (p.e. archivos de configuración dispersos en varios directorios con una estructura totalmente modificada), se deberían establecer los valores predeterminados seguros (p.e. desactivar los servicios) y facilitar la documentación apropiada establecida por las normas (archivos README.Debian y NEWS.Debian) como último recurso. Hay que evitar molestar al usuario con notas debconf invocadas por los guiones del desarrollador en las actualizaciones.

El paquete ucf facilita el sistema conffile-like para preservar los cambios de configuración realizados por el usuario y por ello no deben nombrarse como conffiles los archivos manejados por los guiones del desarrollador. Así se minimizan las incidencias asociadas con ellos.

Estos guiones del desarrollador son un ejemplo de las características de Debian que explican por qué la gente elige Debian. Debes ser cuidadoso con no molestarles con ellos.

Packaging of a library is not easy for a novice maintainer and should be avoided. Having said it, if your package has libraries, you should have debian/package.symbols files. See Sección A.2, “Gestionando debian/package.symbols.

La orden dh_installdocs(1) instala este archivo.

The watch file format is documented in the uscan(1) manpage. The watch file configures the uscan program (in the devscripts package) to watch the site where you originally got the source. This is also used by the Debian Package Tracker service.

Este es su contenido:

# watch control file for uscan
version=3
http://sf.net/gentoo/gentoo-(.+)\.tar\.gz debian uupdate

Con el archivo watch, la URL http://sf.net/gentoo se descarga y se buscan los enlaces del tipo <a href=...>. El nombre base (justo la parte después del / final) de las direcciones URL enlazadas se comparan con la expresión regular de Perl (véase perlre(1)) con el patrón gentoo-(.+)\.tar\.gz. Se descarga el archivo de versión más reciente de entre todos los archivos encontrados cuyo nombre se ajuste al patrón, y se ejecutará el programa uupdate para construir el árbol de código fuente actualizado en base a este fichero.

Although this is true for other sites, the SourceForge download service at http://sf.net is an exception. When the watch file has a URL matching the Perl regexp ^http://sf\.net/, the uscan program replaces it with http://qa.debian.org/watch/sf.php/ and then applies this rule. The URL redirector service at http://qa.debian.org/ is designed to offer a stable redirect service to the desired file for any watch pattern of the form http://sf.net/project/tar-name-(.+)\.tar\.gz. This solves issues related to periodically changing SourceForge URLs.

Si el autor publica la firma criptográfica del fichero tarball, se recomienda comprobar su autenticidad utilizando la opción pgpsigurlmangle descrita en uscan(1).

El archivo debian/source/format, solo contendrá una línea indicando el formato deseado para el paquete (véase dpkg-source(1) para consultar la lista completa). Después de squeeze debería ser:

  • 3.0 (native) para paquetes nativos de Debian o

  • 3.0 (quilt) para el resto de paquetes.

El nuevo formato 3.0 (quilt) registra los cambios en series de archivos de parches quilt en el directorio debian/patches. Estos cambios se aplican automáticamente en la extracción de las fuentes del paquete [58]. Las modificaciones se guardan en el archivo debian.tar.gz que contiene todos los archivos del directorio debian utilizado en la construcción del paquete. El nuevo formato permite la inclusión de archivos como los iconos PNG sin necesidad de trucos [59].

Cuando dpkg-source extrae un paquete fuente con el formato 3.0 (quilt), automáticamente aplica todos los parches listados en el archivo debian/patches/series. Puedes evitar la ejecución de los parches al final de la extracción con la opción --skip-patches.

When you want to manage Debian packaging activities under a VCS, you typically create one branch (e.g., upstream) tracking the upstream source and another branch (e.g., typically master for Git) tracking the Debian package. For the latter, you usually want to have unpatched upstream source with your debian/* files for the Debian packaging to ease merging of the new upstream source.

Una vez compilado el paquete, las fuentes estarán parcheadas. Deberás deshacer los parches manualmente ejecutando dquilt pop -a antes de sincronizar con la rama master. Puedes automatizar esto añadiendo el archivo opcional debian/source/local-options cuyo contenido será «unapply-patches». Este archivo no se incluye en el paquete fuente generado y sólo cambia el entorno local de compilación. Este archivo también puede contener la línea «abort-on-upstream-changes» (véase dpkg-source(1)).

unapply-patches
abort-on-upstream-changes

Los archivos generados automáticamente en el árbol del código fuente pueden ser bastante molestos en la construcción del paquete debido a que generan archivos de parche grandes. Hay módulos personalizados, tales como dh_autoreconf para aliviar este problema como se describe en Sección 4.4.3, “Personalización del archivo rules.

Puedes proporcionar una expresión regular en Perl para la opción --extend-diff-ignore del argumento de dpkg-source(1) para hacer caso omiso de los cambios realizados en los archivos generados automáticamente al crear el paquete fuente.

Puedes conservar las opciones de la orden dpkg-source en el archivo source/options de las fuentes del paquete como solución genérica al problema de los archivos autogenerados. En el ejemplo siguiente, se evita la generación de archivos de parche para config.sub config.guess y Makefile.

extend-diff-ignore = "(^|/)(config\.sub|config\.guess|Makefile)$"

El antiguo formato 1.0 construía un archivo diff.gz cuyo contenido era el de los archivos de construcción del paquete del directorio debian así como los cambios a realizar en las fuentes. Este formato para conservar los cambios resultaba engorroso cuando se trataba de inspeccionar y entender cada modificación de las fuentes. Ya no resulta eficaz.

El nuevo formato 3.0 (quilt) de las fuentes, guarda las modificaciones (los parches) en archivos en el directorio debian/patches/* utilizando la orden quilt. Estos parches y otros datos del paquete que están en el directorio debian se conservan en el archivo debian.tar.gz. Desde que la orden dpkg-source puede aplicar los parches en las fuentes con el nuevo formato tipo quilt sin el paquete quilt, no es necesario añadir el paquete quilt en el campo Build-Depends del fichero control [60].

El funcionamiento de la orden quilt se explica en quilt(1). Conserva las modificaciones de las fuentes en una colección de archivos de parches -p1 en el directorio debian/patches y las fuentes originales permanecen sin modificar fuera del directorio debian. El orden de aplicación de las modificaciones se conserva en el archivo debian/patches/series. Puedes aplicar («push»), deshacer («pop») y actualizar las modificaciones fácilmente [61].

En Capítulo 3, Modificar las fuentes, se han construido tres archivos de parches en debian/patches.

Puesto que los parches se ubican en debian/patches, asegúrate que has configurado adecuadamente la orden dquilt como se describe en Sección 3.1, “Configurar quilt .

Cuando alguien (incluido tú mismo), facilita un parche nombre_parche.patch para las fuentes, cuando ya está construido el paquete, la modificación de un paquete con formato 3.0 (quilt) es así de simple:

$ dpkg-source -x gentoo_0.9.12.dsc
$ cd gentoo-0.9.12
$ dquilt import ../nombre_parche.patch
$ dquilt push
$ dquilt refresh
$ dquilt header -e
.. descripción de la modificación

Los parches conservados con el nuevo formato de fuentes 3.0 (quilt) deben estar exentos de cosas innecesarias. Debes asegurarte ejecutando dquilt pop -a; while dquilt push; do dquilt refresh; done.



[55] Esto reemplaza la orden obsoleta dh_movefiles(1) que se configuraba con el archivo files.

[56] Ten presente que el marcador de posición de páginas de manual help2man reclamará que la documentación más detallada se encuentra disponible en el sistema de información. Si el comando no encuentra una página info, deberás editar manualmente la página de manual construida por help2man.

[57] Aunque el texto utilice la expresión abreviada bash para el nombre de los archivos {pre,post}{inst,rm}, debes utilizar la sintaxis POSIX pura para estos guiones del desarrollador para mantener la compatibilidad con el «shell» del sistema dash.

[58] Véase DebSrc3.0 para un resumen informativo sobre los formatos 3.0 (quilt) y 3.0 (native).

[59] Actualmente, este nuevo formato también permite trabajar con múltiples archivos «tar» fuente y otros sistemas de compresión. Estas funciones están fuera del objetivo de este documento.

[60] Se han propuesto y se están utilizando otros métodos de aplicación de los parches en Debian. El sistema quilt es el preferido. Otros sistemas son dpatch, dbs, cdbs, etc. La mayoría de ellos conservan los parches en archivos en el directorio debian/patches/*.

[61] Si has solicitado a un patrocinador que transfiera el paquete al repositorio, este sistema de separación y documentación de los cambios es muy importante para facilitar la revisión del paquete por el patrocinador.