Capítulo 4. Archivos necesarios en el directorio debian

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

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

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]:

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]

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)

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.

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 .

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.