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


Guía del nuevo desarrollador de Debian
Capítulo 4 - Archivos necesarios en el directoriodebian


Ahora hay un nuevo subdirectorio bajo el directorio principal del programa («gentoo-0.9.12»), que se llama «debian». Hay algunos ficheros en este directorio que debemos editar para adaptar el comportamiento del paquete. La parte más importante es modificar los ficheros «control», «rules», «changelog», y «copyright» que son necesarios en todos los paquetes.


4.1 El archivo control

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 crea para nosotros:

      1 Source: gentoo
      2 Section: unknown
      3 Priority: extra
      4 Maintainer: Josip Rodin <joy-mg@debian.org>
      5 Build-Depends: debhelper (>= 7.0.50~)
      6 Standards-Version: 3.8.4
      7 Homepage: <introduce aquí la URL del autor original  >
      8
      9 Package: gentoo
     10 Architecture: any
     11 Depends: ${shlibs:Depends}, ${misc:Depends}
     12 Description: <insertar hasta 60 caracteres de descripción>
     13  <inserta una descripción larga, indentada con espacios.>

(He añadido los números de línea)

Las líneas 1 a 6 son la información de control para el paquete fuente.

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.

Vamos a cambiarla para que ponga x11. El prefijo «main/» ya va implícito, así que podemos omitirlo. Véase Manual de normas de Debian, 2.4 'Secciones' y Lista de secciones en «sid» para más información.

La línea 3 describe cómo de importante es para el usuario la instalación de este paquete. Podrás consultar en el manual de normas de Debian («Debian Policy», N. del T.) en Manual de normas de Debian, 2.5 'Prioridad' la guía de los valores que deberían tener estos campos.

«Section» y «Priority» se usan en las interfaces como dselect 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: », 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», N. del T.) utilizará esta dirección para enviarte los mensajes de los bugs. Evita usar comas, el signo «ampersand» y paréntesis.

La línea 5 incluye la lista de paquetes requeridos para construir tu paquete (en el campo Build-Depends). Puedes tener una línea adicional con el campo Build-Depends-Indep (consulta Debian Policy Manual, 7.7 'Relationships between source and binary packages - Build-Depends, Build-Depends-Indep, Build-Conflicts, Build-Conflicts-Indep para más información sobre este campo). Algunos paquetes como gcc y make están implícitos, consulta el paquete build-essential para más detalles. Si se necesita algún compilador no estándar u otra herramienta para construir tu paquete, deberías añadirla en la línea «Build-Depends». Las entradas múltiples se separan con comas, lee la explicación de las dependencias binarias para averiguar más sobre la sintaxis de este campo.

En caso de duda, utiliza el campo Build-Depends [19]

Para saber que 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/foo, deberías ejecutar:

     $ objdump -p /usr/bin/nombre_paquete | grep NEEDED

y para cada biblioteca listada por la orden anterior (en el ejemplo se hace para libfoo.so.6) ejecuta

     $ dpkg -S libfoo.so.6

Debes utilizar la versión «-dev» de cada uno de los paquetes dentro de la entrada «Build-deps». 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 requiere 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 del programa.

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 línea 10 describe la arquitectura de CPU para la que el paquete binario puede ser compilado. Dejaremos puesto «any» (cualquiera), porque 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 El archivo rules, Sección 4.4 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.)

A continuación se detalla el significado de las dependencias:

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. Estas entradas funcionan como variables: son substituidas por por listas de paquetes cuando debhelper ejecuta la orden dh_gencontrol(1).

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 y en qué paquetes están, tales como como libc6 o xlib6g. Luego pasará la lista a dh_gencontrol(1) que rellenará estas dependencias en el lugar adecuado (${shlibs:Depends}). De esta forma no tendrás que preocuparte por esto.

La lista de paquetes generada por dh_perl(1) se usa para ${perl:Depends}.

Algunas órdenes de debhelper determinan las dependencias de los paquetes listados anteriormente. La lista de estos paquetes se usará para ${misc:Depends}.

Después de decir todo esto, podemos dejar la línea de «Depends:» exactamente como está ahora e insertar otra línea tras ésta que diga Suggests: file, porque gentoo utiliza algunas funciones de este paquete/programa.

La línea 12 es una descripción corta. La mayor parte de los monitores 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 GTK+ 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 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 puede 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 [20].

Vamos a poner los campos Vcs-* documentados en Developer's Reference, 6.2.5. 'Version Control System location' entre las lineas 6 y 7. 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 (>= 7.0.5), xlibs-dev, libgtk1.2-dev, libglib1.2-dev
      6 Standards-Version: 3.8.4
      7 Vcs-Git: git://git.debian.org/git/collab-maint/gentoo.git
      8 Vcs-browser: http://git.debian.org/?p=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 a 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 utilises the GTK+ toolkit
     30  for its interface.

(He añadido los números de línea)


4.2 El archivo copyright

Este fichero contiene la información sobre la licencia y copyright de las fuentes originales del paquete. El formato no está definido en las normas, pero sí en sus contenidos (Debian Policy Manual, 12.5 'Copyright information'). También puedes consultar DEP-5: Machine-parseable debian/copyright.

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.

Debes completar la información sobre el lugar donde se puede obtener el código fuente, la condiciones de derechos de autor y la licencia. Las licencias de código libre más comunes son 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 o la «Artistic license» y hacer referencia al archivo correspondiente ubicado en el directorio /usr/share/common-licenses/, que existen en todos los sistemas Debian. De lo contrario, debe incluirse en el archivo copyright el texto de la licencia completo.

En resumen, el archivo copyright del paquete gentoo debería ser similar a esto [21]:

      1 Format-Specification: http://svn.debian.org/wsvn/dep/web/deps/dep5.mdwn?op=file&rev=135
      2 Name: gentoo
      3 Maintainer: Josip Rodin <joy-mg@debian.org>
      4 Source: http://sourceforge.net/projects/gentoo/files/
      5
      6 Copyright: 1998-2010 Emil Brink <emil@obsession.se>
      7 License: GPL-2+
      8
      9 Files: icons/*
     10 Copyright: 1998 Johan Hanson <johan@tiq.com>
     11 License: GPL-2+
     12
     13 Files: debian/*
     14 Copyright: 1998-2010 Josip Rodin <joy-mg@debian.org>
     15 License: GPL-2+
     16
     17 License: GPL-2+
     18  This program is free software; you can redistribute it and/or modify
     19  it under the terms of the GNU General Public License as published by
     20  the Free Software Foundation; either version 2 of the License, or
     21  (at your option) any later version. 
     22  .
     23  This program is distributed in the hope that it will be useful,
     24  but WITHOUT ANY WARRANTY; without even the implied warranty of
     25  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
     26  GNU General Public License for more details.
     27 .
     28  You should have received a copy of the GNU General Public License along
     29  with this program; if not, write to the Free Software Foundation, Inc.,
     30  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
     31  .
     32  On Debian systems, the full text of the GNU General Public
     33  License version 2 can be found in the file
     34  `/usr/share/common-licenses/GPL-2'.

(He añadido los números de línea)

Por favor, sigue el COMO redactado por «ftpmasters» y enviada a «debian-devel-announce»: http://lists.debian.org/debian-devel-announce/2006/03/msg00023.html.


4.3 El archivo changelog

Este es un fichero requerido, que tiene un formato especial descrito en las normas Debian, Debian Policy Manual, 4.4 'debian/changelog'. Este es el formato que usan 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 crea uno por omisión, el cual es como sigue:

     1  gentoo (0.9.12-1) unstable; urgency=low
     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)

La línea 1 es el nombre del paquete, versión, distribución y urgencia. El nombre debe coincidir con el nombre del paquete fuente, la distribución debería ser, por ahora, «unstable» (o incluso «experimental») [22] y la urgencia no debería cambiarse a algo mayor que low. :-)

Las línea 3-5 son una entrada de registro, donde se documentan los cambios hechos en esta revisión del paquete (no los cambios en las fuentes originales - hay un fichero especial para este propósito, creado por los autores originales y que instalarás luego como /usr/share/doc/gentoo/changelog.gz). En el ejemplo se supone que el código del informe de error ITP («Intent To Package», intento de empaquetar) es #12345. Las nuevas líneas deben insertarse justo antes de la línea que hay más arriba que comienza por un asterisco («*»). Puede hacerlo con dch(1), o manualmente con cualquier editor de texto.

Terminarás con algo así:

     1  gentoo (0.9.12-1) unstable; 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)

Puedes leer más sobre cómo actualizar el fichero changelog más adelante en Actualizar el paquete, Capítulo 9.


4.4 El archivo rules

Ahora necesitamos mirar las reglas exactas que dpkg-buildpackage(1) utilizará para crear el paquete. Este fichero es en realidad otro Makefile, pero diferente al que viene en las fuentes originales. A diferencia de otros ficheros en debian, éste debe ser un fichero ejecutable.


4.4.1 Objetivos del archivo rules

Cada fichero «rules» (de reglas, N. del T.), como muchos otros Makefiles, se compone de varias reglas que especifican cómo tratar las fuentes.Debian Policy Manual, 4.9 'Main building script: debian/rules' explica detalladamente su función.

A continuación se proporciona una explicación simplificada de los distintos objetivos.

Cada regla se compone de objetivos, ficheros o nombres de acciones que se deben llevar a cabo (por ejemplo, «build:» o «install:»). Las reglas que quieras ejecutar deberían llamarse como argumentos de la línea de órdenes (por ejemplo, «./debian/rules build» o «make -f rules install»). Después del nombre del objetivo, puedes nombrar las dependencias, programas o ficheros de los que la regla dependa. Después de esto, hay un número cualquiera de instrucciones (¡indentado con <tab>!), hasta que se llega a una línea en blanco. Ahí empieza otra regla. Las líneas múltiples en blanco, y las líneas que empiezan por almohadillas («#») se tratan como comentarios y se ignoran.

Probablemente ya te hayas perdido, pero todo quedará más claro después de ver el fichero «rules» que dh_make pone por omisión. Deberías leer también la entrada de «make» en info para más información.


4.4.2 Archivo rules predeterminado

La nueva versión de dh_make genera un un archivo rules muy simple pero poderoso utilizando la orden dh:

      1 #!/usr/bin/make -f
      2 # -*- makefile -*-
      3 # Sample debian/rules that uses debhelper.
      4 # This file was originally written by Joey Hess and Craig Small.
      5 # As a special exception, when this file is copied by dh-make into a
      6 # dh-make output file, you may use that output file without restriction.
      7 # This special exception was added by Craig Small in version 0.37 of dh-make.
      8
      9 # Uncomment this to turn on verbose mode.
     10 #export DH_VERBOSE=1
     11
     12 %:
     13        dh $@

(He añadido los números de línea. En el fichero debian/rules los espacios iniciales de las líneas son códigos de tabulación)

Probablemente estés familiarizado con líneas como la primera de guiones escritos en shell o Perl. Esta línea indica que el fichero debe ejecutarse con /usr/bin/make.

La linea 10 debe descomentarse para asignar el valor 1 a la variable DH_VERBOSE. En ese caso, se escribirán las órdenes dh_* que ejecutadas por dh. Puedes añadir la linea export DH_OPTIONS=-v aquí. Así podrás ver la salida de la ejecución de cada orden dh_* y solucionar los problemas que se produzcan. Esto te ayudará a entender como funciona el archivo rules y a solucionar problemas. Esta nueva orden dh es parte fundamental de la herramientas debhelper y no te esconde nada.

Todo el trabajo del archivo se reduce a las líneas 12 y 13. El símbolo de porcentaje substituye a cualquier objetivo para a continuación ejecutar únicamente dh con el nombre del objetivo (como opción) [26]. La orden dh es un guión que ejecuta las secuencias necesarias de órdenes dh_* según sus parámetros, como se describe a continuación [27]:

La función de las órdenes dh_* puede deducirse de su nombre [29]. A continuación se resume las funciones de las órdenes más importantes asumiendo que se utiliza un sistema de compilación basado en un archivo Makefile [30].

Los objetivos que deben ejecutarse con la orden fakeroot contienen dh_testroot. Si no utilizas la orden para simular la ejecución por el usuario «root», se producirá un error que detendrá la ejecución.

Es importante tener presente que el archivo rules que crea dh_make es sólo una sugerencia. Será suficiente para la mayoría de los paquetes simples, pero no dejes de adaptarlo a tus necesidades en paquetes más complejos. Lo único que no debes cambiar son los nombres de las reglas, puesto que todas las herramientas los utilizan, como se especifica en la normas de Debian.

A pesar de que install no es un objetivo obligatorio, se contempla su uso. fakeroot dh install se comporta como fakeroot dh binary pero se detiene después de dh_fixperms.


4.4.3 Personalización del archivo rules

Puedes realizar muchos cambios para adaptar el archivo rules construido por la orden dh.

La orden dh $@ permite las siguientes adaptaciones [32]:

Para las fuentes que usan «Autotools», combinar las opciones anteriores con dh --with autotools-dev --with autoreconf $@ es lo habitual con el sistema de compilación GNU.

Muchas de las órdenes dh_* invocadas por la nueva orden dh son personalizables mediante sus archivos de configuración en el directorio debian. Véase Otros ficheros en el directorio debian., Capítulo 5 y los manuales (las «manpage») para cada orden.

Algunas órdenes dh_* invocadas por la nueva orden dh pueden precisar la adición de argumentos (opciones), la ejecución de órdenes adicionales u omitirlas del todo. Para estos casos, deberás añadir el objetivo override_dh_foo con las reglas a ejecutar en el archivo rules sólo para la orden dh_foo que vas a cambiar. Se trata de decir «ejecútame a mí en su lugar» [35].

Las ordenes dh_auto_* hacen más cosas que las expuestas aquí. El uso de ordenes equivalentes más sencillas en lugar de éstas en los objetivos override_dh_* (excepto el objetivo override_dh_auto_clean) es una mala idea ya que puede eliminar funciones inteligentes de debhelper.

Si vas a guardar los datos de configuración del paquete gentoo en el directorio /etc/gentoo en lugar del directorio habitual /etc, debes anular la ejecución del argumento predeterminado --sysconfig=/etc de la orden dh_auto_configure por ./configure con lo siguiente [36]:

     override_dh_auto_configure:
             dh_auto_configure -- --sysconfig=/etc/gentoo

Los argumentos a continuación de -- se añaden a los argumentos predeterminados, anulándolos, en la ejecución automática del programa. Es mejor utilizar la orden dh_auto_configure que el ./configure ya que así sólo anulará el argumento --sysconfig manteniendo intactos otros argumentos de ./configure.

Si el Makefile de las fuentes de gentoo requiere la especificación del objetivo build para compilarlo [37], puedes añadir un objetivo override_dh_auto_build para anularlo.

     override_dh_auto_build:
             dh_auto_build -- build

De esta forma se garantiza la ejecución de $(MAKE) con todos los argumentos predeterminados por la orden dh_auto_build y del argumento build.

Si el Makefile de las fuentes de gentoo requiere la especificación del objetivo packageclean para limpiarlo, en lugar de los objetivos distclean o clean en el archivo Makefile, puedes añadir un objetivo override_dh_auto_clean para habilitarlo.

     override_dh_auto_clean:
             $(MAKE) packageclean

Si el Makefile de las fuentes de gentoo contiene un objetivo test que no deseas que se ejecute en la construcción del paquete Debian, puedes usar un objetivo override_dh_auto_test sin órdenes para ignorarlo.

     override_dh_auto_test:

Si gentoo contiene el poco frecuente archivo de cambios del autor con el nombre FIXES, dh_installchangelogs no lo instalará por omisión. La orden dh_installchangelogs requiere como argumento FIXES para instalarlo [38].

     override_dh_installchangelogs:
             dh_installchangelogs FIXES

Cuando utilizas el nuevo programa dh, la utilización explícita de objetivos como los listados en Objetivos del archivo rules, Sección 4.4.1 (excepto get-orig-source) puede dificultar la correcta comprensión de sus efectos exactos. Por favor, limita el uso de objetivos explícitos a objetivos del tipo override_dh_* y de forma que sean completamente independientes entre sí (siempre que sea posible).


[ 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-21 14:06:56 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