Capítol 6. Construir el paquet.

# Capítol 6. Construir el paquet.

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.

Ara hauríem d'estar preparats per construir el paquet.

## 6.1. Reconstrucció completa.

Per realitzar correctament la construcció ( o la reconstrucció) completa d'un paquet, comprova que els següents paquets estan instal·lats:

- el paquet `build-essential`.

- els paquets llistats en el camp `Build-Depends` del fitxer «control» (consulta Secció 4.1, «El fitxer `control`.»).

- els paquets llistats en el camp `Build-Depends-indep` (també de l'arxiu «control», consulta Secció 4.1, «El fitxer `control`.»).

Accedeix al directori principal del codi font del programa i executa la següent ordre:

    $ dpkg-buildpackage -us -uc

Aquesta ordre farà totes les tasques necessàries per construir els paquets binaris i de fonts. Més concretament:

- neteja l'arbre del codi (`debian/rules clean`).

- construeix el paquet de codi font (`dpkg-source -b`).

- compila el programa (`debian/rules build`).

- construeix el paquet binari (`fakeroot debian/rules binary`)

- genera el fitxer `.dsc`

- genera l'arxiu `.changes`, fent servir l'ordre dpkg-genchanges

If the build result is satisfactory, sign the `.dsc` and `.changes` files with your private GPG key using the debsign command. You need to enter your secret pass phrase, twice. [62]

Quan acabi el procés de construcció d'un paquet no nadiu Debian (p.ex.`gentoo`), veuràs els següents fitxers en el directori superior al directori de treball (`~/gentoo/`):

- `gentoo_0.9.12.orig.tar.gz`

  This is the original upstream source code tarball, merely renamed to the above so that it adheres to the Debian standard. Note that this was created initially by the command `dh_make -f ../gentoo-0.9.12.tar.gz`.

- `gentoo_0.9.12-1.dsc`

  Aquest és un sumari dels continguts del codi font. Aquest arxiu es genera amb la informació del fitxer `control` i es fa servir quan es descomprimeixen les fonts amb dpkg-source(1).

- `gentoo_0.9.12-1.debian.tar.gz`

  Aquest arxiu comprimit té tots els fitxers del directori `debian`. Les modificacions de les fonts originals es conserven en els fitxers de pegats quilt en el directori `debian/patches`.

  Si una altra persona vol tornar a construir el paquet des de l'inici, pot fer-ho fàcilment fent servir aquests tres fitxers. El procés d'extracció és trivial: només cal copiar-los en un directori i executar `dpkg-source -x gentoo_0.9.12-1.dsc` [63].

- `gentoo_0.9.12-1_i386.deb`

  Aquest és el paquet binari Debian. Pots fer servir dpkg per instal·lar o eliminar aquest paquet o qualsevol altre.

- `gentoo_0.9.12-1_i386.changes`

  Aquest arxiu conté la descripció dels canvis fets en la revisió actual del paquet, i el fan servir els programes de gestió FTP del repositori Debian per instal·lar-hi els paquets binaris i de fonts. Se genera parcialment amb l'arxiu `changelog` i el fitxer `.dsc`.

  Amb el temps, el paquet anirà canviat i s'afegiran funcions. Les persones que descarreguin el paquet poden llegir aquest arxiu i assabentar-se dels canvis. Els programes de manteniment del repositori Debian també envien el contingut d'aquest arxiu a la llista de correu debian-changes-announce@lists.debian.org.

The `gentoo_0.9.12-1.dsc` and `gentoo_0.9.12-1_i386.changes` files must be signed using the debsign command with your private GPG key in the `~/.gnupg/` directory, before uploading them to the Debian FTP archive. The GPG signature provides the proof that these files are really yours, using your public GPG key.

The debsign command can be made to sign with your specified secret GPG key ID (good for sponsoring packages) with the following in the `~/.devscripts` file:

    DEBSIGN_KEYID=el_teu_identificador_de_la_clau_GPG

Les llistes de números en els fitxers `.dsc` i `.changes` són les sumes MD5/SHA1/SHA256 dels fitxers. Les persones que descarreguen els arxius poden comprovar-los amb md5sum(1), sha1sum(1) o sha256sum(1) i si els nombres no coincideixen sabran que el fitxer està corrupte o s'ha modificat.

## 6.2. «Autobuilder».

Debian manté diverses adaptacions «ports» amb la xarxa de servidors de compilació automàtica que executa dimonis buildd en ordinadors d'arquitectura diferent. Encara que tu no hauràs de fer res de tot això, has de conèixer el processament del teu paquet. Veurem com es processa el paquet per compilar-ho en diferents arquitectures [64].

Els paquets del tipus `Architecture: any`, són construïts pel sistema de compilació automàtica. El sistema garanteix la instal·lació de:

- el paquet `build-essential`, i

- els paquets llistats en el camp `Build-Depends` (consulta Secció 4.1, «El fitxer `control`.»).

A continuació s'executa la següent ordre en el directori de les fonts:

    $ dpkg-buildpackage -B

D'aquest manera, s'executa tot el necessari per a la construcció del paquet binari depenent de l'arquitectura per a cada arquitectura. Fa el següent:

- neteja l'arbre del codi (`debian/rules clean`).

- compila el programa (`debian/rules build`).

- construeix el paquet binari per a l'arquitectura (`fakeroot debian/rules binary-arch`).

- signa l'arxiu `.dsc` fent servir l'ordre gpg

- genera i signa l'arxiu `.changes`, fent servir les ordres dpkg-genchanges i gpg

Així, el paquet estarà disponible per a altres arquitectures.

Encara que és necessari instal·lar els paquets llistats en el camp `Build-Depends-indep` per a la construcció de paquets normal (consulta Secció 6.1, «Reconstrucció completa.»), el sistema automàtic de construcció no ho requereix degut a què només construeix paquets binaris dependents de l'arquitectura [65]. Aquestes diferències entre l'empaquetament normal i l'automàtic determinen si els paquets requerits per a la compilació s'han de llistar en el camp `Build-Depends` o en el camp `Build-Depends-indep` del fitxer `debian/control` (consulta Secció 4.1, «El fitxer `control`.»).

## 6.3. L'ordre debuild.

Pots automatitzar encara més el procés de construcció de paquets de dpkg-buildpackage seguit de l'ordre debuild. Consulta debuild(1).

The debuild command executes the lintian command to make a static check after building the Debian package. The lintian command can be customized with the following in the `~/.devscripts` file:

    DEBUILD_DPKG_BUILDPACKAGE_OPTS="-us -uc -I -i"
    DEBUILD_LINTIAN_OPTS="-i -I --show-overrides"

Per exemple, netejar el codi i reconstruir el paquet des d'un compte d'usuari és tan simple com:

    $ debuild

Pots eliminar els fitxers generats en la compilació executant:

    $ debuild -- clean

## 6.4. El paquet `pbuilder`.

El paquet `pbuilder` és molt útil per aconseguir un entorn net (chroot) on comprovar les dependències [66]. Això assegura una construcció neta des del codi per a la construcció automàtica en la distribució `sid` per a diferents arquitectures i evita errades serioses del tipus FTBFS (Petada en la construcció des de les fonts o «Fail to Build From Source»), que són sempre de tipus RC (errades critiques per a la publicació o «release critical») [67].

És possible personalitzar el funcionament del paquet `pbuilder` en els següents aspectes:

- permet que el teu usuari tengui permís d'escriptura en el directori `/var/cache/pbuilder/result`.

- genera un directori, p. ex. ``/var/cache/pbuilder/hooks``, amb permís d'escriptura per al teu usuari. En aquest directori posaràs els guions «hook».

- Estableix els fitxers `~/.pbuilderrc` o `/etc/pbuilderrc` amb el següent contingut:

      AUTO_DEBSIGN=${AUTO_DEBSIGN:-no}
      HOOKDIR=/var/cache/pbuilder/hooks

Ara pots inicialitzar el sistema local `pbuilder` chroot per primera vegada executant:

    $ sudo pbuilder create

Si treballes amb un paquet font complet, executa les següents ordres en el directori on tenguis els fitxers ``nom_del_paquet`.orig.tar.gz`, ``nom_del_paquet`.debian.tar.gz` i ``nom_del_paquet`.dsc` per actualitzar el sistema local `pbuilder` chroot i, a continuació, compilar el paquet binari:

    $ sudo pbuilder --update
    $ sudo pbuilder --build nom_del_paquet.dsc

En acabar la compilació, el paquet compilat estarà en el directori `/var/cache/pbuilder/result/` i tu en seràs el propietari.

La signatura GPG dels arxius `.dsc` i `.changes` es poden generar de la següent manera:

    $ cd /var/cache/pbuilder/result/
    $ debsign nom_del_paquet_versió_arquitectura.changes

Si en lloc d'iniciar la construcció del paquet a partir d'un paquet ja construït, disposes d'un directori amb les fonts originals actualitzades, hauràs d'executar les següents ordres des del directori de les fonts originals (on hi haurà el directori `debian` amb el seu contingut):

    $ sudo pbuilder --update
    $ pdebuild

Pots «connectar-te» a l'entorn chroot executant l'ordre `pbuilder --login --save-after-login` i configurar-lo per adaptar-lo a les teves necessitats. Aquest entorn pot desar-se sortint del «shell» amb `^D` (Control-D).

La darrera versió de l'ordre lintian pot executar-se automàticament en l'entorn `chroot` fent servir el guió «hook» disponible a ``/var/cache/pbuilder/hooks`/B90lintian` i configurat de la següent manera [68]:

    #!/bin/sh
    set -e
    install_packages() {
            apt-get -y --allow-downgrades install "$@"
            }
    install_packages lintian
    echo "+++ lintian output +++"
    su -c "lintian -i -I --show-overrides /tmp/buildd/*.changes" - pbuilder
    # use this version if you don't want lintian to fail the build
    #su -c "lintian -i -I --show-overrides /tmp/buildd/*.changes; :" - pbuilder
    echo "+++ end of lintian output +++"

Has de tenir un entorn `sid` actualitzat per construir correctament paquets per a `sid`. En realitat, la versió `sid` pot tenir errades que no fan recomanable la migració del teu sistema en aquesta versió. El paquet `pbuilder` t'ajuda a fer front en aquesta situació.

You may need to update your `stable` packages after their release for `stable-proposed-updates`, `stable/updates`, etc. [69] For such occasions, the fact that you may be running a `sid` system is not a good enough excuse for failing to update them promptly. The `pbuilder` package can help you to access environments of almost any Debian derivative distribution of the same architecture.

Consulta http://www.netfort.gr.jp/~dancer/software/pbuilder.html, pdebuild(1), pbuilderrc(5), i pbuilder(8).

## 6.5. git-buildpackage command and similar

Si l'autor original fa servir un sistema de gestió de versions per al codi (VCS) [70] pots considerar fer-ho servir. Així facilites la coordinació i la selecció dels pegats per a les fonts. Debian disposa de diversos paquets de guions especialitzats en cada tipus de VCS:

- `git-buildpackage`: conjunt per a la compilació de paquets en repositoris «Git».

- `svn-buildpackage`: programes d'ajuda per al manteniment de paquets Debian amb «Subversion».

- `cvs-buildpackage`: conjunt de paquets de guions Debian per a estructures de directoris CVS.

L'ús de `git-buildpackage` està esdevenint bastant popular entre els desenvolupadors Debian per la gestió dels paquets Debian amb el servidor «Git» a alioth.debian.org. [71] Aquest paquet ofereix moltes ordres per automatitzar el manteniment dels paquets:

- gbp-import-dsc(1): import a previous Debian package to a Git repository.

- gbp-import-orig(1): import a new upstream tar to a Git repository.

- gbp-dch(1): generate the Debian changelog from Git commit messages.

- git-buildpackage(1): construeix els paquets Debian des del repositori «Git».

- git-pbuilder(1): construeix els paquets Debian des del repository «Git» fent servir pbuilder/cowbuilder.

Aquestes ordres fan servir 3 branques per gestionar el procés d'empaquetat:

- `main` pels directoris de fonts del paquet Debian.

- `upstream` pels directoris de les fonts de l'autor.

- `pristine-tar` pel fitxer comprimit «.tar» de l'autor generat per l'opció `--pristine-tar`.[72]

Pots configurar `git-buildpackage` amb `~/.gbp.conf`. Consulta gbp.conf(5). [73]

## 6.6. Reconstrucció ràpida.

Amb un paquet gran, pot ésser que no vulguis re-compilar des de l'inici cada vegada que fas algun canvi en el fitxer `debian/rules`. Per fer proves, pots construir un arxiu `.deb` sense re-compilar les fonts executant [74]:

    $ fakeroot debian/rules binary

O simplement pots comprovar si el paquet se compila amb:

    $ fakeroot debian/rules build

Un cop has acabat la posada a punt, caldrà reconstruir el paquet amb el procediment explicat anteriorment. No podràs enviar al repositori els fitxers `.deb` construïts d'aquesta manera.

## 6.7. Jerarquia d'ordres

A continuació teniu un resum ràpid de la jerarquia de les ordres de construcció de paquets. Hi ha diversos procediments per fer el mateix.

- `debian/rules` = guió del responsable del paquet per a la compilació

- dpkg-buildpackage = nucli de l'eina de compilació de paquets

- debuild = dpkg-buildpackage + lintian (compilació en un entorn amb les variables controlades)

- pbuilder = nucli de l'entorn «chroot» de Debian

- pdebuild = pbuilder + dpkg-buildpackage (compilació en l'entorn «chroot»)

- cowbuilder = execució accelerada de pbuilder

- git-pbuilder = sintaxis fàcil de fer servir de l'ordre pdebuild (la fa servir gbp buildpackge)

- gbp = gestiona els fitxers Debian en un repositori «git»

- gbp buildpackge = pbuilder + dpkg-buildpackage + gbp

Tot i que fer servir ordres d'alt nivell com a gbp buildpackge i pbuilder assegura un entorn de compilació de paquets perfecte, és important entendre com funcionen les ordres de baix nivell com les executades per `debian/rules` i dpkg-buildpackage en aquest entorn.

[62] Aquesta clau GPG ha de ser signada per un desenvolupador de Debian per connectar-se a la web de confiança i cal registrar-la a l'anell de claus de Debian. Això permet que els paquets siguin acceptats a l'arxiu de Debian. Consulta Creating a new GPG key i Debian Wiki on Keysigning.

[63] Pots evitar l'aplicació automàtica dels pegats per quilt en els paquets amb el format `3.0 (quilt)` al final de l'extracció amb l'opció `--skip-patches`. També pots optar per desfer les modificacions, una vegada acabada l'extracció, executant `dquilt pop -a`.

[64] El funcionament del sistema actual de compilació automàtica és més complicat del que s'explica en aquest document. Molts dels detalls del seu funcionament no són objectiu d'aquest document.

[65] A diferència a com funciona el paquet `pbuilder` (que s'explicarà més endavant), l'entorn chroot del paquet `sbuild` fet servir pel sistema automàtic no té una instal·lació mínima de paquets del sistema i pot deixar molts de paquets instal·lats.

[66] Com que el paquet `pbuilder` està en evolució, comprova la configuració actual consultant la documentació.

[67] Consulta http://buildd.debian.org/ per a més informació sobre el sistema de construcció automatitzada de paquets Debian.

[68] Se suposa que la variable d'entorn `HOOKDIR=/var/cache/pbuilder/hooks` ja està configurada. Tens exemples a `/usr/share/doc/pbuilder/examples`.

[69] Hi ha restriccions per a aquestes actualitzacions del teu paquet per a la versió `stable`.

[70] Consulta Version control systems.

[71] Debian wiki Alioth documenta com fer servir el servei alioth.debian.org.

[72] The `--pristine-tar` option invokes the pristine-tar command, which can regenerate an exact copy of a pristine upstream tarball using only a small binary delta file and the contents of the tarball that are typically kept in an `upstream` branch in the VCS.

[73] Aquí tens alguns recursos web disponibles per al públic expert.

- Construcció de paquets Debian amb git-buildpackage (`/usr/share/doc/git-buildpackage/manual-html/gbp.html`)

- Paquets Debian amb «git»

- Fent servir «Git» en la construcció de paquets Debian

- «git-dpm»: paquets Debian amb el gestor «Git»

[74] Environment variables that are normally configured to proper values are not set by this method. Never create real packages to be uploaded using this quick method.

Capítol 5. Altres fitxers del directori `debian`. |  | Capítol 7. Com comprovar el teu paquet per trobar errors.