Capitolo 4. File richiesti nella directory `debian`

# Capitolo 4. File richiesti nella directory `debian`

È disponibile la riscrittura di questo tutorial, con contenuti aggiornati e con esempi più pratici, denominato Guide for Debian Maintainers. Si prega di utilizzare il nuovo tutorial come documento primario.

C'è una nuova sottodirectory all'interno della cartella contenente i sorgenti del programma ed è chiamata `debian`. All'interno di questa vi sono una serie di file che dovranno essere modificati per personalizzare il comportamento del pacchetto. I più importanti fra tutti questi sono i file `control`, `changelog`, `copyright` e `rules`, che vengono richiesti per tutti i pacchetti. [27]

## 4.1. `control`

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

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

- La priorità `optional` solitamente viene usata per i nuovi pacchetti che non vanno in conflitto con altri pacchetti con priorità `required`, `important` o `standard`.

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.

- Per tutti i pacchetti creati utilizzando il comando dh nel file `debian/rules`, è necessario avere `debhelper (>=9)` nel campo `Build-Depends`, per aderire alle policy di Debian che richiedono per l'obiettivo `clean`.

- I sorgenti dei pacchetti che hanno i pacchetti binari con il campo `Architecture: any`, vengono ricompilati con autobuilder. Poichè questa procedura installa i soli pacchetti elencati nel campo `Build-Depends`, prima di eseguire `debian/rules build` (vedere Sezione 6.2, «Auto-costruzione»), il campo `Build-Depends` ha bisogno di tutti i pacchetti necessari, ed il campo `Build-Depends-Indep` è raramente utilizzato.

- Per i sorgenti dei pacchetti che hanno i pacchetti binari con campo `Architecture: all`, il campo `Build-Depends-Indep` elenca tutti i pacchetti necessari, se non sono già elencati nel campo `Build-Depends`, per essere conforme alle linee guida di Debian riguardanti il target `clean`.

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]

- `Architecture: any`

  - Il pacchetto binario generato è compatibile con una sola architettura, solitamente è utilizzato in programmi creati con un linguaggio compilato.

- `Architecture: all`

  - Il pacchetto binario generato è indipendente dall'architettura, di solito si tratta di testo, immagini o script in un linguaggio interpretato.

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]

- `Depends`

  Il pacchetto non verrà installato a meno che tutti i pacchetti da cui dipende vengono installati. Si usi questa relazione se il programma non funzionerà assolutamente (o sarà praticamente inutilizzabile) a meno della presenza di particolari pacchetti.

- `Recommends`

  Si usi questa relazione per i pacchetti che non sono strettamente necessari ma sono solitamente utilizzati dal programma. Quando un utente installa il programma, tutte le interfacce di APT probabilmente chiederanno l'installazione dei pacchetti raccomandati. aptitude e apt-get installano, in modo predefinito, i pacchetti raccomandati insieme al pacchetto principale (ma l'utente può disabilitare questo comportamento predefinito). dpkg ignorerà questo campo.

- `Suggests`

  Si usi questa relazione per pacchetti che funzionano bene con il programma ma non sono per niente necessari. Quando un utente installa il programma, probabilmente non verrà chiesta l'installazione dei pacchetti consigliati. aptitude può essere configurato per installare i pacchetti consigliati insieme al pacchetto principale ma questo non è il comportamento predefinito. dpkg ed apt-get ignoreranno questo campo.

- `Pre-Depends`

  Questa relazione è più forte di `Depends`. Il pacchetto non verrà installato a meno che i pacchetti da cui pre-dipende sono stati installati e correttamente configurati. Si usi questa relazione con molta parsimonia e solo dopo averne discusso sulla mailing list debian-devel@lists.debian.org. Leggasi: non utilizzarla affatto. :-)

- `Conflicts`

  Il pacchetto non verrà installato a meno che tutti i pacchetti con i quali va in conflitto siano rimossi. Si usi questa relazione se il programma non funzionerà o causerà gravi problemi se un certo pacchetto è presente.

- `Breaks`

  Una volta installato il pacchetto verranno marcati come "guasti" tutti i pacchetti elencati. Normalmente la voce `Breaks` specifica che si applica a version precedenti di un certo valore. Per risolvere il problema, generalmente, basta aggiornare la lista dei pacchetti utilizzando uno strumento di gestione di alto livello, del sistema di pacchettizzazione.

- `Provides`

  Per alcuni tipi di pacchetto di cui vi sono molteplici alternative, sono stati definiti dei nomi virtuali. Si può trovare la lista completa nel file virtual-package-names-list.txt.gz. Si consulti questo file se il programma da pacchettizzare fornisce la funzione di un pacchetto virtuale esistente.

- `Replaces`

  Si usi questa relazione quando il programma rimpiazza i file di un altro pacchetto, o lo rimpiazza completamente (utilizzato in congiunzione con `Conflicts`). I file dei pacchetti indicati saranno sovrascritti con i file del nuovo pacchetto.

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

(Sono stati aggiunti i numeri di riga.)

## 4.2. `copyright`

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

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

## 4.3. `changelog`

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 <joy-mg@debian.org>  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 <joy-mg@debian.org>  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.

## 4.4. Il file `rules`

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.

### 4.4.1. Target del file `rules`

Ogni file `rules`, come ogni altro `Makefile`, si compone di diverse regole, ciascuno dei quali definisce un target e descrive come eseguirlo. [37] Una nuova regola inizia con la dichiarazione del target, nella prima colonna. Le righe seguenti che iniziano con il TAB (codice ASCII 9) specificano il come effettuare il target. Le righe vuote e quelle che iniziano con `#` (cancelletto) vengono trattate come commenti e ignorate. [38]

Quando si vuole eseguire una regola basta eseguire il comando passandogli come argomento il nome del target. Ad esempio, `debian/rules `build`` e `fakeroot make -f debian/rules `binary`` esegue le regole per i target ``build`` e ``binary``.

Ecco una spiegazione semplificata dei target:

- target `clean`: ripulisce tutti i file compilati, generati ed inutili nella struttura delle directory del pacchetto. (richiesto)

- target `build`: costruisce tutti i sorgenti per ottenere programmi compilati e documenti formattati nella struttura delle directory del pacchetto. (richiesto)

- target `build-arch`: costruisce i sorgenti per ottenere programmi compilati, dipendenti dall'architettura, nella radice dei sorgenti. (richiesto)

- target `build-indep`: costruisce i sorgenti per ottenere documenti formattati indipendenti dall'architettura nella radice dei sorgenti. (richiesto)

- target `install`: installa i file in una struttura ad albero per ogni pacchetto binario nella directory `debian`. Se definito, tutti i target `binary*` dipenderanno effettivamente da quest'ultimo. (opzionale)

- target `binary`: crea tutta una serie di pacchetti binari (combinando i target `binary-arch` e `binary-indep`). (richiesto)[39]

- target `binary-arch`: crea una serie di pacchetti binari dipendenti dall'architettura (`Architecture: any`) nella directory padre. (richiesto)[40]

- target `binary-indep`: crea una serie di pacchetti binari indipendenti dall'architettura (`Architecture: all`) nella directory padre. (richiesto)[41]

- target `get-orig-source`: ottiene la versione più recente del pacchetto sorgente originale dal relativo archivio originale. (optional)

È probabile che adesso ci sia un po' di confusione, ma sarà tutto più chiaro una volta esaminato il file `rules` che dh_make fornisce in modo predefinito.

### 4.4.2. Il file `rules` predefinito

Le nuove versioni di dh_make generano un file `rules` molto semplice ma potente utilizzando il comando 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 $@

(Sono stati aggiunti i numeri di riga ed eliminati alcuni commenti. Nel vero file `rules`, gli spazi vengono sostituiti da TAB.)

Probabilmente si sarà già familiari con le righe tipo la prima che ricordano gli script shell e Perl. In pratica indica al sistema operativo che il file andrà elaborato con `/usr/bin/make`.

La riga 4 può essere decommentata per impostare la variabile `DH_VERBOSE` a 1, in modo da mostrare gli output del comando dh che generano i programmi dh_* in esecuzione. È anche possibile aggiungere la riga `export DH_OPTIONS=-v`, in modo che ogni comando dh_* stampi quale comando sta eseguendo. Questo aiuta a comprendere esattamente cosa c'è dietro al singolo file `rules` file ed a diagnosticare i problemi. Il nuovo dh è progettato per formare una parte fondamentale degli strumenti `debhelper` e per essere trasparente, ovvero non nascondere nulla all'utente.

Tutto il lavoro è svolto nelle righe 20 e 21, grazie ad una regola implicita dichiarata nel modello. Il simbolo della percentuale significa che "ogni target" esegue una chiamata ad un singolo programma, dh con il nome del target stesso. [42] Il comando dh è uno script wrapper, che esegue una sequenza appropriata di programmi dh_* in base all'argomento passato. [43]

- `debian/rules clean` esegue `dh clean`; che a sua volta esegue i seguenti:

      dh_testdir
      dh_auto_clean
      dh_clean

- `debian/rules build` esegue `dh build`, che a sua volta esegue i seguenti:

      dh_testdir
      dh_auto_configure
      dh_auto_build
      dh_auto_test

- `fakeroot debian/rules binary` esegue `fakeroot dh binary`, che a sua volta esegue i seguenti[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` esegue `fakeroot dh binary-arch`, che a sua volta esegue la stessa sequenza di `fakeroot dh binary` ma con l'opzione `-a` aggiunta ad ogni comando.

- `fakeroot debian/rules binary-indep` esegue `fakeroot dh binary-indep`, che a sua volta esegue la stessa sequenza di `fakeroot dh binary` ma escludendo dh_strip, dh_makeshlibs, e dh_shlibdeps con l'opzione `-i` aggiunta ad ogni comando rimanente.

Le funzioni dei comandi dh_* sono, in gran parte, auto-esplicativi. [45] Ce ne sono alcune però, per cui vale la pena dare più spiegazioni, tenendo conto che si stia lavorando su un ambiente di sviluppo basato sul `Makefile`: [46]

- dh_auto_clean normalmente esegue i seguenti comandi se nel `Makefile` è presente il target `distclean`.[47]

      make distclean

- dh_auto_configure normalmente esegue i seguenti comandi se esiste il file `./configure` (argomenti abbreviati for una maggiore leggibilità).

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

- dh_auto_build normalmente lancia il seguente comando per eseguire, se esiste, il primo target del `Makefile`.

      make

- dh_auto_clean normalmente esegue i seguenti comandi, se nel `Makefile` esiste il target `test`.[48]

      make test

- dh_auto_install normalmente esegue il seguente comando se nel `Makefile` esiste il target `install` (riga spezzata per aumentare la leggibilità).

      make install \
        DESTDIR=/path/to/package_version-revision/debian/package

Tutti i target che richiedono il comando fakeroot dovrebbero contenere dh_testroot, che restituisce un errore se non si utilizza questo comando per fingere di essere root.

La cosa importante da sapere riguardo al file `rules` creato da dh_make, è che il suo contenuto contiene dei semplici consigli. Funzionerà per la maggior parte dei pacchetti ma per i più complicati non si esiti a personalizzarlo secondo le proprie esigenze.

Anche se il target `install` non è richiesto, è comunque supportato. `fakeroot dh install` si comporta come `fakeroot dh binary` ma si ferma dopo dh_fixperms.

### 4.4.3. Personalizzazione del file `rules`

Verrà qui spiegata la personalizzazione del file `rules`, creato con il nuovo comando dh.

Il comando `dh $@` può essere personalizzato come segue: [49]

- Aggiunge il supporto per il comando dh_python2. (La scelta migliore per Python) [50]

  - Include il pacchetto `python` in `Build-Depends`.

  - Utilizza `dh $@ --with python2`.

  - Gestisce i moduli Python utilizzando il framework `python`.

- Aggiunge il supporto per il comando dh_pysupport. (deprecato)

  - Include il pacchetto `python-support` in `Build-Depends`.

  - Utilizza `dh $@ --with pysupport`.

  - Gestisce i moduli Python utilizzando l'infrastruttura `python-support`.

- Aggiunge il supporto al comando dh_pycentral. (deprecato)

  - Include il pacchetto `python-central` in `Build-Depends`.

  - Utilizza in alternativa `dh $@ --with python-central`.

  - Disattiva anche il comando dh_pysupport.

  - Gestisce i moduli Python utilizzando l'infrastruttura `python-central`.

- Aggiunge il supporto per il comando dh_installtex.

  - Include il pacchetto `tex-common` in `Build-Depends`.

  - Utilizza in alternativa `dh $@ --with tex`.

  - Registra i caratteri Type 1, le regole di sillabazione, ed i formati con TeX.

- Aggiunge il supporto per i comandi dh_quilt_patch e dh_quilt_unpatch.

  - Include il pacchetto `quilt` in `Build-Depends`.

  - Utilizza in alternativa `dh $@ --with quilt`.

  - Applica e rimuove le patch al sorgente originale dai file nella directory `debian/patches` per i sorgenti dei pacchetti con formato `1.0`.

  - Non è necessario se si utilizza il nuovo formato del sorgente del pacchetto `3.0 (quilt)`.

- Aggiunge il supporto per il comando dh_dkms.

  - Include il pacchetto `dkms` in `Build-Depends`.

  - Utilizza in alternativa `dh $@ --with dkms`.

  - Gestisce in maniera corretta DKMS, usato dal pacchetto del modulo del kernel.

- Aggiunge il supporto per i comandi dh_autotools-dev_updateconfig e dh_autotools-dev_restoreconfig.

  - Include il pacchetto `autotools-dev` in `Build-Depends`.

  - Include in alternativa `dh $@ --with autotools-dev`.

  - Aggiorna e ripristina i file `config.sub` and `config.guess`.

- Aggiunge il supporto per i comandi dh_autoreconf e dh_autoreconf_clean.

  - Include il pacchetto `dh-autoreconf` in `Build-Depends`.

  - Utilizza in alternativa `dh $@ --with autoreconf`.

  - Aggiorna i file del sistema di compilazione GNU e ripristina i file dopo la sua compilazione.

- Aggiunge il supporto per il comando dh_girepository.

  - Include il pacchetto `gobject-introspection` in `Build-Depends`.

  - Utilizza in alternativa `dh $@ --with gir`.

  - Questa operazione calcola le dipendenze per i pacchetti che spediscono dei dati d'auto-analisi di GObject e genera la variabile di sostituzione `${gir:Depends}` per la dipendenza del pacchetto.

- Aggiunge il supporto alla funzionalità di completamento di bash.

  - Include il pacchetto `bash-completion` in `Build-Depends`.

  - Utilizza in alternativa `dh $@ --with bash-completion`.

  - Installa il completamento per bash utilizzando il file di configurazione `debian/`package`.bash-completion`.

Molti comandi del tipo dh_*, invocati da dh, possono essere personalizzati modificando i rispettivi file di configurazione nella directory `debian`. Si veda Capitolo 5, Altri file nella directory `debian` per la personalizzazione di tali caratteristiche.

Alcuni comandi del tipo dh_*, invocati da dh, possono richiedere la propria esecuzione con alcuni parametri o in aggiunta ad altri comandi da eseguire contestualmente o al posto dei comandi originali. In tali casi viene creato nel file `rules` il target `override_dh_`foo`` aggiungendo una regola solo per il comando dh_`foo` che si intende modificare. Fondamentalmente tale regola dice esegui me al posto di. [51]

Si noti che il comando dh_auto_* tende a fare più di ciò che è stato discusso in questa spiegazione (ultra)semplificata. È una cattiva idea utilizzare i target `override_dh_*` per sostituire i comandi equivalenti (ad eccezione del target `override_dh_auto_clean`) in quanto può bypassare delle caratteristiche "intelligenti" di `debhelper`.

Se si vogliono registrare i dati di configurazione di sistema nella directory `/etc/gentoo` invece che nella solita directory `/etc`, per il pacchetto `gentoo`, che utilizza gli Autotools, si può sovrascrivere il parametro predefinito `--sysconfig=/etc` dato dal comando dh_auto_configure al comando ./configure nel modo seguente:

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

I parametri immessi dopo `--` vengono aggiunti dopo i parametri predefiniti dei programmi eseguiti per sovrascriverli. Utilizzare il comando dh_auto_configure è preferibile rispetto al comando ./configure dal momento che sovrascriverà esclusivamente il parametro `--sysconfig` e manterrà gli altri parametri del comando ./configure.

Se il `Makefile` del sorgente per il pacchetto `gentoo` necessita che venga specificato il target per costruirlo [52], basterà creare il target `override_dh_auto_build` per abilitarlo.

    override_dh_auto_build:
            dh_auto_build -- build

Questo assicura che `$(MAKE)` verrà eseguito con tutti i parametri predefiniti del comando dh_auto_build ed il parametro `build`.

Se il `Makefile` del sorgente per il pacchetto `gentoo` necessita che venga specificato il target `packageclean` per pulirlo per il pacchetto Debian, al posto dell'utilizzo dei target `distclean` o `clean`, si può creare il target `override_dh_auto_build` pe abilitarlo.

    override_dh_auto_clean:
            $(MAKE) packageclean

Se il `Makefile` di un sorgente per il pacchetto `gentoo` contiene il target `test` che non vuole essere eseguito nel processo di costruzione del pacchetto Debian, si può utilizzare l'obiettivo `override_dh_auto_test` per saltarlo.

    override_dh_auto_test:

Se il programma originale `gentoo` contiene un inusuale file di changelog chiamato `FIXES`, dh_installchangelogs non installerà questo file in modo predefinito. Il comando dh_installchangelogs richiede che venga fornito il parametro `FIXES` per installarlo.[53]

    override_dh_installchangelogs:
            dh_installchangelogs FIXES

Quando si usa il nuovo comando dh, l'utilizzo di target espliciti come quelli elencanti in Sezione 4.4.1, «Target del file `rules`», possono rendere difficile capire i loro effetti. Si prega di limitare i target espliciti in favore dei target `override_dh_*` e, se possibile, quelli completamente indipendenti.

[27] In questo capitolo, per semplicità, i file nella directory `debian` sono indicati senza la directory radice `debian/`, ogni volta che il loro significato è scontato.

[28] Vedere Manuale delle policy di Debian, 2.4 "Sezioni" e Elenco delle sezioni in `sid`.

[29] Vedere Manuale delle policy di Debian, 2.5 "Priorità".

[30] Vedere Manuale delle policy di Debian, 7.7 "Relazioni tra pacchetti sorgenti e i pacchetti binari - Build-Depends, Build-Depends-Indep, Build-Conflicts, Build-Conflicts-Indep".

[31] Questa strana situazione è ben documentata in Debian Policy Manual, Footnotes 55. Questo non è dovuto all'uso del comando dh nel file `debian/rules`, ma bensì al funzionamento di dpkg-buildpackage.La stessa situazione si presenta per il sistema automatico di compilazione di Ubuntu.

[32] Vedere Manuale delle policy di Debian, 5.6.8 "Architettura" per maggiori informazioni.

[33] Vedere Manuale delle policy di Debian, 7 "Dichiarare le relazioni tra i pacchetti".

[34] Queste descrizioni sono in inglese. Le traduzioni di queste descrizioni sono fornite da The Debian Description Translation Project - DDTP.

[35] Vedere Guida di riferimento per lo sviluppatore Debian, 6.2.5. "Version Control System location".

[36] Se si utilizza il comando `dch -r` per effettuare quest'ultima modifica, ci si assicuri che l'editor salvi il file con il nome `changelog`.

[37] Si può imparare come scrivere il `Makefile` dalla Guida di riferimento Debian, 12.2. "Make". La documentazione completa è disponibile su http://www.gnu.org/software/make/manual/html_node/index.html o come pacchetto `make-doc` nella sezione `non-free` del repository.

[38] Il manuale delle policy Debian, 4.9 "Main building script: debian/rules" descrive i dettagli.

[39] Questo obiettivo è utilizzato da `dpkg-buildpackage` come in Sezione 6.1, «(ri)Creazione completa».

[40] Questo target è usato da `dpkg-buildpackage -B` come descritto in Sezione 6.2, «Auto-costruzione».

[41] Questo target è utilizzato da `dpkg-buildpackage -A`.

[42] Questo è una nuova caratteristica di `debhelper` v7+. La sua architettura è documentata su Not Your Grandpa's Debhelper ed è stata presentata alla Debconf9 dall'autore di `debhelper`. Su sistemi Debian `lenny`, dh_make crea file `rules` molto più complicati, con molti script dh_* elencati per ogni target, la maggior parte dei quali sono ormai inutili (e rispecchiano l'anzianità del pacchetto). La nuova versione del programma dh è molto più semplice e ci libera da questo vincolo. Si continuerà ad avere il pieno potere di personalizzazione utilizzando i target `override_dh_*`. Si veda Sezione 4.4.3, «Personalizzazione del file `rules`». Esso si basa solo sul pacchetto `debhelper` e non offusca il processo di compilazione come il pacchetto `cdbs`.

[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] Il seguente esempio assume che il file `debian/compat` abbia un valore uguale o superiore a 9, per evitare l'esecuzione automatica di qualsiasi comando python di supporto.

[45] Per informazioni dettagliate sul funzionamento di tutti questi script dh_ *, e sulle loro opzioni, leggere le rispettive pagine del manuale e `debhelper` documentazione.

[46] Questi comandi supportano altri ambienti di sviluppo, come `setup.py` che può essere elencato eseguendo `dh_auto_build --list` nella directory del sorgente del pacchetto.

[47] Attualmente il programma esegue il primo target presente nel `Makefile`, tra `distclean`, `realclean` o `clean`.

[48] Attualmente il programma esegue il primo target `test` o `check` disponibile nel `Makefile`.

[49] Se il pacchetto installa il file `/usr/share/perl5/Debian/Debhelper/Sequence/`nome_personalizzato`.pm`, si deve attivare la funzione di personalizzazione tramite il comando `dh $@ --with `nome-personalizzato``.

[50] L'uso del comando dh_python2 è preferito rispetto all'uso di dei comandi dh_pysupport o dh_pycentral. Non si deve utilizzare il comando dh_python.

[51] Sotto `lenny`, se si vuole cambiare il comportamento di uno script dh_* basta cercare la riga relativa nel file `rules` e modificarla.

[52] dh_auto_build senza alcun argomento eseguirà il primo target del file `Makefile`.

[53] I file `debian/changelog` e `debian/NEWS` vengono sempre installati automaticamente. Il changelog originale viene trovato convertendo i nomi dei file in minuscolo e cercando la corrispondenza con `changelog`, `changes`, `changelog.txt`, e `changes.txt`.

Capitolo 3. Modificare i sorgenti |  | Capitolo 5. Altri file nella directory `debian`