Capítol 4. Fitxers necessaris en el directori `debian`.

# Capítol 4. Fitxers necessaris en el directori `debian`.

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 tens un nou directori en el directori principal del programa («gentoo-0.9.12»), amb el nom `debian`. Hi ha alguns fitxers en aquest directori que caldrà editar per adaptar-los. Els fitxers més importants són `control`, `changelog`, `copyright` i `rules`, tots ells s'han d'incloure a tots els paquets [27].

## 4.1. El fitxer `control`.

La informació d'aquest fitxer es fa servir per dpkg, dselect, apt-get, apt-cache, aptitude i altres eines de gestió de paquets. El seu contingut està explicat a «Debian Policy Manual, 5 'Control files and their fields'».

Aquest és el contingut del fitxer `control` generat per dh_make:

     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>

(S'han afegit els números de les línies).

Lines 1–7 are the control information for the source package. Lines 9–13 are the control information for the binary package.

La línia 1 és el nom del paquet font.

La línia 2 és la secció de la distribució a la qual s'assignarà el paquet.

Debian està dividit en seccions: `main` (principal, per als programes de codi lliure), `non-free` (propietaris, per als programes propietaris) i `contrib` (per als programes que depenen de programari propietari). A cada secció hi ha subdivisions segons el tipus de programari. Tenim `admin` per a programes que es fan servir per l'administració del sistema (habitualment només per l'usuari «root»), `base` per a les eines bàsiques del sistema, `devel` per al programari de desenvolupament, `doc` per a la documentació, `libs` per a les biblioteques, `mail` per a lectors de correu i dimonis de correu electrònic, `net` per a programes i dimonis de xarxa, `x11` per a programes específics de X11 i molts d'altres [28].

Anem a canviar-ho per x11 (el prefix `main/` és implícit, pel que podem ometre'l).

La línia 3 descriu la importància que pot tenir per a l'usuari (o el sistema) la instal·lació del paquet [29].

- La prioritat `optional` es fa servir per a paquets nous que no tenen conflictes amb altres paquets amb prioritat `required`, `important` o `standard`.

«Section» i «Priority» es fan servir per les interfícies com aptitude quan ordenen els paquets i seleccionen els predeterminats. Una vegada el teu paquet s'afegeixi a Debian, el contingut d'aquests camps pot ésser canviat per les persones responsables del repositori, que t'informaran per correu electrònic.

Com és un paquet de prioritat normal i no té conflictes amb cap altre paquet, deixarem la prioritat a `optional` (opcional).

A la línia 4 hi ha el nom i l'adreça electrònica del desenvolupador. Assegura't que l'adreça electrònica és vàlida per al camp `A` : el sistema de seguiment d'errades («Bug Tracking System») la farà servir per enviar-te els missatges de les errades del paquet. No facis servir «», el signe «&» i parèntesi.

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.

- A tots els paquets construïts amb l'ordre dh en el fitxer `debian/rules`, caldrà posar `debhelper (>=9)` en el camp `Build-Depends` per seguir les normes Debian respecte a l'objectiu `clean`.

- Source packages which have binary packages with `Architecture: any` are rebuilt by the autobuilder. Since this autobuilder procedure installs only the packages listed in the `Build-Depends` field before running `debian/rules build` (see Secció 6.2, ««Autobuilder».»), the `Build-Depends` field needs to list practically all the required packages, and `Build-Depends-Indep` is rarely used.

- Els paquets de fonts amb binaris del tipus `Architecture: all`, el camp `Build-Depends-Indep` inclourà tots els paquets necessaris amb excepció dels llistats en el camp `Build-Depends` per tal de seguir els requeriments de les normes Debian respecte a l'objectiu `clean`.

Si tens dubtes, fes servir el camp `Build-Depends` [31].

Si vols saber quins paquets són necessaris per compilar el teu programa, executa l'ordre (si el programa fa servir «configure» per compilar-se):

    $ dpkg-depcheck -d ./configure

Si vols saber les dependències de compilació d'un paquet `/usr/bin/nom_del_paquet`, executa:

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

and for each library listed (e.g., libfoo.so.6), execute

    $ dpkg -S libfoo.so.6

Cal fer servir la versió `-dev` de cada un dels paquets llistats en el camp `Build-Depends`. Si fas servir el programa ldd per saber les dependències, també t'informarà de les dependències de les biblioteques indirectes, la qual cosa pot fer que la llista sigui massa llarga.

`gentoo` fa servir `xlibs-dev`, `libgtk1.2-dev` i `libglib1.2-dev` en la compilació, així que caldrà afegir-ho tot a continuació de `debhelper`.

La línia 6 és la versió dels estàndards definits en les normes Debian i que s'han seguit en la construcció del paquet, és a dir, la versió del manual de normes que has seguit per empaquetar (consulta «Debian Policy Manual»).

A la línia 7 està l'adreça URL del programa.

La línia 9 és el nom del paquet binari. Normalment és el mateix que el paquet del codi original, tot i què no és imprescindible que sigui així.

A la línia 10 es descriu les arquitectures en les quals pot ésser compilat el paquet. Aquest valor és un dels següents depenent del tipus de paquet binari [32]:

- `Architecture: any`

  - El paquet binari generat és depenent de l'arquitectura, generalment quan es tracta d'un programa escrit en un llenguatge compilat.

- `Architecture: all`

  - El paquet binari generat és independent de l'arquitectura, generalment quan es tracta d'arxius de text, imatges o guions escrits en un llenguatge interpretat.

Eliminarem la línia 10 degut a que el programa està escrit en C. dpkg-gencontrol(1) omplirà el valor apropiat d'arquitectura per a cada màquina en què és possible compilar el paquet de fonts.

Si el teu paquet és independent de l'arquitectura (serà el cas d'un document o d'un guió escrit en Perl), canvia el valor a `all` i consulta més endavant Secció 4.4, «El fitxer `rules`.» per saber com fer servir la regla `binary-indep` en lloc de `binary-arch` per a la construcció del paquet.

La línia 11 mostra una de les més poderoses possibilitats del sistema de paquets de Debian. És possible relacionar els paquets entre ells. A més de `Depends` (depèn de) altres camps de relació són `Recommends` (recomana), `Suggests` (suggereix), `Pre-Depends` (pre-depèn de), `Breaks` (trenca a), `Conflicts` (entre en conflicte amb), `Provides` (proveeix), `Replaces` (reemplaça a).

Les eines de gestió de paquets tracten de la mateixa manera les relacions entre els paquets; els casos en què no és així s'explicaran en el seu moment (consulta dpkg(8), dselect(8), apt(8), aptitude(1), etc.).

Heus aquí una descripció simplificada de les relacions entre paquets [33]:

- `Depends`

  El programa no s'instal·larà fins què s'instal·lin els paquets dels quals depèn. Fes servir aquesta opció si el teu programa no funciona (o es trenca fàcilment) sense un paquet determinat.

- `Recommends`

  Aquesta opció és per a paquets que no són imprescindibles per al funcionament del programa però que es fan servir juntament amb ell. Quan els usuaris instal·lin el teu paquet, totes les interfícies d'instal·lació aconsellaran la instal·lació dels paquets recomanats. aptitude i apt-get instal·len els paquets recomanats (però l'usuari pot decidir no fer-ho). dpkg ignora el contingut d'aquest camp.

- `Suggests`

  Fes servir aquesta opció per a paquets que funcionaran bé amb el teu programa però que no són en absolut necessaris.. Quan l'usuari instal·li el teu programa, probablement no se li demanarà que s'instal·lin els paquets suggerits. És possible configurar aptitude per a què instal·li els paquets suggerits (no és l'opció per defecte). dpkg i apt-get ignoren aquestes dependències. Fes servir aquesta opció per a paquets que funcionaran bé amb el teu programa però que no són en absolut necessaris.

- `Pre-Depends`

  Aquesta opció és més radical que `Depends`. El paquet no s'instal·larà fins que els paquets dels quals pre-depèn estiguin instal·lats i correctament configurats. Fes servir aquesta opció poques vegades i només després d'haver-ho discutit a la llista de distribució debian-devel@lists.debian.org. Més clarament: no facis servir aquesta opció :-).

- `Conflicts`

  El paquet no s'instal·larà fins què tots el paquets amb els quals entre en conflicte siguin eliminats. Fes servir aquesta opció si el teu programa no funcionarà amb absolut (o fallarà fàcilment) si un paquet en concret no està instal·lat.

- `Breaks`

  Si el paquet s'instal·la, tots els paquets de la llista es trencaran. Normalment, els paquets inclosos en la llista `Breaks` tenen una clàusula de versió anterior. La solució és fe servir eines de gestió de paquets més sofisticades per actualitzar els paquets de la llista.

- `Provides`

  For some types of packages where there are multiple alternatives, virtual names have been defined. You can get the full list in the virtual-package-names-list.txt.gz file. Use this if your program provides a function of an existing virtual package.

- `Replaces`

  Fes servir aquesta opció només si el teu programa substitueix fitxers d'un altra paquet o el paquet complet (generalment es fa servir aquesta opció conjuntament amb `Conflicts`). S'eliminaran els fitxers dels paquets indicats abans d'instal·lar el teu.

Tots aquests camps tenen una sintaxi uniforme: es tracta d'una llista de noms de paquets separats per comes. Aquests noms de paquets també poden ésser llistes de paquets alternatius, separats amb una barra vertical «`|`» (símbol de tub).

Els camps poden restringir la seva aplicació a versions determinades del paquet llistat. Aquestes versions s'enumeren entre parèntesi després de cada nom de paquet individual, i ha de contenir una relació de la següent llista seguit pel nombre de versió. Les relacions possibles són: `<<`, `<=`, `=`, `>=` i `>>` per a estrictament anterior, anterior o igual, exactament igual, posterior o igual i estrictament posterior, respectivament. Per exemple:

    Depends: foo (>= 1.2), libbar1 (= 1.3.4)
    Conflicts: baz
    Recommends: libbaz4 (>> 4.0.7)
    Suggests: quux
    Replaces: quux (<< 5), quux-foo (<= 7.6)

L'última funcionalitat que necessites conèixer és `${shlibs:Depends}`, `${perl:Depends}`, `${misc:Depends}`, etc.

dh_shlibdeps(1) determina les dependències de biblioteques compartides pels paquets binaris. Genera una llista d'executables ELF i biblioteques compartides per a cada paquet binari. Aquesta llista es farà sevir per substituir `${shlibs:Depends}`.

dh_perl(1) comprova les dependències Perl. Genera una llista de dependències de `perl` o `perlapi` per a cada paquet binari. Aquesta llista es fa servir per reemplaçar `${perl:Depends}`.

Algunes ordres de `debhelper` determinen les dependències dels paquets llistats anteriorment. Les ordres generen una llista dels paquets necessaris per a cada un dels paquets binaris. La llista d'aquests paquets reemplaçaran a `${misc:Depends}`.

dh_gencontrol(1) genera l'arxiu `DEBIAN/control` per a cada paquet binari substituint `${shlibs:Depends}`, `${perl:Depends}`, `${misc:Depends}`, etc.

La línia `Depends` pot quedar així com està però afegirem una línia `Suggests: file`, degut a què el paquet `gentoo` fa servir algunes funcions del paquet `file`.

La línia 9 conté la URL del programa. S'assumeix que és http://www.obsession.se/gentoo/.

La línia 12 és una descripció curta del programa. La major part dels monitors dels usuaris són de 80 columnes d'amplada (els terminals, és clar!) per la qual cosa la descripció no hauria de tenir més de 60 caràcters. Canviaré la descripció per a `fully GUI-configurable, two-pane X file manager`. («Interfície gràfica d'usuari GTK+ de gestió de fitxers completament configurable»).

La línia 13 és per fer una descripció més llarga del paquet. Cal que sigui almenys d'un paràgraf amb detalls sobre el paquet. Cada línia començarà amb un espai buit. No hi pot haver línies en blanc, però es pot simular amb un `.` (punt) a la segona columna. Tampoc hi pot haver més d'una línia en blanc al final de la descripció completa [34].

Afegirem els camps `Vcs-*` per a documentar la localització del sistema de control de versions (VCS) entre les línies 6 i 7 [35]. Se suposa que el paquet `gentoo` està allotjat en el servei «Alioth Git» de Debian a `git://git.debian.org/git/collab-maint/gentoo.git`.

Finalment, el fitxer `control` actualitzat quedarà així:

     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.

(S'han afegit els números de les línies).

## 4.2. El fitxer `copyright`.

Aquest arxiu conté la informació de la llicència i drets d'autor de les fonts originals del paquet. Debian Policy Manual, 12.5 "Copyright information" concreta el seu contingut i DEP-5: Machine-parseable `debian/copyright` proporciona directrius per al seu format.

dh_make proporciona una plantilla per a l'arxiu `copyright`. Amb l'opció `--copyright gpl2` s'aconsegueix la plantilla per al paquet `gentoo` amb la llicència 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.

Resumint, el fitxer `copyright` del paquet `gentoo` hauria de ser més o menys com el següent exemple:

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

(S'han afegit els números de les línies).

Consulta el text «COM» redactat pel «ftpmasters» i enviat a «debian-devel-announce»: http://lists.debian.org/debian-devel-announce/2006/03/msg00023.html.

## 4.3. El fitxer `changelog`.

Aquest és un arxiu imprescindible amb un format especial descrit a les normes Debian, Debian Policy Manual, 4.4 "debian/changelog". El seu especial format és degut a què dpkg i d'altres programes el fan servir per obtenir informació de la versió, revisió, distribució i urgència del paquet.

També és important aquest arxiu: facilita la documentació dels canvis fets en la construcció del paquet. El fitxer informarà als usuaris que descarreguin el paquet sobre els problemes que pugui tenir el paquet i que ells hagin de saber. El fitxer es conserva com `/usr/share/doc/gentoo/changelog.Debian.gz` en el paquet.

dh_make construeix un arxiu predeterminat amb el següent text:

    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

(S'han afegit els números de les línies).

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

Aquest serà el contingut del fitxer:

    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

(S'han afegit els números de les línies).

Quan estiguis satisfet dels canvis i els hagis documentat en el fitxer `changelog`, ja pots canviar el valor de la distribució de `UNRELEASED` pel nom de la distribució de destinació `unstable` (o bé per `experimental`). [36]

A la secció Capítol 8, Actualitzar el paquet. s'explicaran alguns aspectes més de l'actualització del fitxer `changelog`.

## 4.4. El fitxer `rules`.

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.

### 4.4.1. Objectius del fitxer `rules`.

Cada arxiu `rules`, igual que els arxius `Makefile`, consta de diversos objectius i les seves regles [37]. Cada regla comença amb la declaració dels objectius a la primera columna. Les següents línies comencen amb una tabulació (codi ASCII 9) i les seves regles. Les línies buides i les començades amb `#` es tracten com a comentaris i s'ignoren [38].

A rule that you want to execute is invoked by its target name as a command line argument. For example, `debian/rules `build`` and `fakeroot make -f debian/rules `binary`` execute rules for ``build`` and ``binary`` targets, respectively.

A continuació tens una explicació simplificada dels objectius:

- `clean` (obligatori): elimina tots els fitxers generats, compilats o innecessaris de l'estructura de directoris de les fonts.

- `build` (obligatori): construeix els fitxers executables o els documents amb format a partir dels fitxers de les fonts.

- objectiu `build-arch` (obligatori): per compilar les fonts en programes compilats dependents de l'arquitectura en l'arbre de directoris de compilació.

- objectiu `build-indep` (obligatori) : per compilar les fonts en documents amb format independents de l'arquitectura en l'arbre de directoris de compilació.

- `install` (opcional): fa la instal·lació en l'estructura de directoris temporal en el directori `debian` dels fitxers que constitueixen els paquets binaris. Si hi ha un objectiu `binary*`, dependrà d'aquest.

- `binary` (obligatori): per a la construcció de cada un dels paquets binaris (combinat amb els objectius `binary-arch` i `binary-indep`) [39].

- `binary-arch` (obligatori): per a la construcció de paquets dependents de l'arquitectura (els que tenen el camp `Architecture: any` en el fitxer «control») [40].

- `binary-indep` (obligatori): per a la construcció de paquets independents de l'arquitectura (`Architecture: all` en el fitxer «control») [41].

- `get-orig-source` (opcional): per determinar la versió més recent de les fonts originals des del magatzem de l'autor.

Probablement l'exposició no és gens clara, però tot quedarà més clar després de veure el fitxer `rules` que dh_make construeix com a plantilla.

### 4.4.2. Fitxer `rules` predeterminat.

La nova versió de dh_make genera un arxiu `rules` molt simple però poderós que fa servir l'ordre dh:

     1 #!/usr/bin/make -f
     2 # See debhelper(7) (uncomment to enable)
     3 # output every command that modifies files on the build system.
     4 #DH_VERBOSE = 1
     5
     6 # see FEATURE AREAS in dpkg-buildflags(1)
     7 #export DEB_BUILD_MAINT_OPTIONS = hardening=+all
     8
     9 # see ENVIRONMENT in dpkg-buildflags(1)
    10 # package maintainers to append CFLAGS
    11 #export DEB_CFLAGS_MAINT_APPEND  = -Wall -pedantic
    12 # package maintainers to append LDFLAGS
    13 #export DEB_LDFLAGS_MAINT_APPEND = -Wl,--as-needed
    14
    15
    16 %:
    17         dh $@

(He afegit els números de les línies i simplificat els comentaris. En el fitxer `debian/rules` els espais inicials de les línies són tabulacions).

Probablement estàs familiaritzat amb línies com la primera per a guions escrits en shell o Perl. Aquesta línia indica que el fitxer s'executa amb `/usr/bin/make`.

Cal eliminar la marca de comentari a la línia 4 per assignar el valor 1 a la variable `DH_VERBOSE`. En aquest cas, l'ordre dh escriurà les ordres dh_* en el terminal així com siguin executades per dh. Pots afegir la línia `export DH_OPTIONS=-v` aquí. Això farà que cada ordre dh_* escrigui la sortida d'allò que fa. Això t'ajudarà a entendre com funciona el fitxer `rules` i a solucionar errades. La nova ordre dh és part fonamental de les eines `debhelper` i no t'amaguen res.

Tota la feina del fitxer la fan les línies 16 i 17 executant una regla implícita fent servir la regla patró. El símbol de percentatge substitueix «qualsevol objectiu» per a continuació executar únicament dh amb el nom de l'objectiu (com a opció) [42]. L'ordre dh és un guió que executa les seqüències necessàries d'ordres dh_* segons els seus paràmetres com es descriu a continuació [43]:

- `debian/rules clean` executa `dh clean`, que al seu torn executa el següent:

      dh_testdir
      dh_auto_clean
      dh_clean

- `debian/rules build` runs `dh build`, which in turn runs the following:

      dh_testdir
      dh_auto_configure
      dh_auto_build
      dh_auto_test

- `fakeroot debian/rules binary` runs `fakeroot dh binary`, which in turn runs the following[44]:

      dh_testroot
      dh_prep
      dh_installdirs
      dh_auto_install
      dh_install
      dh_installdocs
      dh_installchangelogs
      dh_installexamples
      dh_installman
      dh_installcatalogs
      dh_installcron
      dh_installdebconf
      dh_installemacsen
      dh_installifupdown
      dh_installinfo
      dh_installinit
      dh_installmenu
      dh_installmime
      dh_installmodules
      dh_installlogcheck
      dh_installlogrotate
      dh_installpam
      dh_installppp
      dh_installudev
      dh_installwm
      dh_installxfonts
      dh_bugfiles
      dh_lintian
      dh_gconf
      dh_icons
      dh_perl
      dh_usrlocal
      dh_link
      dh_compress
      dh_fixperms
      dh_strip
      dh_makeshlibs
      dh_shlibdeps
      dh_installdeb
      dh_gencontrol
      dh_md5sums
      dh_builddeb

- `fakeroot debian/rules binary-arch` runs `fakeroot dh binary-arch`, which in turn runs the same sequence as `fakeroot dh binary` but with the `-a` option appended for each command.

- `fakeroot debian/rules binary-indep` runs `fakeroot dh binary-indep`, which in turn runs almost the same sequence as `fakeroot dh binary` but excluding dh_strip, dh_makeshlibs, and dh_shlibdeps with the `-i` option appended for each remaining command.

La funció de les ordres dh_* pot deduir-se del seu nom [45]. A continuació es resumeix la funció de les ordres més importants per al cas de compilació basada en un arxiu `Makefile` [46]:

- dh_auto_clean executa el següent si hi ha un arxiu `Makefile` amb l'objectiu `distclean` [47].

      make distclean

- dh_auto_configure executa el següent si es fa servir el fitxer `./configure` (els arguments s'ha abreviat per facilitar la lectura):

      ./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var ...

- dh_auto_build executa el següent per executar el primer objectiu del fitxer `Makefile` (si es fa servir aquest arxiu).

      make

- dh_auto_test executa el següent si existeix l'objectiu `test` en el fitxer `Makefile` [48].

      make test

- dh_auto_install executa el següent si existeix l'objectiu `install` en el fitxer `Makefile` (s'ha truncat la línia per facilitar la lectura):

      make install \
        DESTDIR=/directori/del/paquet_versió-revisió/debian/nom_del_paquet

Els objectius que cal executar amb l'ordre fakeroot contenen dh_testroot. Si no fas servir l'ordre «fakeroot» per simular l'execució per l'usuari «root», es produirà una errada que aturarà l'execució.

És important tenir present que el fitxer `rules` construït per dh_make només és un exemple. Serà útil per a la majoria dels paquets simples, però no deixis de fer les adaptacions necessàries.

Malgrat que `install` no és un objectiu obligatori, està acceptat. `fakeroot dh install` es comporta com `fakeroot dh binary` però s'atura després de dh_fixperms.

### 4.4.3. Personalització del fitxer `rules`.

Pots fer molts canvis per adaptar el fitxer `rules` construït per l'ordre dh.

L'ordre `dh $@` permet les següents adaptacions [49]:

- Afegir funcionalitat per a l'ordre dh_python2 (la millor opció per a Python) [50].

  - Afegeix el paquet `python` en el camp `Build-Depends`.

  - Fes servir `dh $@ --with python2` en el seu lloc.

  - Així es gestiona el mòdul Python fent servir el entorn («framework») de `python`.

- Afegir funcionalitat per a l'ordre dh_pysupport (obsolet).

  - Afegeix el paquet `python-support` en el camp `Build-Depends`.

  - Fes servir `dh $@ --with pysupport` en el seu lloc.

  - Així es gestiona el mòdul Python fent servir el entorn («framework») de `python-support`.

- Afegir funcionalitat per a l'ordre dh_pycentral (obsolet).

  - Afegeix el paquet `python-central` en el camp `Build-Depends`.

  - Fes servir `dh $@ --with python-central` en el seu lloc.

  - També es desactiva l'ordre dh_pysupport.

  - I es gestiona el mòdul Python fent servir l'entorn («framework») de `python-central`.

- Afegir funcionalitat per a l'ordre dh_installtex.

  - Afegeix el paquet `tex-common` en el camp `Build-Depends`.

  - Fes servir `dh $@ --with tex` en el seu lloc.

  - Així es registren els tipus de lletra «Type 1», els patrons per a la separació de paraules («hyphenation patterns») o els formats TeX.

- Afegir funcionalitat per a les ordres dh_quilt_patch i dh_quilt_unpatch.

  - Afegeix el paquet `quilt` en el camp `Build-Depends`.

  - Fes servir `dh $@ --with quilt` en el seu lloc.

  - Així s'apliquen o es desfan, en els fitxers de les fonts originals, les modificacions dels fitxers del directori `debian/patches` en els paquets construïts amb el format `1.0`.

  - Aquesta adaptació no és necessària per als paquets construïts amb el format `3.0 (quilt)`.

- Afegir funcionalitat per a l'ordre dh_dkms.

  - Afegeix el paquet `dkms` en el camp `Build-Depends`.

  - Fes servir `dh $@ --with dkms` en el seu lloc.

  - Així es controla correctament l'ús de DKMS en la construcció de paquets del nucli.

- Afegir funcionalitat per a les ordres dh_autotools-dev_updateconfig i dh_autotools-dev_restoreconfig.

  - Afegeix el paquet `autotools-dev` en el camp `Build-Depends`.

  - Fes servir `dh $@ --with autotools-dev` en el seu lloc.

  - Així s'actualitza i restaura `config.sub` i `config.guess`.

- Afegir funcionalitat per a les ordres dh_autoreconf i dh_autoreconf_clean.

  - Afegeix el paquet `dh-autoreconf` en el camp `Build-Depends`.

  - Fes servir `h $@ --with autoreconf` en el seu lloc.

  - Així s'actualitzen els fitxers del sistema de compilació GNU i els restaura després de la compilació.

- Afegir funcionalitat per a l'ordre dh_girepository.

  - Afegeix el paquet `gobject-introspection` en el camp `Build-Depends`.

  - Fes servir `dh $@ --with gir` en el seu lloc.

  - Això computa les dependències dels paquets d'enviament de dades d'introspecció de «GObject» i genera la substitució de la variable `${gir:Depends}` per les dependències del paquet.

- Afegir funcionalitat d'autocompletar a bash.

  - Afegeix el paquet `bash-completion` en el camp `Build-Depends`.

  - Fes servir `dh $@ --with bash-completion` en el seu lloc.

  - Així s'instal·la la funció d'autocompletar de bash fent servir l'arxiu de configuració de `debian/`nom_del_paquet`.bash-completion`.

Moltes de les ordres dh_* executades per la nova ordre dh es poden personalitzar amb fitxers de configuració ubicats en el directori `debian`. Consulta Capítol 5, Altres fitxers del directori `debian`. i els manuals (les «manpage») de cada ordre.

Algunes ordres dh_* invocades per la nova ordre dh poden necessitar l'addició d'arguments o l'execució d'ordres addicionals. Per a aquests casos, hauràs d'afegir l'objectiu `override_dh_`nom_ordre`` en el fitxer `rules` per a l'ordre dh_`nom_ordre` que cal canviar. Es tracta de execute'm a mi en el seu lloc [51].

Les ordres dh_auto_* fan més coses que les explicades en aquesta explicació simplificada. L'ús d'ordres equivalents més senzilles en el lloc d'aquestes en els objectius `override_dh_*` (amb l'excepció de l'objectiu `override_dh_auto_clean`) no és una bona idea ja que pot eliminar funcions intel·ligents de `debhelper`.

Si les dades de configuració del paquet `gentoo` es desen en el directori `/etc/gentoo` en lloc del directori habitual `/etc`, cal anular l'execució de l'argument predeterminat `--sysconfig=/etc` de l'ordre dh_auto_configure per ./configure amb:

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

The arguments given after `--` are appended to the default arguments of the auto-executed program to override them. Using the dh_auto_configure command is better than directly invoking the ./configure command here since it will only override the `--sysconfig` argument and retain any other, benign arguments to the ./configure command.

Si el `Makefile` de les fonts de `gentoo` requereix l'especificació de l'objectiu `build` per a la compilació [52], pots afegir un objectiu `override_dh_auto_build` per tal d'anul·lar-lo.

    override_dh_auto_build:
            dh_auto_build -- build

D'aquesta forma es garanteix l'execució de `$(MAKE)` amb tots els arguments predeterminats per l'ordre dh_auto_build i de l'argument `build`.

Si el fitxer `Makefile` de les fonts de `gentoo` requereix l'especificació de l'objectiu `packageclean` (per fer neteja després de la compilació), en lloc dels objectius `distclean` o `clean` a l'arxiu `Makefile` pots afegir un objectiu `override_dh_auto_clean` per habilitar l'ordre.

    override_dh_auto_clean:
            $(MAKE) packageclean

Si el fitxer `Makefile` de les fonts de `gentoo` té un objectiu `test` i desitges que no s'executi en la construcció del paquet, pots fer servir l'objectiu `override_dh_auto_test` sense ordres per tal de que no es faci res.

    override_dh_auto_test:

Si el paquet `gentoo` inclou el poc freqüent arxiu de canvis de l'autor amb el nom `FIXES`, dh_installchangelogs no en farà la instal·lació (és l'opció predeterminada). L'ordre dh_installchangelogs requereix l'argument `FIXES` per tal d'instal·lar-lo [53].

    override_dh_installchangelogs:
            dh_installchangelogs FIXES

Si fas sevir el nou dh, la utilització explícita d'objectius com els llistats a Secció 4.4.1, «Objectius del fitxer `rules`.» (excepte `get-orig-source`) pot dificultar la correcta comprensió dels seus efectes. Si us plau, limita l'ús d'objectius explícits a objectius del tipus `override_dh_*` i de manera que siguin completament independents entre ells (sempre que sigui possible).

[27] En aquest capítol, es farà referència als arxius ubicats en el directori `debian` sense afegir el prefix `debian/` per a simplificar el text i sempre que no hi hagi possibilitat de confusió.

[28] Consulta Debian Policy Manual, 2.4 'Sections' and Llistat de seccions a `sid`.

[29] Consulta Manual de normes de Debian, 2.5 'Prioritat'.

[30] Consulta Debian Policy Manual, 7.7 'Relationships between source and binary packages - Build-Depends, Build-Depends-Indep, Build-Conflicts, Build-Conflicts-Indep'.

[31] Aquesta situació una mica estranya és una característica ben documentada a la «Debian Policy Manual, Footnotes 55». En tot cas, això és degut al funcionament de dpkg-buildpackage, no pel fet de fer servir l'ordre dh en el fitxer `debian/rules`. Tot això també s'explica a «auto build system for Ubuntu».

[32] Consulta Debian Policy Manual, 5.6.8 "Architecture" per a més detalls.

[33] Consulta Debian Policy Manual, 7 "Declaring relationships between packages".

[34] Aquestes descripcions s'han d'escriure en anglès. De la traducció s'encarrega el The Debian Description Translation Project - DDTP.

[35] Consulta Developer's Reference, 6.2.5. "Version Control System location".

[36] Si fas servir l'ordre `dch -r` per fer efectiu aquest darrer canvi, assegura't que deses el fitxer `changelog` des del editor.

[37] You can start learning how to write a `Makefile` from Debian Reference, 12.2. "Make". The full documentation is available as http://www.gnu.org/software/make/manual/html_node/index.html or as the `make-doc` package in the `non-free` archive area.

[38] Debian Policy Manual, 4.9 "Main building script: debian/rules" explica els detalls.

[39] Aquest objectiu és utilitzat per `dpkg-buildpackage` com en Secció 6.1, «Reconstrucció completa.».

[40] Aquest objectiu és utilitzat per `dpkg-buildpackage -B` com en Secció 6.2, ««Autobuilder».».

[41] Aquest objectiu és utilitzat per `dpkg-buildpackage -A`.

[42] This uses the new `debhelper` v7+ features. Its design concepts are explained in Not Your Grandpa's Debhelper presented at DebConf9 by the `debhelper` upstream. Under `lenny`, dh_make created a much more complicated `rules` file with explicit rules and many dh_* scripts listed for each one, most of which are now unnecessary (and show the package's age). The new dh command is simpler and frees us from doing the routine work "manually". You still have full power to customize the process with `override_dh_*` targets. See Secció 4.4.3, «Personalització del fitxer `rules`.». It is based only on the `debhelper` package and does not obfuscate the package building process as the `cdbs` package tends to do.

[43] You can verify the actual sequences of dh_* programs invoked for a given ``target`` without really running them by invoking `dh `target` --no-act` or `debian/rules -- '`target` --no-act'`.

[44] El següent exemple assumeix que el teu fitxer `debian/compat` té un valor igual o major a 9 per tal d'evitar invocar qualsevol ordre «python» de suport automàticament.

[45] Per a una descripció més completa de la funció de cada guió dh_* i les seves opcions, consulta els manuals respectius així com la documentació de `debhelper`.

[46] These commands support other build environments, such as `setup.py`, which can be listed by executing `dh_auto_build --list` in a package source directory.

[47] Mira el primer objectiu disponible a l'arxiu `Makefile` com `distclean`, `realclean` o `clean` a l'arxiu `Makefile` i l'executa.

[48] En realitat executa el primer dels objectius `test` o `check` del fitxer `Makefile`.

[49] Si un paquet instal·la el fitxer `/usr/share/perl5/Debian/Debhelper/Sequence/`nom_arxiu`.pm` pots activar la funció adaptada amb `dh $@ --with `nom_arxiu``.

[50] És preferible fer servir l'ordre dh_python2 abans que l'ordre dh_pysupport o dh_pycentral. No facis servir l'ordre dh_python.

[51] En `lenny`, quan calia canviar un guió dh_* calia trobar la línia adequada en el fitxer `rules` i canviar-la. Ara és suficient afegir un objectiu.

[52] dh_auto_build sense arguments executarà el primer objectiu del fitxer `Makefile`.

[53] Els fitxers `debian/changelog` i `debian/NEWS` sempre s'instal·len automàticament. També es busca el fitxer de canvis de l'autor canviant el nom a minúscules i per la seva coincidència amb `changelog`, `changes`, `changelog.txt`, i `changes.txt`.

Capítol 3. Modificar les fonts originals. |  | Capítol 5. Altres fitxers del directori `debian`.