[ anterior ] [ Nota de Copyright ] [ Contenidos ] [ siguiente ]

Guía del Nuevo Desarrollador de Debian
Capítulo 4 Las cosas necesarias bajo debian/


Ahora hay un nuevo subdirectorio bajo el directorio principal del programa ('gentoo-0.9.12'), que se llama 'debian'. Hay bastantes ficheros en este directorio. Empezaremos editando éstos para adaptar el comportamiento del paquete. La parte más importante es modificar los ficheros 'control', 'rules' (reglas, n. del t.), 'changelog', y 'copyright' que se necesitan en todos los paquetes.


4.1 El fichero `control'.

Este fichero contiene varios valores que dpkg y dselect usarán para gestionar el paquete. Aquí está el fichero de control que dh_make crea para nosotros.

     1 Source: gentoo
       2 Section: unknown
       3 Priority: optional
       4 Maintainer: Josip Rodin <jrodin@jagor.srce.hr>
       5 Standards-Version: 3.0.1
       6
       7 Package: gentoo
       8 Architecture: any
       9 Depends: ${shlibs:Depends}
       9  Depends: ${shlibs:Depends}
       10 Deguiónion: <insertar unos 60 caracteres de descripción>
       11  <inserta una descripción ligera, indentado con espacios>

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

La línea 3 describe cómo de importante es para el usuario la instalación de éste paquete. La sección y prioridad son actualmente sólo usadas por dselect cuando ordena paquetes y selecciona valores por defecto, y pueden ser modificadas (y generalmente lo serán) por nuestros administradores del FTP. Lea el manual de Política de Debian para una guía de qué valor deben tener estos campos.

Como es un paquete de prioridad normal, lo dejaremos con prioridad 'optional' (opcional, n. del t.).

La línea 4 es el nombre y correo electrónico del desarrollador.

La línea 5 es la versión de los estándares de la Política de Debian que sigue este paquete (dos versiones importantes del paquete debian-policy instalado).

Si se necesita un compilador no estándar o alguna otra herramienta para construir el paquete, debería añadir aquí una línea 'Build-depends' y listar los paquetes necesarios. Para más información sobre ésto lea el Manual de Empaquetamiento (sección 8.7) y la documentación en el paquete 'build-essential'.

La línea 7 es el nombre del paquete binario.

La línea 8 describe la arquitectura de CPU para la que se compiló el paquete. Podemos dejar ésta como 'any' (cualquiera, n. del. t), ya que dpkg-gencontrol(1) lo rellenará con el valor apropiado cuando se compile este paquete (lea la Referencia del Desarrollador para una explicación de qué es portar paquetes). Si su paquete es independiente de la arquitectura (por ejemplo, un documento, un programa de shell o un guión en Perl), cambie esto a "all", y lea más adelante el fichero `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 9 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, n. del t.) otros campos de relación son 'Recommends:' (recomienda, n. del t.), 'Suggests:' (sugiere, n. del t.), 'Pre-depends:' (predepende de, n. del t.), 'Conflicts:' (entra en conflicto con, n. del t.), 'Provides:' (provee, n. del t.), 'Replaces:' (reemplaza a, n. del t.). Ésto es lo que significan:

Esto es lo que generalmente significan:

Todos estos campos tienen una sintaxis uniforme. Tienen 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 aplicabilidad a versiones determinadas de cada paquete nombrado. Esto se hace entre paréntesis para cada nombre de paquete individual; los paréntesis deberían contener una relación de la siguiente lista seguida por un número de versión. Las relaciones permitidas son <<, <=, =, >= y >> estrictamente para anterior, anterior o igual, exactamente igual, posterior o igual o estrictamente posterior, respectivamente.

La última funcionalidad que quiero necesita conocer es $(shlibs:Depends). Ésta se sustituirá automáticamente por dh_shlibdeps(1) y rellenada por dh_gencontrol(1) por los nombres de cualquier librería compartida, como libc6 o xlib6g, que use su programa, así que no necesita especificar esto usted mismo. Habiendo dicho todo esto, puede dejar la línea 9 exactamente como está ahora.

La línea 10 es donde va la lista de sugerencias. Aquí sólo es 'file', porque gentoo utiliza algunas funciones de este paquete/programa.

La línea 11 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 "A fully GUI configurable GTK+ file manager" ("Una GUI GTK+ a un gestor de ficheros completamente configurable").

La línea 12 es donde va la descripción larga del paquete. Debería ser al menos un párrafo que da más detalles del paquete. La Columna 1 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. También no debe haber más de una línea en blanco después de la descripción completa.

Aquí está el fichero de control actualizado:

       1  Source: gentoo
       2  Section: x11
       3  Priority: optional
       4  Maintainer: Josip Rodin <jrodin@jagor.srce.hr>
       5  Standards-Version: 3.0.1
       6
       7  Package: gentoo
       8  Architecture: any
       9  Depends: ${shlibs:Depends}
       10 Suggests: file 
       11 Deguiónion: A fully GUI configurable GTK+ file manager
       12 gentoo is a file manager for Linux written from scratch in pure C. It
       13 uses the GTK+ toolkit for all of its interface needs. gentoo provides
       14 100% GUI configurability; no need to edit config files by hand and re-
       15 start the program. gentoo supports identifying the type of various
       16 files (using extension, regular expressions, or the 'file' command),
       17 and can display files of different types with different colors and icons.
       18 .
       19 gentoo borrows some of its look and feel from the classic Amiga file
       20 manager "Directory OPUS" (written by Jonathan Potter).


4.2 el fichero `copyright'

Este fichero contiene la información sobre la licencia y copyright de las fuentes originales del paquete. El formato no está definido en la Política, pero sí sus contenidos (sección 6.5). Dh_make crea un fichero por defecto que es así:

       1  This package was debianized by Josip Rodin <jrodin@jagor.srce.hr> on
       2  Wed, 11 Nov 1998 21:02:14 +0100.
       3
       4  It was downloaded from <fill in ftp site>
       5
       6  Upstream Author(s): <put author(s) name and email here>
       7
       8  Copyright:
       9
       10 <Must follow here>

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

Las cosas importantes que se deben añadir a este fichero son el lugar de donde obtuvo el paquete y la nota de copyright y licencia originales. Debe incluir la licencia completa, a menos que sea una licencia común en el mundo del software libre como GNU GPL o LGPL, BSD o la 'Artistic license', basta referirse al fichero apropiado en el directorio /usr/share/common-licenses/ que existe en todo sistema Debian. Gentoo está licenciado bajo la Licencia Pública General GNU, así que cambiaremos el fichero a esto:

       1  This package was debianized by Josip Rodin <jrodin@jagor.srce.hr> on
       2  Wed, 11 Nov 1998 21:02:14 +0100.
       3
       4  It was downloaded from: ftp://ftp.obsession.se/gentoo/
       5
       6  Upstream author: Emil Brink <emil@obsession.se>
       7
       8  This software is copyright (c) 1998-99 by Emil Brink, Obsession
       9  Development.
       10
       11 You are free to distribute this software under the terms of
       12 the GNU General Public License.
       13 On Debian systems, the complete text of the GNU General Public
       14 License can be found in /usr/share/common-licenses/GPL file.

(He añadido los números de línea) (Nota del T.: la política de Debian actual indica que los documentos aquí citados estén escritos en inglés, al ser el idioma oficial del, proyecto por ello no se traducen en este documento)


4.3 el fichero `changelog'

Este es un fichero requerido, que tiene un formato especial descrito en el Manual de Empaquetamiento (sección 3.2.3). Este formato es usado por dpkg y otros programas para obtener el número de versión, revisión, distribución y urgencia de su paquete.

Para usted es también importante, ya que es bueno tener documentados todos los cambios que haya hecho. Le ayudará a las personas que se descargen su paquete para ver si hay temas pendientes en el paquete que deberían conocer de forma inmediata. Se salvará como `/usr/share/doc/gentoo/changelog.Debian.gz' en el paquete binario.

Dh_make crea uno por defecto, que es algo así:

       1  gentoo (0.9.12-1) unstable; urgency=low
       2
       3   * Initial Release.
       4
       5  -- Josip Rodin <jrodin@jagor.srce.hr> Wed, 11 Nov 1998 21:02:14 +0100
       6
       7  Local variables:
       8  mode: debian-changelog
       9  End:

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

(N. del T.: se traduce el fichero de copyright, dh_make sólo lo ofrece en inglés)

       1  Éste paquete fue debianizado por Josip Rodin jrodin@jagor.srce.hr el
       2  Mie, 11 Nov 1998 21:02:14 +0100.
       3
       4  Se descargó de  <rellenar el servidor de ftp>
       5
       6  Autor/es Original/es: <poner el nombre/s de el/los autor/es y
       7  dirección de correo electrónico aquí>
       8  Copyright:
       9
       10 <Debe venir aquí>

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 `experimental', y la urgencia no debería cambiarse a algo mayor que `low'. :-)

Las línea 3-5 son una entrada de registro, donde documenta los cambios hechos en esta revisión del paquete (no los cambios de la fuente original - hay un fichero especial para este propósito, creado por los autores originales e instalado como /usr/share/doc/gentoo/changelog.gz). Las nuevas líneas deben ser insertadas justo antes de la línea que hay más arriba que comienza por un asterisco (`*'). Puede hacerlo con dch(1), emacs(1) (las líneas 7 a la 9 contienen información de modo para el editor Emacs), o cualquier otro editor de texto. Terminará con algo así:

       1  gentoo (0.9.12-1) unstable; urgency=low
       2
       3   * Initial Release.
       4   * This is my first Debian package.
       5   * Adjusted the Makefile to fix $DESTDIR problems.
       6
       7  -- Josip Rodin <jrodin@jagor.srce.hr> Wed, 11 Nov 1998 21:02:14 +0100
       8
       9  Local variables:
       10  mode: debian-changelog
       11 End:

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

Cuando distribuya una nueva revisión, sólo debe incrementar el número de versión. Puede hacer esto sólo con `dch -i` o explícitamente con `dch -v <versión>-<revisión>` y después insertar los comentarios usando su editor preferido. Pista: ¿cómo obtener rápidamente la fecha en el formato necesario? Use `822-date`, o `date -R`.

La nueva información sobre la versión se añade al principio del fichero de cambios. Esto es como el fichero de cambios quedará después:

       1  gentoo (0.9.12-2) unstable; urgency=low
       2
       3   * Fixed a glitch in the menu file.
       4
       5  -- Josip Rodin <jrodin@jagor.srce.hr> Wed, 11 Nov 1998 22:15:39 +0100
       6
       7  gentoo (0.9.12-1) unstable; urgency=low
       8
       9   * Initial Release.
       10  * This is my first Debian package.
       11  * Adjusted the Makefile to fix $DESTDIR problems.
       12
       13 -- Josip Rodin <jrodin@jagor.srce.hr> Wed, 11 Nov 1998 21:02:14 +0100
       14
       15 Local variables:
       16 mode: debian-changelog
       17 End:

(I've added the line numbers.)

Puede leer más sobre nuevas versiones/revisiones de paquetes más adelante en Actualizar su paquete, Sección 6.4.


4.4 el fichero `rules'.

Ahora volvemos al directorio 'debian' para mirar las reglas que dpkg-buildpackage(1) utilizará para crear el paquete. Este fichero es en realidad otro Makefile, ya que es ejecutado con 'make -f', pero diferente al que viene en las fuentes originales.

Cada fichero 'rules' (de reglas, n. del t.), como muchos otros Makefiles, consiste de varias reglas sobre cómo compilar las fuentes. Las reglas consisten en objetivos: ficheros o nombres de acciones que se deben llevar a cabo (por ejemplo, 'build:' o 'install:'). Las reglas que quiere ejecutar deberían llamarse como los argumentos de comandos (por ejemplo, './debian/rules build' o 'make -f rules install'). Después del nombre del objetivo, puede nombrar las dependencias, programas o ficheros de los que la regla depende. 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. Líneas múltiples en blanco, o líneas que empiezan por almohadillas ('#') se tratan como comentarios y se ignoran.

Probablemente ya se haya perdido, pero todo quedará más claro después de ver un fichero 'rules' que dh_make pone por defecto. Debería también leer la entrada de 'make' en info para más información.

La parte importante que debe conocer sobre el fichero de reglas creado por dh_make, es que sólo es una sugerencia. Funcionará para paquetes simples pero para más complicados, no se asuste y añada o sustraiga de éste para ajustarse a sus necesidades. Una cosa que no debe cambiar son los nombres de las reglas, porque todas las herramientas utilizan estos nombres, como se indica en el Manual de Empaquetamiento.

       1  #!/usr/bin/make -f
       2  # Made with the aid of dh_make, by Craig Small
       3  # Sample debian/rules that uses debhelper. GNU copyright 1997 by Joey Hess.
       4  # Some lines taken from debmake, by Christoph Lameter.
       5
       6  # Uncomment this to turn on verbose mode.
       7  #export DH_VERBOSE=1
       8
       9  # This is the debhelper compatability version to use.
       10 export DH_COMPAT=1
       11 build: build-stamp
       12 build-stamp:
       13	dh_testdir
       14
       15	
       16	# Add here commands to compile the package.
       17	$(MAKE)
       18
       19	touch build-stamp
       20
       21 clean:
       22	dh_testdir
       23	dh_testroot
       24	rm -f build-stamp 
       25
       26	# Add here commands to clean up after the build process.
       27	-$(MAKE) clean
       28
       29	dh_clean
       30
       31 install-stamp: build-stamp
       32	dh_testdir
       33	dh_testroot
       34	dh_clean -k
       35	dh_installdirs
       36
       37	# Add here commands to install the package into debian/tmp.
       38	$(MAKE) install DESTDIR=`pwd`/debian/tmp
       39
       40 # Build architecture-independent files here.
       41 binary-indep: build install
       42 # We have nothing to do by default.
       43
       44 # Build architecture-dependent files here.
       45 binary-arch: build install
       46 #	dh_testversion
       47	dh_testdir
       48	dh_testroot
       49 #  dh_installdebconf
       50	dh_installdocs
       51	dh_installexamples
       52	dh_installmenu
       53 #	dh_installemacsen
       54 #	dh_installpam
       55 #	dh_installinit
       56	dh_installcron
       57	dh_installmanpages
       58	dh_installinfo
       59 #	dh_undocumented
       60	dh_installchangelogs
       61	dh_link
       62	dh_strip
       63	dh_compress
       64	dh_fixperms
       65	# You may want to make some executables suid here.
       66	dh_suidregister
       67 #	dh_makeshlibs
       68	dh_installdeb
       69 #	dh_perl
       70	dh_shlibdeps
       71	dh_gencontrol
       72	dh_md5sums
       73	dh_builddeb
       74
       75 binary: binary-indep binary-arch
       76 .PHONY: build clean binary-indep binary-arch binary install

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

(N. del T.: se traduce el fichero de reglas, dh_make sólo lo ofrece en inglés)

       1  #!/usr/bin/make -f
       2  # Creado con la ayuda de dh_make, por Craig Small 
       3  # Fichero de ejemplo debian/rules que usa debhelper. Copyright GNU 1997 por Joey Hess.
       4  # Algunas líneas son de debmake, por Christoph Lameter.
       5
       6  # Quitele el comentario para activar el modo verboso
       7  #export DH_VERBOSE=1
       8
       9  # Esta es la versión de compatibilidad con debhelper a usar
       10 export DH_COMPAT=1
       11 build: build-stamp
       12 build-stamp:
       13	dh_testdir
       14
       15	
       16	# Añada aquí los comandos para compilar el paquete.
       17	$(MAKE)
       18
       19	touch build-stamp
       20
       21 clean:
       22	dh_testdir
       23	dh_testroot
       24	rm -f build-stamp 
       25
       26	# Añada aquí los comandos para limpiar después del proceso de creación.
       27	-$(MAKE) clean
       28
       29	dh_clean
       30
       31 install-stamp: build-stamp
       32	dh_testdir
       33	dh_testroot
       34	dh_clean -k
       35	dh_installdirs
       36
       37	# Añada aquí los comandos para instalar el paquete en debian/tmp.
       38	$(MAKE) install DESTDIR=`pwd`/debian/tmp
       39
       40 # Construir los ficheros independientes de arquitectura aquí
       41 binary-indep: build install
       42 # Por defecto no se hace nada.
       43
       44 # Construir los ficheros dependientes de arquitectura aquí.
       45 binary-arch: build install
       46 #	dh_testversion
       47	dh_testdir
       48	dh_testroot
       49 #  dh_installdebconf
       50	dh_installdocs
       51	dh_installexamples
       52	dh_installmenu
       53 #	dh_installemacsen
       54 #	dh_installpam
       55 #	dh_installinit
       56	dh_installcron
       57	dh_installmanpages
       58	dh_installinfo
       59 #	dh_undocumented
       60	dh_installchangelogs
       61	dh_link
       62	dh_strip
       63	dh_compress
       64	dh_fixperms
       65	# Puede hacer algunos ejecutables suid aquí
       66	dh_suidregister
       67 #	dh_makeshlibs
       68	dh_installdeb
       69 #	dh_perl
       70	dh_shlibdeps
       71	dh_gencontrol
       72	dh_md5sums
       73	dh_builddeb
       74
       75 binary: binary-indep binary-arch
       76 .PHONY: build clean binary-indep binary-arch binary install

Probablemente esté familiarizado con líneas como la 1 de guiones hechos en shell o perl. Esto significa que el fichero debe ejecutarse con make.

Las líneas 12 a la 19 describen la regla de construcción (en inglés: build, n. del t.) que ejecuta el Makefile del propio programa para compilarlo.

Las cosas rara vez funcionan perfectamente la primera vez, así que se especifica la regla de limpieza (del inglés 'clean', n. del t.) en las líneas 18-26 que limpian cualquier resto innecesario dejado de intentos previos fallidos.

La regla 'clean' (limpia, n. del t.), como se especifica en las líneas 21-29, limpia cualquier binario innecesario o cosas automáticamente generadas, dejadas después de la construcción del paquete. Esta regla debe funcionar en todo momento (incluso cuando el árbol de fuentes está limpio!), así que por favor use las opciones que fuerzan a hacer cosas (por ejemplo para rm, sería `-f'), o ignore los valores devueltos (con un `-' al principio de la orden).

El proceso de instalación, la regla 'install', comienza en la línea 31. Básicamente ejecuta la regla `install' del Makefile del programa, pero lo instala en el directorio `pwd`/debian/tmp - esto es por lo que especificamos $(DESTDIR) como el directorio raíz de instalación del Makefile de gentoo.

Como sugiere el comentario, la regla 'binary-indep', en la línea 41, se usa para construir paquetes independientes de arquitectura. Como no tenemos ninguno aquí no se hará nada. Si su paquete es del tipo `Architecture: all' necesita incluir todas las órdenes para crear el paquete bajo esta regla, y dejar las siguiente regla (`binary-arch') vacía en su lugar.

Lo siguiente es en la regla 'binary-arch', en las líneas 45 a 73, en la que ejecutamos varias utilidades diversas del paquete debhelper que nos permiten hacer operaciones variadas en nuestro paquete para que cumpla la política de Debian.

Los nombres comienza con dh_ y el resto es la descripción de lo que la utilidad en particular realmente hace. Es todo más o menos auto-explicativo, pero a continuación se indica lo que realmente hace cada pequeña utilidad:

Para información más completa de lo que hacen cada uno de estos guiones dh_* , y qué otras opciones tienen, por favor lea sus páginas de manual respectivas. Hay otros guiones con la misma nomenclatura (dh_*) que no se han mencionado aquí, pero pueden serle útiles. Si los necesita, lea la documentación de debhelper.

Las líneas 70 a la 74 son sólo algunas necesidades sobre las que puede leer en el manual de make. Por ahora, no es importante conocerlas.

La parte importante sobre el fichero de reglas creado por dh_make es que sólo es una sugerencia. Funcionará para paquetes simples pero para los más complicados no se asuste y modifique, borre o añada a éste para ajustarse a sus necesidades. Esto se aplica de forma especial a las secciones binary-arch, donde debería comentar las líneas que llaman a funciones que no necesita, en este caso he comentado las líneas sobre testversion, emacsen, pam, init, cron, manpages, info, undocumented, suidregister, makeshlibs, and perl, simplemente porque gentoo no las necesita. Sólo he añadido en la línea 60, `FIXES', porque este es el nombre del fichero de cambios de las fuentes.

La única cosas que no debe cambiar son los nombre de las reglas, porque es necesario que se llamen de esta forma para que todas las herramientas que las usan utilicen estos mismos nombres, esto se obliga en nuestro manual de Empaquetamiento.

Las últimas dos líneas (junto con otras que no se explican) son cosas más o menos necesarios, sobre las que puede leer en el manual de make, y en el Manual de Empaquetamiento. Por ahora no necesita saberlas.


[ anterior ] [ Nota de Copyright ] [ Contenidos ] [ siguiente ]
Guía del Nuevo Desarrollador de Debian
versión 1.0 (translation 0.9a.19), 25 de enero de 2000
Josip Rodin jrodin@jagor.srce.hr
Traducido por: Javier Fernández-Sanguino Peña jfs@computer.org