Ubuntu logo

Packaging Guide

2. Descripción general básica del Directorio debian/

En este artículo explicaremos brevemente los diferentes archivos que son importantes para el empaquetado de paquetes Ubuntu los cuales están en el directorio debian/. Los más importantes son changelog, control, copyright y rules. Estos son requeridos por todos los paquetes. Un conjunto de archivos adicionales en debian/ puede que sean usados para personalizar y configurar el comportamiento del paquete. Sobre algunos de ello se habla en este articulo, pero esto no pretende ser una lista completa.

2.1. El registro de cambios

Este archivo es, como su nombre indica, un listado de los cambios realizados en cada versión. Tiene un formato especifico que da el nombre del paquete, versión, distribución, cambios, y quién realizó estos cambios en un determinado momento. Si tiene una clave GPG (vea: Getting set up), asegúrese de usar el mismo nombre y dirección de correo electrónico en changelog. tal y cómo lo tiene en la clave. Lo siguiente es una plantilla de changelog:

package (version) distribution; urgency=urgency

 * change details
  - more change details
 * even more change details

-- maintainer name <email address>[two spaces]  date

El formato (especialmente el de la fecha) es importante. La fecha debe estar en formato RFC 5322, que puede obtenerse mediante la orden date -R. Por conveniencia, la orden dchx se puede usar para editar el archivo changelog. Se actualizará la fecha de forma automática.

Los puntos de segundo nivel se indican con un guión «-», los de primer nivel usan un asterisco «*».

Si está empaquetando desde cero, dch --create (dch se encuentra en el paquete devscripts) creará un archivo debian\changelog estándar.

Este es un ejemplo del archivo changelog para hello:

hello (2.8-0ubuntu1) trusty; urgency=low

  * New upstream release with lots of bug fixes and feature improvements.

-- Jane Doe <packager@example.com>  Thu, 21 Oct 2013 11:12:00 -0400

Observe que el paquete tiene un -0ubuntu1 anexado a el, este representa la versión en la distribución y se usa para que el paquete pueda ser actualizado (para solucionar errores por ejemplo) con nuevas subidas usando la misma versión principal con la que se liberó.

Ubuntu y Debian tienen esquemas de versión de paquetes ligeramente diferentes para evitar conflictos en los programas con la misma versión principal. Si una paquete de Debian sufre un cambio en Ubuntu, se le agrega el ubuntuX (donde X es el número de revisión en Ubuntu) al final de la versión de Debian. Si el paquete hello 2.6-1 de Debian es modificado en Ubuntu, la versión quedaría 2.6-1ubuntu1. Si el paquete no existiera en Debian, entonces la revisión ahí sería 0 (y quedaría 2.6-0ubuntu1).

For further information, see the changelog section (Section 4.4) of the Debian Policy Manual.

2.2. El archivo de control

El archivo control contiene la información que usan administradores de paquetes (como apt-get, synaptic y adept), dependencias de compilación, información del mantenedor y mucho más.

Para el paquete hello de Ubuntu, el archivo control tiene el siguiente aspecto:

Source: hello
Section: devel
Priority: optional
Maintainer: Ubuntu Developers <ubuntu-devel-discuss@lists.ubuntu.com>
XSBC-Original-Maintainer: Jane Doe <packager@example.com>
Standards-Version: 3.9.5
Build-Depends: debhelper (>= 7)
Vcs-Bzr: lp:ubuntu/hello
Homepage: http://www.gnu.org/software/hello/

Package: hello
Architecture: any
Depends: ${shlibs:Depends}
Description: The classic greeting, and a good example
 The GNU hello program produces a familiar, friendly greeting. It
 allows non-programmers to use a classic computer science tool which
 would otherwise be unavailable to them. Seriously, though: this is
 an example of how to do a Debian package. It is the Debian version of
 the GNU Project's `hello world' program (which is itself an example
 for the GNU Project).

El primer párrafo describe el paquete fuente incluyendo la lista de paquetes requeridos para construirlo desde sus fuentes en el campo Build-Depends. También contiene alguna meta-información como el nombre del mantenedor, la versión de la política de Debian que cumple el paquete, la ubicación del repositorio de control de versiones del paquete y la página principal para enviar el parche.

Note that in Ubuntu, we set the Maintainer field to a general address because anyone can change any package (this differs from Debian where changing packages is usually restricted to an individual or a team). Packages in Ubuntu should generally have the Maintainer field set to Ubuntu Developers <ubuntu-devel-discuss@lists.ubuntu.com>. If the Maintainer field is modified, the old value should be saved in the XSBC-Original-Maintainer field. This can be done automatically with the update-maintainer script available in the ubuntu-dev-tools package. For further information, see the Debian Maintainer Field spec on the Ubuntu wiki.

Cada párrafo adicional describe un paquete binario a ser construido.

For further information, see the control file section (Chapter 5) of the Debian Policy Manual.

2.4. El archivo de reglas

El último archivo que se necesita estudiar es el archivo rules. Este archivo hace todo el trabajo para crear el paquete. Es un Makefile con secciones para compilar e instalar el programa, y después crear el archivo .deb a partir de los archivos instalados. También tiene una sección para limpiar todos los archivos generados por la compilación, con el fin de volver a quedarse únicamente con el paquete fuente.

Esta es una versión simplificada del archivo de reglas creado por dh_make (el cual se puede encontrar en el paquete dh-make):

#!/usr/bin/make -f
# -*- makefile -*-

# Uncomment this to turn on verbose mode.
#export DH_VERBOSE=1

%:
       dh  $@

Analicemos con más detalle este archivo. Lo que hace es pasar cada sección de compilación invocada por debian/rules como un parámetro a /usr/bin/dh, que a su vez ejecutará todos los comandos dh_* necesarios.

dh ejecuta una secuencia de órdenes de debhelper. Las secuencias soportadas son las que corresponden a las secciones del archivo debian/rules: «build», «clean», «install», «binary-indep», y «binary». Para saber cuales son las órdenes que se ejecutan en cada sección, ejecute:

$ dh binary-arch --no-act

A las órdenes de la secuencia binary-indep se incluye la opción «-i» para asegurar que solo funcionen en paquetes binarios independientes, mientras que a las órdenes de la secuencia binary-arch se les agrega una opción «-a» para asegurar que solo funcionen para paquetes independientes de la arquitectura.

Cada orden debhelper registrará cuando se ha ejecutado correctamente en «debian/package.debhelper.log» (archivo que dh_clean elimina). De esta manera dh puede saber qué órdenes ya han sido ejecutadas, para qué paquetes y evitar ejecutar esas órdenes de nuevo.

Cada vez que dh se ejecuta, comprueba el registro y busca la última orden registrada que está en la secuencia especificada. Continúa entonces con la siguiente orden de la secuencia. Las opciones --until, --before, --after y --remaining pueden modificar este comportamiento.

Si el archivo debian/rules contiene una sección con el nombre override_dh_command, cuando se llegue a esa orden en la secuencia, dh ejecutará esa sección en lugar de la orden original. La sección sobrescrita puede ejecutar entonces la orden con opciones adicionales, o ejecutar órdenes completamente diferentes en su lugar (téngase en cuenta que para usar esta característica, se debería construir las dependencias con debhelper 7.0.50 o superior).

Véase /usr/share/doc/debhelper/examples/ y man dh para más ejemplos. Véase también la sección sobre el archivo de reglas (sección 4.9) del manual de normas de Debian.

2.5. Archivos adicionales

2.5.1. El archivo de instalación

El archivo install lo usa dh_install para instalar archivos en el paquete binario. Tiene dos casos de uso estándar:

  • Para instalar archivos en el paquete que no son manejados por el sistema de compilación del proyecto original.

  • Partir paquete fuente en un único fichero grande en varios paquetes binarios.

En el primer caso, el archivo install debería contener solo una linea por cada archivo instalado, indicando tanto el archivo como el directorio de destino. Por ejemplo, el siguiente archivo install instalaría el script foo que se encuentra en la raíz del paquete en usr/bin y el archivo «desktop» del directorio debian en usr/share/applications:

foo usr/bin
debian/bar.desktop usr/share/applications

Cuando un paquete fuente crea varios paquetes binarios, dh instala los archivos en debian/tmp en lugar de debian/<paquete>. Los archivos instalados en debian/tmp pueden entonces moverse a diferentes paquetes binarios usando varios archivos $nombre_paquete.install. Esto se hace frecuentemente para separar grandes cantidades de datos que son independientes de la arquitectura de paquetes que dependen de la misma, llevándolos a paquetes Architecture: all. En este caso, solo se necesita el nombre de los archivos (o directorios) a instalar, sin el directorio de instalación. Por ejemplo, un archivo foo.install que solo contenga archivos dependientes de la arquitectura se vería así:

usr/bin/
usr/lib/foo/*.so

Por el contrario, un archivo foo-common.install que solo contenga archivos que son independientes de la arquitectura se vería así:

/usr/share/doc/
/usr/share/icons/
/usr/share/foo/
/usr/share/locale/

Esto crearía dos paquetes binarios, foo y foo-common. Ambos necesitarían su propia sección en el archivo debian/control.

Véase man dh_install y la sección sobre el archivo «install» (Section 5.11) de la guía del nuevo mantenedor de Debian para obtener más información.

2.5.2. El archivo de avisos («watch»)

El archivo debian/watch permite comprobar automáticamente si existe una nueva versión del proyecto original con la herramienta uscan, localizada en el paquete devscripts. La primera línea del archivo «watch» debe describir la versión del formato (3, en el momento de escribir esto), mientras que el resto de líneas contienen las URLs a analizar. Por ejemplo:

version=3

http://ftp.gnu.org/gnu/hello/hello-(.*).tar.gz

Ejecutando uscan en el directorio raíz del paquete comparará el número de versión original que se encuentra en debian/changelog con el último disponible en el proyecto original. Si se encuentra una versión más moderna del proyecto original, se descargará automáticamente. Por ejemplo:

$ uscan
hello: Newer version (2.7) available on remote site:
  http://ftp.gnu.org/gnu/hello/hello-2.7.tar.gz
  (local version is 2.6)
hello: Successfully downloaded updated package hello-2.7.tar.gz
    and symlinked hello_2.7.orig.tar.gz to it

If your tarballs live on Launchpad, the debian/watch file is a little more complicated (see Question 21146 and Bug 231797 for why this is). In that case, use something like:

version=3
https://launchpad.net/flufl.enum/+download http://launchpad.net/flufl.enum/.*/flufl.enum-(.+).tar.gz

Para más información, véase man uscan y la sección sobre el archivo «watch» (sección 4.11) del manual de normas de Debian.

Para obtener una lista de los paquetes de los que el archivo watch informa no estar sincronizados con las versiones originales véase la página Ubuntu External Health Status (estado de salud externa de Ubuntu, en inglés).

2.5.3. El archivo de formato («source/format»)

Este archivo indica el formato fuente del paquete. Solo debería contener una línea indicando el formato deseado:

  • 3.0 (native) para paquetes nativos de Debian (sin versión en upstream)

  • 3.0 (quilt) para paquetes con un archivo tar de upstream independiente.

  • 1.0 para paquetes que desean declarar explícitamente el formato por defecto

Actualmente, el formato fuente del paquete será por defecto 1.0 si no existe este archivo. Se puede establecer esto explícitamente en el archivo «source/format». Si elige no usar este archivo para definir el formato, Lintian mostrará una advertencia sobre su ausencia. La advertencia es de carácter informativo y puede ser ignorada.

Se le anima a utilizar el nuevo formato fuente 3.0 . Proporciona una serie de nuevas características:

  • Soporte para formatos de compresión adicionales: bzip2, lzma y xz

  • Soporte para varios archivos tar de upstream

  • No es necesario volver a empaquetar los archivos tar de upstream para eliminar el directorio debian

  • Los cambios específicos de Debian ya no se guardan en un único archivo .diff.gz, sino en varios parches compatibles con quilt en debian/patches/

https://wiki.debian.org/Projects/DebSrc3.0 summarizes additional information concerning the switch to the 3.0 source package formats.

See man dpkg-source and the source/format section (Section 5.21) of the Debian New Maintainers’ Guide for additional details.

2.6. Recursos adicionales

In addition to the links to the Debian Policy Manual in each section above, the Debian New Maintainers’ Guide has more detailed descriptions of each file. Chapter 4, “Required files under the debian directory” further discusses the control, changelog, copyright and rules files. Chapter 5, “Other files under the debian directory” discusses additional files that may be used.