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.

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

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 <[email protected]>
 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ó [email protected]. 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 <[email protected]>
 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).

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 <[email protected]>
 4 Source: http://sourceforge.net/projects/gentoo/files/
 5
 6 Files: *
 7 Copyright: 1998-2010 Emil Brink <[email protected]>
 8 License: GPL-2+
 9
10 Files: icons/*
11 Copyright: 1998 Johan Hanson <[email protected]>
12 License: GPL-2+
13
14 Files: debian/*
15 Copyright: 1998-2010 Josip Rodin <[email protected]>
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.

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 <[email protected]>  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 <[email protected]>  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.

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.

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.

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.

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

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

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