Capitolo 4. File richiesti nella directory debian

Questo file contiene diversi valori che dpkg, dselect, apt-get, apt-cache, aptitude, ed altri strumenti utilizzeranno per gestire il pacchetto. Il tutto è definito nel Manuale delle policy di Debian, 5 "File di controllo ed i loro campi".

Questo è il file di control che dh_make crea:

 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>

(Sono stati aggiunti i numeri di riga.)

Le righe 1–7 contengono le informazioni di controllo per il pacchetto sorgente. Le righe 9-13 contengono le informazioni di controllo per il pacchetto binario.

La riga 1 contiene il nome del pacchetto sorgente.

La riga 2 indica la sezione della distribuzione in cui il pacchetto sorgente dovrà andare.

Come si sarà notato, l'archivio Debian è diviso in diverse aree: main (software libero), non-free (software non propriamente libero) e contrib (software libero che dipende da software non libero). All'interno di queste esistono delle sezioni che descrivono brevemente quali pacchetti vi si possono trovare. Quindi si hanno le sezioni admin per i programmi legati all'amministrazione di sistema, base per gli strumenti di base, devel per gli strumenti di sviluppo, doc per la documentazione, libs per le librerie, mail per client di posta e server associati, net per applicazioni e servizi di rete, x11 per programmi X11 che non appartengono alle altre categorie, e tanti altri. ^[28]

Si può cambiare il valore in x11. (Il prefisso main/ è implicito e può essere omesso.)

La riga numero 3 indica quanto sia importante per l'utente installare questo pacchetto. ^[29]

Le sezioni e le priorità vengono solitamente utilizzate da interfacce come aptitude in cui i pacchetti vengono suddivisi e vengono selezionati quelli predefiniti. Una volta caricato il pacchetto in Debian, il valore di ciascuno di questi due campi può essere sovrascritto dai manutentori dell'archivio, in tal caso si verrà avvertiti via mail.

Dal momento che il pacchetto trattato ha una priorità normale e non va in conflitto con altri, si cambierà la priorità a optional.

La riga 4 indica il nome e l'indirizzo email del manutentore. Ci si assicuri che questo campo includa una testata To valida per un indirizzo mail, perché una volta caricato il pacchetto, il sistema di rilevazione bug la userà per inviare le mail contenenti i bug. Si eviti di utilizzare virgole, 'e' commerciali o parentesi.

La riga 5 include la lista dei pacchetti richiesti per costruire il pacchetto, ad es. il campo Build-Depends. Si può, inoltre, avere una riga contenente il campo Build-Depends-Indep. ^[30] . Alcuni pacchetti come gcc e make sono richiesti implicitamente, dal pacchetto build-essential. Se si ha la necessità di avere altri strumenti per costruire il pacchetto, questi devono essere aggiunti negli appositi campi. I campi multipli sono separati con le virgole; si legga una spiegazione sulle dipendenze binarie per scoprirne di più sulla sintassi di queste righe.

Se non si è sicuri sul campo da utilizzare, si può scegliere il campo Build-Depends.^[31]

Per scoprire di quali pacchetti si ha bisogno per la compilazione si può eseguire il comando:

$ dpkg-depcheck -d ./configure

Per scoprire manualmente le esatte dipendenze per /usr/bin/foo, basta eseguire

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

e per ogni libreria elencata (ad esempio, libfoo.so.6), si esegue

$ dpkg -S libfoo.so.6

A questo punto si indica la versione -dev di ogni pacchetto come voce Build-Depends. Se si usa ldd per questo scopo, verranno considerate anche le dipendenze indirette, il che potrà portare ad avere un numero eccessivo di dipendenze.

Il pacchetto gentoo richiede anche xlibs-dev, libgtk1.2-dev e libglib1.2-dev per poter essere costruito, quindi tali dipendenze si aggiungeranno subito dopo debhelper.

La riga 6 indica la versione delle delle linee guida Debian che il pacchetto deve rispettare, che corrisponde a quello che si legge quando lo si crea.

Nella riga 7 si può inserire l'URL della pagina del programma originale.

La riga 9 indica il nome del pacchetto binario. Questo è normalmente lo stesso nome del pacchetto sorgente, ma non deve essere necessariamente così.

La riga 10 specifica le architetture per cui è possibile compilare il pacchetto. Questo valore è di solito uno dei seguenti, a seconda del tipo di pacchetto binario: ^[32]

Si lasci la riga 10 così com'è visto che il programma è scritto in C.dpkg-gencontrol(1) riempirà il campo dell'architettura con un valore adeguato per ciascuna macchina in cui il pacchetto viene compilato.

Se il pacchetto è indipendente dall'architettura (per esempio, uno script shell o Perl, o un documento), si cambi questo valore in all, e si legga in seguito in Sezione 4.4, «Il file rules» riguardo l'utilizzo della regola binary-indep al posto di binary-arch per costruire il pacchetto.

La riga 11 mostra una delle caratteristiche più potenti del sistema di pacchettizzazione Debian. I pacchetti possono relazionarsi tra di loro in vari modi. A parte Depends, altri campi di relazione sono Recommends, Suggests, Pre-Depends, Breaks, Conflicts, Provides e Replaces.

Gli strumenti di gestione dei pacchetti solitamente si comportano allo stesso modo quando si occupano di tali relazioni; in caso contrario, il comportamento verrà spiegato. (si legga dpkg(8), dselect(8), apt(8), aptitude(1) ecc.)

Ecco una descrizione semplificata delle relazioni tra i pacchetti: ^[33]

Tutti i campi qui descritti hanno una sintassi uniforme. Sono costituiti da una lista contenente i nomi dei pacchetti separati da virgole. Questi possono essere anche costituiti da liste di nomi di pacchetto alternativi, separati da barre verticali | (simboli pipe).

I campi possono limitare la loro applicabilità a particolari versioni di ogni pacchetto indicato. Le restrizioni di ogni singolo sono elencate tra parentesi dopo il nome de pacchetto, e dovrebbero contenere una relazione presa dalla lista qui sotto, seguita dal numero di versione. Le relazioni permesse sono: <<, <=, =, >= e >> per strettamente inferiore, inferiore o uguale, esattamente uguale, superiore o uguale e strettamente superiore, rispettivamente. Per esempio,

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'ultima caratteristica utile da conoscere è ${shlibs:Depends}, ${perl:Depends}, ${misc:Depends}, ecc.

dh_shlibdeps(1) calcola le dipendenze delle librerie condivise per i pacchetti binari. Questo genera un'elenco di eseguibili ELF e di librerie condivise che sono stati trovati in ogni pacchetto binario. Questa lista è utilizzata per ${shlibs:Depends}.

dh_perl(1) calcola le dipendenze perl. Questo genera un elenco di dipendenze perl o perlapi per ogni pacchetto binario. Questa lista è utilizzata per ${perl:Depends}.

Alcuni comandi debhelper possono far si che il pacchetto generato abbia bisogno di dipendere da altri pacchetti. Questa lista di pacchetti richiesti è utilizzata per ${misc:Depends}.

dh_gencontrol(1) genera il file DEBIAN/control per ogni pacchetto binario che utilizza ${shlibs:Depends}, ${perl:Depends}, ${misc:Depends}, ecc.

Detto ciò, si può lasciare la riga Depends esattamente come è ora, e si può inserire un'altra riga dopo questa che dica Suggests: file, perché gentoo può utilizzare alcune caratteristiche fornite dal pacchetto file.

La riga 9 è l'URL dell'homepage. Supponiamo che questa sia http://www.obsession.se/gentoo/ .

La riga 12 contiene una breve descrizione del pacchetto. Usualmente la larghezza dei terminali è di 80 colonne quindi il contenuto non dovrebbe superare i 60 caratteri. Si cambia questo valore in fully GUI-configurable, two-pane X file manager.

Nella riga 13 va messa la descrizione lunga. Questa dovrebbe consistere in un paragrafo che fornisce più dettagli sul pacchetto. La prima colonna di ogni riga dovrebbe essere vuota. Non ci dovrebbero essere linee vuote, ma si può mettere un singolo . (punto) in una colonna per simularle. Inoltre non ci dovrebbe essere più di una linea vuota dopo questa descrizione. ^[34]

Si possono inseriscono i campi Vcs-* per documentare il Version Control System (VCS) tra la linea 6 e 7. ^[35] Si supponga che il pacchetto gentoo abbia il suo VCS nel servizio Git Debian Alioth su git://git.debian.org/git/collab-maint/gentoo.git.

E per concludere, questo è il file control aggiornato:

 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.

(Sono stati aggiunti i numeri di riga.)

Questo file contiene le informazioni sul copyright e la licenza del programma originale. Il suo contenuto è descritto nel Manuale delle policy di Debian, 12.5 'Informazioni di copyright', e il documento DEP-5: Machine-parseable debian/copyright fornisce le linee guida del suo formato.

dh_make può fornire un modello di file del copyright, basta utilizzare l'opzione --copyright per selezionare quello giusto, se si desidera rilasciare il pacchetto gentoo sotto licenza 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.

Brevemente, ecco come il file di copyright del pacchetto gentoo dovrebbe apparire:

 1 Format: https://www.buy-develop.eu.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'.

(Sono stati aggiunti i numeri di riga.)

Si prega di seguire l'HOWTO fornito da ftpmasters ed inviato a debian-devel-announce: http://lists.debian.org/debian-devel-announce/2006/03/msg00023.html.

Questo è un file obbligatorio, che ha un formato speciale descritto nel Manuale delle policy di Debian, 4.4 "debian/changelog". Questo formato è utilizzato da dpkg ed altri programmi per ottenere il numero di versione, revisione, distribuzione ed urgenza del pacchetto.

Tale file è anche utile allo scopo di aver documentato tutti i cambiamenti che sono stati fatti. Sarà inoltre d'aiuto agli utenti che scaricano il pacchetto per vedere se ci sono problemi di cui dovrebbero essere al corrente. Il file verrà salvato come /usr/share/doc/gentoo/changelog.Debian.gz nel pacchetto binario.

dh_make ne crea uno predefinito, ecco come appare:

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

(Sono stati aggiunti i numeri di riga.)

La riga 1 indica il nome del pacchetto, la versione, la distribuzione e l'urgenza. Il nome deve corrispondere al nome del pacchetto sorgente, mentre la distribuzione dovrebbe essere unstable, e l'urgenza dovrebbe essere impostata come media, a meno chè non ci sia un motivo valido per impostarlo diversamente.

Le righe 3-5 sono una voce del registro, in cui vengono documentati i cambiamenti fatti nella revisione del pacchetto (non dei cambiamenti del pacchetto originario — c'è un file apposta per questo scopo, creato dagli autori originali, che verrà installato successivamente /usr/share/doc/gentoo/changelog.gz). Supponiamo che il numero di servizio del ticket ITP fosse 12345. Nuove righe devono essere aggiunte appena prima della riga più in alto che comincia con * (asterisco). Ciò si può fare con dch(1), o manualmente con un editor testuale.

Per evitare che un pacchetto venga accidentalmente caricato prima che il quest'ultimo sia pronto, è buona prassi cambiare il valore del campo distribuzione, con il valore fittizio UNRELEASED.

Alla fine si avrà qualcosa del genere:

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

(Sono stati aggiunti i numeri di riga.)

Quando si è soddisfatti di tutte le modifiche e quest'ultime sono state documentate nel file changelog, si può modificare il valore del campo distribuzione da UNRELEASED a unstable (o anche experimental). ^[36]

Si possono avere più informazioni su come aggiornare il file changelog nel capitolo Capitolo 8, Aggiornamento del pacchetto.

Ora si darà uno sguardo alle regole esatte che dpkg-buildpackage(1) userà per creare il pacchetto. In realtà questo file non è che un altro Makefile, ma diverso da quelli della sorgente originale. Differentemente dagli altri file sotto debian, questo è marcato come eseguibile.