[ anterior ] [ Contenidos ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ siguiente ]


Guía del nuevo desarrollador de Debian
Capítulo 5 - Otros ficheros en el directorio debian.


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.

La orden dh_make construye varios archivos de configuración a modo de plantillas y los ubica en el directorio debian. Algunos de ellos tienen el sufijo .ex (de «example») en el nombre. Otros tienen como prefijo en el nombre el nombre del paquete que estas construyendo. Mira el contenido de todos ellos.

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_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, package-2.install, etc.


5.1 README.debian (LÉEME.debian)

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

dh_make crea una por omisión, y éste es su aspecto:

       gentoo para Debian
       -----------------
     
       <posibles notas asociadas a este paquete (en inglés) - si no 
           hay ninguna borre este fichero>
     
        -- Josip Rodin <joy-mg@debian.org>, Wed, 11 Nov 1998 21:02:14 +0100

Dado que no tenemos que poner nada aquí - está permitido borrarlo.Véase dh_installdocs(1).


5.2 Archivo compat

El archivo compat define el nivel de compatibilidad de debhelper. Actualmente, establecerás la compatibilidad a la versión 7 de debhelper como se indica a continuación.

     $ echo 7 > debian/compat

5.3 Archivo conffiles

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 de forma que 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» (N. del T. archivos de configuración gestionados por el sistema de paquetes). Así, si todos los «conffiles» están en ese 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 crear 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 estas 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 dpkg se mantenga callado.

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


5.4 Archivos nombre_paquete.cron.*

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, o mes. O pueden ejecutarse en cualquier otro momento, si lo desea. Los nombres de los archivos son:

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

Ten en cuenta que ésto no incluye la rotación de archivos de registro, para hacer eso consulta dh_installlogrotate(1) y logrotate(8). Elimina el fichero si el paquete no utiliza dichas tareas.


5.5 Archivo dirs

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 creación previa de los directorios. Véase Archivo install, Sección 5.11.

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


5.6 Archivo nombre_paquete.doc-base

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_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 doc-base , en /usr/share/doc/doc-base/doc-base.html/.

Para más detalles sobre la instalación de documentación adicional, lee Instalación del programa, Sección 3.3.


5.7 Archivo docs

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 ficheros existentes en los directorios de más alto nivel del código que se llamen «BUGS», «README*», «TODO», etc.

También incluiré algunos otros para gentoo:

       BUGS
       CONFIG-CHANGES
       CREDITS
       ONEWS
       README
       README.gtkrc
       TODO

5.8 Archivo emacsen-*

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

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

Elimínalos si no los necesitas.


5.9 Archivo nombre_paquete.examples

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


5.10 Archivos nombre_paquete.init y nombre_paquete.default

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

El archivo nombre_paquete.init se instala como un guión en /etc/init.d/nombre_paquete. Se trata de una plantilla genérica construida por la orden dh_make como init.d.ex. Deberás renómbralo y hacerle muchos cambios para asegurarte que cumpla con las cabeceras del estándar de la jerarquía del sistema de archivos («Filesystem Hierarchy Standard» véase /usr/share/doc/debian-policy/fhs/). dh_installinit(1) lo instalará en el directorio temporal.

El archivo nombre_paquete.default se instalará en el directorio /etc/default/nombre_paquete. Este archivo establece los valores predeterminados que utiliza el guión «init». En la mayoría de casos, este archivo se utiliza para desactivar la ejecución del demonio, estableciendo algunos indicadores predeterminados o tiempos de espera. Las características configurables que puedan existir en tu guión «init» deben incluirse en este archivo default, y no en el propio guión.

Si el programa original incluye un archivo «init», tu puedes hacer uso de él o bien descartarlo. Si optas por no hacer uso del guión «init.d» original, deberás construir uno nuevo en debian/nombre_paquete.init. En cualquier caso tendrás construir los enlaces simbólicos rc* aunque el guión de 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.


5.11 Archivo install

Si hay archivos que deben ser instalados por el paquete pero no lo hace make install, puedes listar los archivos y sus destinos en el archivo install. Se encargará de la instalación la orden dh_install(1) [39]. Debes asegurarte que no hay un sistema más específico para hacer esta instalación. Por ejemplo, para la documentación debes utilizar el archivo docs, en lugar de este archivo.

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 no se instalase, deberías utilizar el archivo install como sigue:

     src/nombre_paquete/archivo_binario usr/bin

Al instalarse el paquete, se instalará el archivo binario /usr/bin/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_paquete-1.install, nombre_paquete-2.install, etc.

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


5.12 Archivo nombre_paquete.info

Si tu paquete utiliza páginas «info» (sistema de ayuda), podrás instalarlas utilizando dh_installinfo(1) que utilizará el listado del archivo package.info.


5.13 Archivos {nombre_archivo.|source/}lintian-overrides

Si el programa lintian emite un informe de diagnóstico erróneo en algún caso en que las normas admitan excepciones, podrás utilizar los archivos nombre_paquete.lintian-overrides o source/lintian-overrides para evitar que lintian emita el error. Por favor, lee /usr/share/doc/lintian/lintian.html/index.html error y procura no abusar de esta opción (para ocultar errores auténticos).

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

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


5.14 Archivos manpage.*

El/los programa/s debería/n tener una página de manual. Tendrás que crearla 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.


5.14.1 Archivo manpage.1.ex

Las páginas de manual se escriben normalmente con nroff(1). El ejemplo manpage.1.ex está también escrito con «nroff». Consulta la página de manual man(7) para una breve descripción de cómo editar el fichero.

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.

       Sección |     Descripción        |     Notas
          1     Órdenes de Usuario        Programas o guiones ejecutables.
          2     Llamadas al Sistema       Funciones que ofrece el núcleo.
          3     Llamadas a Bibliotecas    Funciones dadas por las bibliotecas 
     				     del sistema.
          4     Ficheros Especiales       Generalmente se encuentran en /dev.
          5     Formatos de Fichero       Por ejemplo, el formato del /etc/passwd.
          6     Juegos                    U otros programas frívolos.
          7     Paquetes de Macros        Como las macros de man.
          8     Administración del Sist.  Programas que sólo suele ejecutar 
     				     el superusuario.
          9     Rutinas del Núcleo        Llamadas al sistema no estándar.

Así que la página de manual de «gentoo» debería llamarse gentoo.1. No había una página de manual gentoo.1 en el paquete fuente así que la escribí 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» and "«--version» para cada programa [40].


5.14.2 Archivo manpage.sgml.ex

Por otro lado, puede que prefieras escribir usando SGML en lugar de «nroff». En este caso, puedes usar la plantilla manpage.sgml.ex. Si haces esto, tendrás que:


5.14.3 Archivo manpage.xml.ex

Si prefieres el formato XML en lugar de SGML, puedes utilizar la plantilla manpage.xml.ex. En este caso debes:


5.15 Archivo nombre_paquete.manpages

Si tu paquete tienen páginas de manual, las instalarás con dh_installman(1) listado los archivos correspondientes en el archivo nombre_paquete.manpages.

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

     docs/gentoo.1

5.16 Archivo menu.ex

Los usuarios de X Windows suelen tener un gestor de ventanas con menús que pueden adaptarse para lanzar programas. Si tienen instalado el paquete menu de Debian, se creará un conjunto de menús para cada programa del sistema para ellos.

Éste es el fichero menu.ex que dh_make construye por omisión:

       ?package(gentoo):needs="X11|text|vc|wm" 
         section="Apps/lea-manual-menu"\
         title="gentoo" command="/usr/bin/gentoo"

El primer campo tras la coma es needs (necesidades, n. del t.) y especifica qué tipo de interfaz necesita el programa. Cambia ésta a una de las alternativas que se listan, como por ejemplo «text» o «X11».

El siguiente section, es la sección donde deberían aparecer la entrada del menú y del submenú. La lista actual de secciones está en: /usr/share/doc/debian-policy/menu-policy.html/ch2.html#s2.1

El campo title es el nombre del programa. Puedes comenzar éste en mayúsculas si así lo prefieres, pero hazlo lo más corto que puedas.

Finalmente, el campo command es la orden que ejecuta el programa.

Ahora cambiaremos la entrada del menú por ésta:

     ?package(gentoo): needs="X11" \
             section="Applications/Tools" \
             title="Gentoo" command="gentoo"

También puedes añadir otros campos como son «longtitle» (título largo), «icon» (icono), «hints» (pistas), etc. Para más información consulta dh_installmenu(1), menufile(5), update-menus(1) y /usr/share/doc/debian-policy/menu-policy.html/.


5.17 Archivo NEWS

La orden dh_installchangelogs(1) instala este archivo.


5.18 Archivos {post|pre}{inst|rm}

Los ficheros postinst, preinst, postrm, y prerm [41] se llaman guiones del desarrollador («maintainer scripts»), y 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 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 dados 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 de 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.


5.19 Archivo TODO

La orden dh_installdocs(1) instala este archivo.


5.20 Archivo watch.ex

El formato del archivo watch se documenta en la página de manual de uscan(1). El archivo watch se usa para configurar el programa uscan(1) (del paquete devscripts) que vigila el servidor de donde obtuviste las fuentes originales. También lo utiliza Debian External Health Status (DEHS).

Esto es lo que he puesto yo [42]:

     # fichero de control «watch» para uscan
     version=3
     http://sf.net/gentoo/gentoo-(.+)\.tar\.gz debian uupdate

Habitualmente, la URL http://sf.net/gentoo se descarga y se buscan los enlaces del tipo <a href=...> con este archivo watch. 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 crear el árbol de código fuente actualizado en base a este fichero.

Aunque es posible hacer esto con otros portales, el servicio de descarga de «SourceForge» en http://sf.net es una excepción. Cuando el archivo watch tiene una URL que concuerda con el patrón Perl ^http://sf\.net/, el programa uscan lo substituye por http://qa.debian.org/watch/sf.php/ y después aplica esta regla. El servicio de redireccionamiento URL a la dirección http://qa.debian.org/ está diseñado para ofrecer un servicio estable de redireccionamiento al archivo presente en watch y que concuerda con http://sf.net/proyecto/nombre_archivo_tar-(.+)\.tar\.gz


5.21 Archivo source/format

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

El nuevo formato 3.0 (quilt) registra los cambios en series de archivos de parches en el directorio debian/patches. Estos cambios se aplican automáticamente en la extracción de las fuentes del paquete [43]. 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 [44].

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.


5.22 Archivo source/local-options

Si tienes que gestionar los trabajos de empaquetado en un entorno VCS, seguramente tendrás una rama (p.ej. upstream) que sigue las fuentes originales y otra rama (p.ej. normalmente master en Git) para el paquete Debian. Para este último caso, generalmente tendrás las fuentes originales sin modificar (sin aplicarles los parches) con los archivos debian/* para el empaquetamiento Debian para facilitar la fusión con las nuevas versiones de las fuentes.

Una vez compilado el paquete, las fuentes estarán parcheadas. Deberás deshacer los parches manualmente ejecutando quilt 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)).


5.23 Archivos patches/*

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 para 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 3.0 (quilt) sin el paquete quilt, no es necesario añadir el paquete quilt en el campo Build-Depends del fichero control [45].

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 ejecutar («push»), deshacer («pop») y actualizar las modificaciones fácilmente [46].

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

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

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
     $ quilt import ../nombre_parche.patch
     $ quilt push
     $ quilt refresh
     $ quilt 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 «quilt pop -a; while quilt push; do quilt refresh; done».


[ anterior ] [ Contenidos ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ siguiente ]


Guía del nuevo desarrollador de Debian

versión 1.2.25, 2010-12-22 12:44:34 UTC

Josip Rodin joy-mg@debian.org

Traducido por Javier Fernández-Sanguino Peña jfs@debian.org
David Martínez ender@debian.org
Ana Beatriz Guerrero López ana@debian.org
Francisco Javier Cuadrado fcocuadrado@gmail.com
Innocent De Marchi tangram.peces@gmail.com