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

Sumari

4.1. El fitxer control.
4.2. El fitxer copyright.
4.3. El fitxer changelog.
4.4. El fitxer rules.
4.4.1. Objectius del fitxer rules.
4.4.2. Fitxer rules predeterminat.
4.4.3. Personalització del fitxer rules.

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

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: extra
 4 Maintainer: Josip Rodin <joy-mg@debian.org>
 5 Build-Depends: debhelper (>=9)
 6 Standards-Version: 3.9.4
 7 Homepage: <aquí l'URL de l'autor original  >
 8
 9 Package: gentoo
10 Architecture: any
11 Depends: ${shlibs:Depends}, ${misc:Depends}
12 Description: <descripció de fins a 60 caràcters>
13  <descripció llarga, cada línia amb un espai inicial.>

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

Les línies 1 a 7 tenen la informació de control per al paquet font. Les línies 9 a 13 tenen informació de control del paquet binari.

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.

  • La prioritat extra es fa servir per als nous paquets que tenen conflictes amb altres paquets que no tenguin la prioritat extra

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

A la línia 5 hi ha els paquets necessaris per a la construcció del teu paquet (en el camp Build-Depends). Hi pot haver una línia addicional amb el camp Build-Depends-Indep[30]. Alguns paquets com a gcc i make que són necessaris per a build-essential no és necessari posar-los (es consideren implícitament). Si el teu programa fa servir algun compilador que no sigui habitual o alguna altra eina per a la construcció del paquet, hauries d'afegir la línia «Build-Depends». Els noms dels paquets se separen amb comes: consulta l'explicació de les dependències binaries per saber més sobre la sintaxi d'aquest camp.

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

  • Els paquets de fonts que tenen paquets binaris amb el camp Architecture: any fan servir «autobuilder». El procediment «autobuilder» s'encarrega d'instal·lar els paquets llistats en el camp Build-Depends abans d'executar debian/rules build (consulta Secció 6.2, ««Autobuilder».»), el camp Build-Depends normalment llista tots els paquets necessaris i per això, el camp Build-Depends-indep es fa servir poc.

  • 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

i per a cada una de les biblioteques llistades per l'ordre anterior (a l'exemple es fa amb libfoo.so.6) executa:

$ 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

    Hi ha definits noms virtuals per a alguns tipus determinats de paquets que ofereixen múltiples alternatives per a la mateixa funció. Pots obtenir una llista completa a virtual-package-names-list.txt.gz. Fes servir aquesta opció si el teu programa ofereix les funcions d'un paquet virtual que ja existeixi.

  • 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 (>=9), xlibs-dev, libgtk1.2-dev, libglib1.2-dev
 6 Standards-Version: 3.9.4
 7 Vcs-Git: git://git.debian.org/git/collab-maint/gentoo.git
 8 Vcs-browser: http://git.debian.org/?p=collab-maint/gentoo.git
 9 Homepage: http://www.obsession.se/gentoo/
10
11 Package: gentoo
12 Architecture: any
13 Depends: ${shlibs:Depends}, ${misc:Depends}
14 Suggests: file
15 Description: fully GUI-configurable, two-pane X file manager
16  gentoo is a two-pane file manager for the X Window System. gentoo lets the
17  user do (almost) all of the configuration and customizing from within the
18  program itself. If you still prefer to hand-edit configuration files,
19  they're fairly easy to work with since they are written in an XML format.
20  .
21  gentoo features a fairly complex and powerful file identification system,
22  coupled to 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).

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.

Has de completar la informació sobre el lloc on es pot obtenir el codi font, les condicions dels drets d'autor i la llicència. Les llicències de codi lliure més comuns són GNU GPL-1, GNU GPL-2, GNU GPL-3, LGPL-2, LGPL-2.1, LGPL-3, GNU FDL-1.2, GNU FDL-1.3, Apache-2.0 o la «Artistic license» i fer referència al fitxer corresponent disponible a /usr/share/common-licenses/ en els sistemes Debian. En cas contrari, cal incloure el text complet de la llicència en el fitxer.

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

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

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

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=low
2
3   * Initial release (Closes: #nnnn)  <nnnn is the bug number of your ITP>
4
5  -- Josip Rodin <joy-mg@debian.org>  Mon, 22 Mar 2010 00:37:31 +0100
6

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

A la línia 1 hi ha el nom del paquet, versió, distribució i urgència. El nom serà el del paquet amb les fonts, la distribució hauria de ser, per ara, unstable, i la urgència no hauria de ser major a low. :-)

Les línies 3-5 són entrades de registre, on es documenta els canvis fets en la versió/revisió actual del paquet (no els canvis fets en les fonts originals: per això els autors de les fonts fan servir un altre arxiu que s'instal·larà com /usr/share/doc/gentoo/changelog.gz). A l'exemple se suposa que el codi de l'informe d'error ITP («Intent To Package», intent d'empaquetament) és 12345. Les noves línies s'afegiran a continuació de la primera començant sempre amb un * (asterisc). Pots fer servir dch(1) per afegir nova informació o un editor de text.

Per evitar que el paquet sigui accidentalment pujat al repositori abans d'estar finalitzat, és una bona idea canviar el nom de la distribució a un nom incorrecte com 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.

Ara mirarem quines són les regles que farà servir dpkg-buildpackage(1) per a la construcció del paquet. Aquest arxiu és un tipus de Makefile, però diferent dels que hi ha al codi font. En contra dels altres arxius del directori debian és un guió executable i cal que tengui aquesta propietat.

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

Una regla que voleu executar s'invoca pel seu nom d'objectiu com un argument de línia d'ordres. Per exemple, debian/rules build i fakeroot make -f debian/rules binary executa les regles per als objectius build i binary respectivament.

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.

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 EXAMPLES in dpkg-buildflags(1) and read /usr/share/dpkg/*
 7 DPKG_EXPORT_BUILDFLAGS = 1
 8 include /usr/share/dpkg/default.mk
 9 
10 # see FEATURE AREAS in dpkg-buildflags(1)
11 #export DEB_BUILD_MAINT_OPTIONS = hardening=+all
12
13 # see ENVIRONMENT in dpkg-buildflags(1)
14 # package maintainers to append CFLAGS
15 #export DEB_CFLAGS_MAINT_APPEND  = -Wall -pedantic
16 # package maintainers to append LDFLAGS
17 #export DEB_LDFLAGS_MAINT_APPEND = -Wl,--as-needed
18 
19 # main packaging script based on dh7 syntax
20 %:
21         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 20 i 21 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 executa dh build, que al seu torn executa el següent:

    dh_testdir
    dh_auto_configure
    dh_auto_build
    dh_auto_test
    
  • fakeroot debian/rules binary executa fakeroot dh binary, que al seu torn executa el següent [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 executa fakeroot dh binary-arch; que al seu torn executa la mateixa seqüència que fakeroot dh binary però amb l'opció -a per a cada ordre.

  • fakeroot debian/rules binary-indep executa fakeroot dh binary-indep, que al seu torn executa la mateixa seqüència que fakeroot dh binary excloent l'execució de dh_strip, dh_makeshlibs i dh_shlibdeps a la vegada que executa les demés ordres amb l'opció -i.

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.

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

Els arguments a continuació de dh_auto_configure -- s'afegeixen als predeterminants, anul·lant-los, en l'execució automàtica del programa. És millor fer servir l'ordre dh_auto_configure que el ./configure: d'aquesta manera només s'anul·larà l'argument --sysconfig mantenint els altres arguments de ./configure.

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

[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».

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

[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] Pots començar a aprendre a escriure arxius Makefile amb Debian Reference, 12.2 "Make". La documentació completa està disponible a http://www.gnu.org/software/make/manual/html_node/index.html o en el paquet make-doc de la secció no lliure («non-free») de l'arxiu Debian.

[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] Aquí es fan servir les noves funcions de la versió 7+ de debhelper que s'explique a «Not Your Grandpa's Debhelper» presentades a la DebConf9 per l'autor de debhelper. En lenny, dh_make construïa un arxiu rules més complex amb el llistat de cada ordre dh_* necessària per a cada objectiu, la majoria dels quals ja no són necessàries (i mostren l'edat del paquet). La nova ordre dh és més simple i ens allibera del treball «manua». Tot i així, és possible personalitzar el fitxer amb objectius override_dh_*. Consulta Secció 4.4.3, «Personalització del fitxer rules. Es basa únicament en el paquet debhelper i cal no confondre's amb la construcció de paquets feta amb cdbs.

[43] Per saber les seqüències d'ordres dh_* executades per a cada objectiu executa dh --no-act objectiu o bé debian/rules -- '--no-act objectiu' sense que s'executin realment.

[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] L'ordre també funciona amb altres sistemes de compilació com setup.py. L'execució de dh_auto_build --list en el directori de les fonts fa un llistat de les possibilitats admeses.

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