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.
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.6-0ubuntu1) natty; urgency=low
* New upstream release with lots of bug fixes and feature improvements.
-- Jane Doe <packager@example.com> Thu, 21 Apr 2011 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).
Para obtener más información, consulte la sección de cambios (Section 4.4) <http://www.debian.org/doc/debian-policy/ch-source.html#s-dpkgchangelog>`_ del Manual de normas de Debian.
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.1
Build-Depends: debhelper (>= 7)
Bzr-Vcs: 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.
Tenga en cuenta que en Ubuntu, se configura el campo Maintainer a una dirección general porque cualquiera puede cambiar cualquier paquete (esto se diferencia de Debian, donde se restringen los permisos para cambiar paquetes a individuos o equipos). Los paquetes en Ubuntu deben tener por lo general el campo Maintainer como Ubuntu Developers <ubuntu-devel-discuss@lists.ubuntu.com>. Si el campo del mantenedor se cambia, el valor anterior debe guardarse en XSBC-Original-Maintainer. Esto puede hacerse automáticamente con el script update-maintainer que es parte del paquete ubuntu-dev-tools. Para obtener mayor información, véase la página Debian Maintainer Field spec en la wiki de Ubuntu.
Cada párrafo adicional describe un paquete binario a ser construido.
Para obtener mayor información, véase la sección sobre el archivo de control (Capítulo 5) del manual de normas de Debian.
El archivo copyright¶
Este archivo almacena la información de derechos de autor para ambos, el proyecto original y el empaquetado. Tanto Ubuntu como Debian en la sección 12.5 de su manual de normas establecen que cada paquete debe instalar una copia literal del archivo de copyright y de la información del licenciamiento en /usr/share/doc/$(nombre_del_paquete)/copyright.
Por lo general, la información sobre los derechos de autor se encuentra en el archivo COPYING dentro del directorio de código fuente del programa. Este archivo debe contener información tal los nombres de los autores, del creador del paquete, la URL de donde salió el código fuente y una línea de Copyright con el año, el titular de los derechos de autor y el propio texto del copyright. Una plantilla de ejemplo sería:
Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
Upstream-Name: Hello
Source: ftp://ftp.example.com/pub/games
Files: *
Copyright: Copyright 1998 John Doe <jdoe@example.com>
License: GPL-2+
Files: debian/*
Copyright: Copyright 1998 Jane Doe <packager@example.com>
License: GPL-2+
License: GPL-2+
This program is free software; you can redistribute it
and/or modify it under the terms of the GNU General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later
version.
.
This program is distributed in the hope that it will be
useful, but WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE. See the GNU General Public License for more
details.
.
You should have received a copy of the GNU General Public
License along with this package; if not, write to the Free
Software Foundation, Inc., 51 Franklin St, Fifth Floor,
Boston, MA 02110-1301 USA
.
On Debian systems, the full text of the GNU General Public
License version 2 can be found in the file
`/usr/share/common-licenses/GPL-2'.
Este ejemplo sigue el formato de Machine-readable debian/copyright (archivo debian/copyright legible por una máquina). Se le anima a usar este formato de la misma forma.
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.
Archivos adicionales¶
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.
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
Si sus archivos tar residen en Launchpad, el archivo debian/watch es algo más complicado (véase Question 21146 y Bug 231797 para saber por qué). En este caso, usamos algo como:
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)`.
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/
http://wiki.debian.org/Projects/DebSrc3.0 contiene información adicional concerniente a la migración al formato de paquetes fuente 3.0.
Véase man dpkg-source y la sección sobre el archivo «source/format» (sección 5.21) de la guía del nuevo mantenedor de Debian para más detalle.
Recursos adicionales¶
Además de los enlaces hacia el manual de normas de Debian en cada sección de arriba, la guía del nuevo mantenedor de Debian contiene descripciones más detallas de cada archivo. El capítulo 4 «Archivos necesarios del directorio debian» explica con mayor profundidad los archivos de control («control»), de registro de cambios («changelog»), de derechos de autor («copyright») y de reglas («rules»). El capítulo 5, «Otros archivos dentro del directorio debian» documenta archivos adicionales que podrían utilizarse.