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

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

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

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

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

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

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.

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.

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.