Capítulo 2. Primeros pasos

# Capítulo 2. Primeros pasos

The rewrite of this tutorial document with updated contents and more practical examples is available as Guide for Debian Maintainers. Please use this new tutorial as the primary tutorial document.

Vamos a construir nuestro propio paquete (o, mejor aún, adoptar un paquete ya existente).

## 2.1. Plan de trabajo para la construcción de paquetes Debian

Si estas construyendo un paquete Debian con las fuentes originales, el plan de trabajo típico implica varias etapas (en las cuales se generan archivos con nombres específicos) y que se explican a continuación:

- Conseguimos las fuentes originales del programa, normalmente en un archivo comprimido en formato «tar».

  - ``nombre_del_paquete`-`versión`.tar.gz`

- Añadir las modificaciones específicas de Debian al programa original en el directorio `debian`, y construir un paquete de fuentes no nativo (es decir, el conjunto de archivos de entrada utilizados para la construcción de paquetes Debian) en formato `3.0 (quilt)`).

  - ``nombre_del_paquete`_`versión`.orig.tar.gz`
  - ``nombre_del_paquete`_`versión`-`revisión`.debian.tar.gz` [4]
  - ``nombre_del_paquete`_`versión`-`revisión`.dsc`

- Construimos los paquetes binarios Debian, que son archivos instalables ordinarios en formato `.deb` (o en formato `.udeb`, utilizado por el instalador de Debian), desde el paquete fuente de Debian.

  - ``nombre_del_paquete`_`versión`-`revisión`_`arquitectura`.deb`

Fíjate que el carácter que separa ``nombre_del_paquete`` y ``versión`` se ha cambiado de `-` (guión) a `_` (guión bajo).

En los nombres de archivo que siguen, ``nombre_del_paquete`` se substituye por el nombre del paquete, ``versión`` por la versión del código fuente, ``revisión`` por la revisión Debian, ``arquitectura`` por la arquitectura del paquete [5].

Cada paso de este esquema se explica con ejemplos detallados en secciones posteriores.

## 2.2. Elige el programa

Probablemente hayas escogido ya el paquete que deseas construir. Lo primero que debes hacer es comprobar si el paquete está ya en el archivo de la distribución utilizando:

- la orden aptitude

- la página web Debian packages

- the Debian Package Tracker web page

Si el paquete ya existe, ¡instálalo! :-) Si te encuentras con que el paquete es un paquete huérfano (cuando su desarrollador es el Debian QA Group, es decir, el grupo de calidad de Debian), puedes adoptarlo (convertirte en el responsable de empaquetarlo y mantenerlo) si está disponible. También puedes adoptar un paquete para el cual se ha emitido una «solicitud de adopción» (Request for Adoption o RFA) por su desarrollador o por un DD [6].

Hay varios recursos para conocer el estado de los paquetes:

- La orden wnpp-alert del paquete `devscripts`

- Paquetes pendientes y futuros nuevos paquetes

- Registro de informes de fallos de Debian: errores en el paquete `wnpp` en la versión `unstable`

- Paquetes Debian que necesitan cariño

- Búsqueda de errores `wnpp` basada en palabras clave

A modo de nota al margen, es importante tener presente que Debian incorpora paquetes de un gran número de programas de todo tipo, y que la cantidad de paquetes disponibles en el repositorio de Debian es mucho mayor al de colaboradores con permiso para incorporar paquetes al repositorio. En consecuencia, la colaboración en el mantenimiento de paquetes que ya están en el repositorio se valora muy positivamente (y es más fácil conseguir patrocinador) por el resto de desarrolladores [7]. Puedes hacer esto de distintas formas:

- hacerte cargo de paquetes huérfanos pero que son utilizados frecuentemente por otros usuarios

- incorporándote a los equipos de desarrolladores.

- seleccionando errores de los paquetes más populares

- preparando paquetes QA o NMU

If you are able to adopt the package, get the sources (with something like `apt-get source `packagename``) and examine them. This document unfortunately doesn't include comprehensive information about adopting packages. Thankfully you shouldn't have a hard time figuring out how the package works since someone has already done the initial setup for you. Keep reading, though; a lot of the advice below will still be applicable to your case.

Si el paquete es nuevo y decides que te gustaría verlo en Debian debes seguir los pasos indicados a continuación:

- En primer lugar deberías saber cómo funciona, y haberlo utilizado durante algún tiempo (para confirmar su utilidad).

- You must check that no one else is already working on the package on the Work-Needing and Prospective Packages site. If no one else is working on it, file an ITP (Intent To Package) bug report to the `wnpp` pseudo-package using reportbug. If someone's already on it, contact them if you feel you need to. If not — find another interesting program that nobody is maintaining.

- El programa debe tener una licencia.

  - Si el paquete debe pertenecer a la sección `main` el programa debe cumplir con las Directrices de Debian para el software libre (DFSG) y no debe precisar la instalación de otro paquete que no pertenezca a la sección `main` para su compilación o ejecución como requiere la directiva de Debian («Debian Policy»). Es la situación deseada.

  - Para paquetes de la sección `contrib` la licencia debe cumplir todos los requisitos de la DFSG pero puede precisar la instalación de otro paquete que no sea de la sección `main` para su compilación o ejecución.

  - Para paquetes de la sección `non-free`, no es necesario que la licencia cumpla todos los requisitos de la DFSG pero debe permitir la distribución del programa.

  - Si no estás seguro sobre en qué lugar debería ir, envía el texto de la licencia y pide consejo con un correo (en inglés) dirigido a debian-legal@lists.debian.org.

- The program should not introduce security and maintenance concerns into the Debian system.

  - The program should be well documented and its code needs to be understandable (i.e., not obfuscated).

  - Deberías contactar con el autor o autores del programa para comprobar su conformidad con el empaquetado. Es importante que el autor o autores sigan manteniendo el programa para que puedas en el futuro consultarle/s en caso de que haya problemas específicos. No deberías intentar empaquetar programas que no estén mantenidos.

  - El programa no debería ejecutarse con «setuid root», o aún mejor: no debería ser «setuid» ni «setgid».

  - El programa no debería ser un demonio, o algo que vaya en los directorios `*/sbin`, o abrir un puerto como usuario administrador.

Of course, the last one is just a safety measure, and is intended to save you from enraging users if you do something wrong in some setuid daemon… When you gain more experience in packaging, you'll be able to package such software.

Como nuevo desarrollador, es aconsejable que adquieras experiencia con la construcción de paquetes sencillos y se desaconseja construir paquetes complicados.

- Paquetes sencillos

  - archivo binario único, arquitectura = todas (colección de datos como gráficos de fondo de pantalla)

  - archivo binario único, arquitectura = todas (ejecutables escritos en lenguajes interpretados como POSIX)

- Paquetes de complejidad intermedia

  - paquete binario simple, arquitectura = todas (ejecutables ELF escritos en lenguajes compilados tales como C y C + +)

  - paquete binario múltiple, arquitectura = todas y cualquiera (paquetes de ejecutables ELF y documentación)

  - paquetes en los que el formato del archivo fuente no es `tar.gz` ni `tar.bz2`

  - paquetes cuyas fuentes contienen partes que no se pueden distribuir.

- Paquetes muy complejos

  - paquete de módulos de lenguaje interpretado utilizado por otros paquetes

  - paquetes de bibliotecas ELF genéricas utilizadas por otros paquetes

  - múltiples paquetes binarios incluyendo un paquete(s) de bibliotecas ELF

  - paquetes de fuentes con múltiples originales

  - paquetes de módulos del núcleo

  - paquetes de parches del núcleo,

  - cualquier paquete de guiones de desarrollador no triviales

Construir paquetes de alta complejidad no es demasiado difícil, pero requiere más conocimientos. Debes buscar las orientaciones específicas para cada caso según su complejidad. Por ejemplo, algunos lenguajes interpretados tienen sus normas específicas.

- Perl policy

- Normas para Python

- Normas para Java

There is another old Latin saying: fabricando fit faber (practice makes perfect). It is highly recommended to practice and experiment with all the steps of Debian packaging with simple packages while reading this tutorial. A trivial upstream tarball, `hello-sh-1.0.tar.gz`, created as follows may offer a good starting point:[8]

    $ mkdir -p hello-sh/hello-sh-1.0; cd hello-sh/hello-sh-1.0
    $ cat > hello <<EOF
    #!/bin/sh
    # (C) 2011 Foo Bar, GPL2+
    echo "Hello!"
    EOF
    $ chmod 755 hello
    $ cd ..
    $ tar -cvzf hello-sh-1.0.tar.gz hello-sh-1.0

## 2.3. Obtén el programa y pruébalo

Lo primero que debes hacer es encontrar y descargar el código fuente original. A partir de este punto se da por supuesto que ya tienes el código fuente que obtuviste de la página del autor. Las fuentes de los programas libres de Unix (y GNU/Linux) generalmente vienen en formato tar+gzip, con extensión `.tar.gz` o en formato tar+bzip2 con extensión `.tar.bz2`, y generalmente contienen un subdirectorio llamado ``programa`-`versión`` con todas las fuentes en él.

If the latest version of the source is available through a Version Control System (VCS) such as Git, Subversion, or CVS, you need to get it with `git clone`, `svn co`, or `cvs co` and repack it into tar+gzip format yourself by using the `--exclude-vcs` option.

Si tu programa viene en otro tipo de archivo (por ejemplo, el fichero termina en `.Z` o `.zip`[9]), descomprímelo con las herramientas adecuadas y reconstrúyelo de nuevo.

Si el código fuente del programa viene con algunos contenidos que no cumplan con las DFSG, debes descomprimirlo para eliminar dichos contenidos y volver a comprimirlo modificando el código de versión original añadiendo `dfsg`.

Como ejemplo, usaré el programa conocido como gentoo, un gestor de ficheros de X11 en GTK+ [10].

Crea un subdirectorio en tu directorio personal llamado `debian` o `deb` o lo que creas apropiado (por ejemplo `~/gentoo/` estaría bien en este caso). Mueve a él el archivo que has descargado, y descomprímelo de la siguiente forma: `tar xzf gentoo-0.9.12.tar.gz`. Asegúrate de que no hay errores, incluso errores irrelevantes, porque es muy probable que haya problemas al desempaquetarlo en sistemas de otras personas, cuyas herramientas de desempaquetado puede que no ignoren estas anomalías. En el terminal de órdenes, deberías ver lo siguiente.

    $ mkdir ~/gentoo ; cd ~/gentoo
    $ wget http://www.example.org/gentoo-0.9.12.tar.gz
    $ tar xvzf gentoo-0.9.12.tar.gz
    $ ls -F
    gentoo-0.9.12/
    gentoo-0.9.12.tar.gz

Ahora tienes otro subdirectorio, con el nombre `gentoo-0.9.12`. Accede a ese directorio y lee atentamente la documentación. Habitualmente encontrarás archivos con el nombre `README*`, `INSTALL*`, `*.lsm` o `*.html`. Deberías encontrar instrucciones sobre cómo compilar e instalar el programa (probablemente se asumirá que la instalación será en el directorio `/usr/local/bin`, aunque tú no lo harás eso, como se explica más adelante en Sección 3.3, “Instalación de los archivos en su destino” ).

Deberías empezar a construir tu paquete en un directorio de fuentes completamente limpio, o simplemente con las fuentes recién desempaquetadas.

## 2.4. Métodos de compilación simple

Los programas sencillos incluyen un fichero `Makefile` y pueden (generalmente) compilarse con «`make`»[11]. Algunos de ellos soportan `make check`, esta orden ejecuta las comprobaciones automáticas que estén definidas. Generalmente se instalarán en sus directorios de destino ejecutando `make install`.

Ahora intenta compilar y ejecutar el programa, para asegurarte que funciona bien y que no genera errores en el sistema mientras está instalándose o ejecutándose.

También, generalmente, puedes ejecutar `make clean` (o mejor `make distclean`) para limpiar el directorio donde se compila el programa. A veces hay incluso un `make uninstall` que se puede utilizar para borrar todos los archivos instalados.

## 2.5. Métodos de compilación portables populares

Buena parte de los programas libres están escritos en lenguaje C y C++. Muchos utilizan las «Autotools» y «CMake» para compilar en diferentes plataformas. Estas herramientas se utilizan para generar un archivo `Makefile` y otros archivos necesarios para la compilación. Así, muchos programas se compilan ejecutando «`make; make install`».

Las Autotools son el sistema de compilación GNU e incluyen Autoconf, Automake, Libtool y gettext. Confirmarás que el programa utiliza las autoools por la presencia de los archivos `configure.ac`, `Makefile.am`, y `Makefile.in` [12].

El primer paso en el uso de «Autotools» es la ejecución por parte del autor de la orden `autoreconf -i -f` la cual genera, a partir de los archivos fuente (a la izquierda del gráfico) los archivos que utilizará la orden «configure» (a la derecha del gráfico).

    configure.ac-----+-> autoreconf -+-> configure
    Makefile.am -----+        |      +-> Makefile.in
    src/Makefile.am -+        |      +-> src/Makefile.in
                              |      +-> config.h.in
                          automake
                          aclocal
                          aclocal.m4
                          autoheader

La edición de los archivos `configure.ac` y `Makefile.am` requiere conocer el funcionamiento de autoconf y automake. Véase «`info autoconf`» y «`info automake`» (ejecutando las órdenes en el terminal).

El segundo paso en el uso de «Autotools« es la ejecución de «`./configure && make`» en el directorio del código fuente para compilar el programa generando un archivo `binario`.

    Makefile.in -----+                +-> Makefile -----+-> make -> binary
    src/Makefile.in -+-> ./configure -+-> src/Makefile -+
    config.h.in -----+                +-> config.h -----+
                     |
      config.status -+
      config.guess --+

Puedes hacer cambios en el archivo `Makefile`, por ejemplo cambiando el directorio de instalación predeterminado usando las opciones de la orden ejecutando: ./configure --prefix=/usr.

Aunque no es necesario, la actualización del archivo `configure` y de otros archivos con la orden `autoreconf -i -f` es la mejor manera para mejorar la compatibilidad del código fuente [13].

CMake es un sistema de compilación alternativo. La presencia del archivo `CMakeLists.txt` te indicará que se utiliza esta opción para compilar el programa.

## 2.6. Nombre del paquete y versión

Si el código original se presenta como `gentoo-0.9.12.tar.gz`, puedes poner como nombre del paquete `gentoo` y como versión original `0.9.12`. Estas referencias se utilizan en el archivo `debian/changelog` descrito más adelante en Sección 4.3, “El archivo `changelog`”.

Although this simple approach works most of the time, you may need to adjust package name and upstream version by renaming the upstream source to follow Debian Policy and existing convention.

You must choose the package name to consist only of lower case letters (`a-z`), digits (`0-9`), plus (`+`) and minus (`-`) signs, and periods (`.`). It must be at least two characters long, must start with an alphanumeric character, and must not be the same as existing packages. It is a good idea to keep its length within 30 characters. [14]

Si el código fuente original utiliza palabras genéricas tales como `prueba-privada` por nombre, es buena idea cambiarlo para no «contaminar» el espacio de nombres y para identificar su contenido en forma explícita [15].

You should choose the upstream version to consist only of alphanumerics (`0-9A-Za-z`), plus signs (`+`), tildes (`~`), and periods (`.`). It must start with a digit (`0-9`). [16] It is good idea to keep its length within 8 characters if possible. [17]

If upstream does not use a normal versioning scheme such as `2.30.32` but uses some kind of date such as `11Apr29`, a random codename string, or a VCS hash value as part of the version, make sure to remove them from the upstream version. Such information can be recorded in the `debian/changelog` file. If you need to invent a version string, use the `YYYYMMDD` format such as `20110429` as upstream version. This ensures that dpkg interprets later versions correctly as upgrades. If you need to ensure smooth transition to the normal version scheme such as `0.1` in the future, use the `0~YYMMDD` format such as `0~110429` as the upstream version.

El código de la versión [18] será comparado por dpkg(1) como sigue:

    $ dpkg --compare-versions versión_1 op versión_2

La regla de comparación de versiones se pueden resumir de la siguiente manera.

- Las cadenas se comparan desde el inicio hasta el final.

- Los caracteres (letras y símbolos) son anteriores a los números.

- Los números se comparan como enteros.

- Los caracteres (letras y símbolos) se comparan en el orden del código ASCII.

- Hay algunas reglas especiales para los puntos (`.` ), símbolo de suma (`+`) y tildes (`~`) como se explica a continuación:

  `0.0` < `0.5` < `0.10` < `0.99` < `1` < `1.0~rc1` < `1.0` < `1.0+b1` < `1.0+nmu1` < `1.1` < `2.0`

Uno de los casos difíciles sucede cuando la versions del código fuente `gentoo-0.9.12-ReleaseCandidate-99.tar.gz` se utiliza como el pre-lanzamiento de `gentoo-0.9.12.tar.gz`. Debes asegurarte que la actualización funciona correctamente cambiando el nombre a las fuentes originales por `gentoo-0.9.12~rc99.tar.gz`.

## 2.7. Configurar dh_make

Primero debes configurar las variables de entorno «shell» `$DEBEMAIL` y `$DEBFULLNAME` que son utilizadas por varias herramientas de mantenimiento de Debian para obtener tu nombre y correo electrónico como se indica a continuación [19].

    $ cat >>~/.bashrc <<EOF
    DEBEMAIL="tu.direccion.de.correo@ejemplo.org"
    DEBFULLNAME="Nombre Apellido"
    export DEBEMAIL DEBFULLNAME
    EOF
    $ . ~/.bashrc

## 2.8. Paquete no nativo Debian inicial

Los paquetes Debian normales son paquetes no nativos construidos a partir de los programas originales de los autores. Si deseas construir un paquete Debian no nativo a partir del código fuente original `gentoo-0.9.12.tar.gz`, puedes construir un primer paquete de Debian no nativo ejecutando la orden dh_make como sigue:

    $ cd ~/gentoo
    $ wget http://example.org/gentoo-0.9.12.tar.gz
    $ tar -xvzf gentoo-0.9.12.tar.gz
    $ cd gentoo-0.9.12
    $ dh_make -f ../gentoo-0.9.12.tar.gz

Deberás cambiar el nombre del archivo por el correspondiente a tus fuentes [20]. Véase dh_make(8) para una descripción más detallada.

You should see some output asking you what sort of package you want to create. Gentoo is a single binary package — it creates only one binary package, i.e., one `.deb` file — so we will select the first option (with the `s` key), check the information on the screen, and confirm by pressing ``ENTER``. [21]

Tras ejecutar dh_make, se genera una copia del código original con el nombre `gentoo_0.9.12.orig.tar.gz` en el directorio raíz para facilitar la construcción del paquete de fuentes no nativo de Debian con el archivo `debian.tar.gz`:

    $ cd ~/gentoo ; ls -F
    gentoo-0.9.12/
    gentoo-0.9.12.tar.gz
    gentoo_0.9.12.orig.tar.gz

Observa que hay dos cambios clave en el nombre del fichero `gentoo_0.9.12.orig.tar.gz`:

- El nombre del paquete y la versión están separados por «`_`».

- Hay un `.orig` antes de `.tar.gz`.

Observa que la ejecución de la orden ha generado varios archivos de plantilla en el directorio `debian`. Se tratará sobre ellos en Capítulo 4, Archivos necesarios en el directorio `debian` y Capítulo 5, Otros ficheros en el directorio `debian`.. El proceso de empaquetado no está totalmente automatizado. Se tratará la modificación de los archivos Debian en Capítulo 3, Modificar las fuentes. A continuación se compilará el paquete Debian en el apartado Capítulo 6, Construcción del paquete, la revisión del resultado en Capítulo 7, Comprobación del paquete en busca de fallos y el envío del paquete en Capítulo 9, Enviar el paquete. Se explicará cada una de estas etapas a continuación.

Si accidentalmente has eliminado alguna de las plantillas mientras trabajabas en ellas, puedes regenerarlas ejecutando dh_make con la opción `--addmissing` desde el directorio con las fuentes del paquete Debian.

Actualizar un paquete existente puede complicarse debido a que puede estar construido con técnicas más antiguas. Para aprender lo básico, es mejor limitarse a la construcción de un paquete nuevo; se amplia la explicación en Capítulo 8, Actualizar el paquete.

Please note that the source file does not need to contain any build system discussed in Sección 2.4, “Métodos de compilación simple” and Sección 2.5, “Métodos de compilación portables populares”. It could be just a collection of graphical data, etc. Installation of files may be carried out using only `debhelper` configuration files such as `debian/install` (see Sección 5.11, “Archivo `install`”).

[4] Para paquetes no nativos Debian construidos en el formato anterior `1.0`, se utiliza ``nombre_del_paquete`_`versión`-`revisión`.diff.gz`

[5] Consulta 5.6.1 "Source", 5.6.7 "Package", and 5.6.12 "Version". La arquitectura del paquete sigue el Debian Policy Manual, 5.6.8 "Architecture" y se asigna automáticamente en el proceso de compilación del paquete.

[6] See Debian Developer's Reference 5.9.5 "Adopting a package".

[7] Dicho esto, por supuesto, hay nuevos programas que vale la pena empaquetar para Debian.

[8] No debes preocuparte por perder el `Makefile`. Puedes instalar la orden hello simplemente utilizando debhelper como en Sección 5.11, “Archivo `install`”, o modificando las fuentes originales agregando un nuevo `Makefile` con el objetivo `install` como en Capítulo 3, Modificar las fuentes.

[9] Puedes identificar el formato de archivo utilizando la herramienta file cuando no es suficiente con la extensión de fichero.

[10] Ten en cuenta que el programa ya ha sido empaquetado previamente. La versión actual utiliza las «Autotools» en su construcción y ha cambiado sustancialmente de la versión 0.9.12 que se utiliza en los ejemplos mostrados a continuación.

[11] Many modern programs come with a script named `configure`, which when executed creates a `Makefile` customized for your system.

[12] Autotools is too big to deal with in this small tutorial. This section is meant to provide keywords and references only. Please make sure to read the Autotools Tutorial and the local copy of `/usr/share/doc/autotools-dev/README.Debian.gz`, if you need to use it.

[13] Añade el paquete `dh-autoreconf` en el campo `Build-Depends`. Véase Sección 4.4.3, “Personalización del archivo `rules`”.

[14] La longitud predeterminada del nombre del paquete en la orden aptitude es 30. En más del 90% de los paquetes, la longitud del nombre del paquete es inferior a 24 caracteres.

[15] If you follow the Debian Developer's Reference 5.1. "New packages", the ITP process will usually catch this kind of issue.

[16] Esta norma más estricta debería ayudar a evitar confundir los nombres de archivo.

[17] El valor predeterminado para la longitud de la versión de la orden aptitude es 10. El código de la revisión Debian precedida por un guión consume 2. Para más del 80% de los paquetes, el código de la versión original es de menos de 8 caracteres y el de la revisión Debian es de menos de 2 caracteres. Para más del 90% de los paquetes, la versión original es de menos de 10 caracteres y la revisión Debian es de menos de 3 caracteres.

[18] Las cadenas de versión pueden ser la versión del código fuente (``versión``), la revisión Debian (``revisión``), o versión (``versión`-`revisión``). Consulta Sección 8.1, “Nueva revisión Debian del paquete” para saber cómo debe incrementarse la revisión Debian.

[19] El texto mostrado a continuación da por supuesto que estás ejecutando «bash» como tu intérprete de línea de órdenes. Si utilizas otros intérpretes, como «Z shell», deberás utilizar sus correspondientes ficheros de configuración en lugar de `~/.bashrc`.

[20] If the upstream source provides the `debian` directory and its contents, run the dh_make command with the extra option `--addmissing`. The new source `3.0 (quilt)` format is robust enough not to break even for these packages. You may need to update the contents provided by the upstream version for your Debian package.

[21] Se ofrecen varias opciones aquí: `s` para un binario,`i` para un paquete independiente de la arquitectura (sólo código fuente o bien documentación), `m` para más de un binario, `l` para una biblioteca, `k` para un módulo del núcleo («kernel»), `n` para un parche del núcleo y `b` para paquetes `cdbs`. Este documento se centra en el uso del paquete `debhelper` con la orden dh para la construcción de paquetes con un binario y trata solo parcialmente su uso en la construcción de paquetes independientes de la arquitectura y con más de un binario. El paquete `cdbs` ofrece guiones alternativos a la orden dh y su uso queda fuera de este documento.

Capítulo 1. Empezando «de la forma correcta». |  | Capítulo 3. Modificar las fuentes