Capitolo 2. Primi passi

Indice

2.1. Flusso di lavoro per la costruzione dei pacchetti Debian
2.2. Scegliamo il programma
2.3. Prendere il programma e provarlo
2.4. Sistemi di compilazione semplici
2.5. Sistemi di compilazione portabili più utilizzati
2.6. Nome e versione del pacchetto
2.7. Configurare dh_make
2.8. Il primo pacchetto non nativo per Debian

Iniziamo a creare un pacchetto (o, meglio ancora, adottiamone uno già esistente).

Se si sta facendo un pacchetto Debian con un programma, il flusso di lavoro tipico per la costruzione di pacchetti Debian comporta la generazione di diversi file indicati in modo specifico per ogni passo come segue:

Si prega di notare che il carattere di separazione tra pacchetto e versione è stato modificato da - (trattino) nel nome dell'archivio, a _ (trattino basso) nel nome del pacchetto Debian.

Nel file di nomi di cui sopra, sostituire la parte relativa al pacchetto con il nome del pacchetto, la versione con la versione originale, la revisione con la revisione Debian, e l' architettura con l'architettura del pacchetto, come definito nel manuale delle Policy di Debian. [5]

Ogni passo di questo schema è spiegato con esempi dettagliati nelle sezioni successive.

Probabilmente avete già scelto il pacchetto da creare. La prima cosa da fare è controllare se il pacchetto è già presente negli archivi della distribuzione, utilizzando i seguenti strumenti:

Se il pacchetto esiste già, bene, basta installarlo! :-) Se dovesse essere orfano (cioè, se il maintainer è Debian QA Group), lo si può prendere in carico se è ancora disponibile. Si può adottare anche un pacchetto per il quale il suo manutentore ha presentato una richiesta di adozione (RFA).[6]

Ci sono diverse risorse per controllare lo stato di appartenenza dei pacchetti:

Come nota a margine, è importante sottolineare che Debian ha già i pacchetti per la maggior parte dei programmi e che il numero di pacchetti presenti nell'archivio Debian è molto più grande di quello dei contribuenti con permessi di caricamento. Pertanto, i contributi sui pacchetti già presenti in archivio sono molto più apprezzati dagli altri sviluppatori (ed è molto più probabile che si ottenga una sponsorizzazione). [7]. Si può contribuire in diversi modi:

If you are able to adopt the package, get the sources (with something like apt-get source packagename) and examine them. This document unfortunately doesn't include comprehensive information about adopting packages. Thankfully you shouldn't have a hard time figuring out how the package works since someone has already done the initial setup for you. Keep reading, though; a lot of the advice below will still be applicable to your case.

Se il pacchetto è nuovo, e si pensa che sarebbe bello entrare a far parte di Debian, ecco come procedere:

  • Prima di tutto bisogna capire se il programma funziona in modo corretto, e averlo provato per almeno un po' di tempo e dimostrarne l'utilità.

  • You must check that no one else is already working on the package on the Work-Needing and Prospective Packages site. If no one else is working on it, file an ITP (Intent To Package) bug report to the wnpp pseudo-package using reportbug. If someone's already on it, contact them if you feel you need to. If not — find another interesting program that nobody is maintaining.

  • il programma deve avere una licenza.

    • I programmi nella sezione main, devono essere completamente compatibili con le Linee Guida per il Software Libero Debian (DFSG, Debian Free Software Guidelines) (vedere DSFG) e non devono richiede nessun pacchetto che non sia presente nella sezione main, per la compilazione o l'esecuzione. Questo è il caso preferito.

    • I programmi nella sezione contrib, devono essere conformi alle DFSG, ma potrebbero richiedere, per la compilazione o l'esecuzione, un pacchetto che non è presente nella sezione main.

    • I programmi nella sezione non-free, possono non essere conformi alle DFSG, ma devono poter essere distribuibili.

    • Se non si è sicuri su quale sezione il pacchetto dovrebbe essere incluso, si può mandare il testo della licenza alla mailing list debian-legal@lists.debian.org e chiedere consigli.

  • The program should not introduce security and maintenance concerns into the Debian system.

    • The program should be well documented and its code needs to be understandable (i.e., not obfuscated).

    • Si dovrebbe contattare l'autore o gli autori del programma per verificare che siano d'accordo con la sua pacchettizzazione. È importante essere in grado di consultarsi con l'autore/i sul programma nel caso di problemi specifici del programma, per questo è meglio non provare a pacchettizzare programmi non più manutenuti.

    • il programma non dovrebbe certamente girare come setuid root, o meglio, non dovrebbe per niente richiedere di essere setuid o setgid.

    • il programma non dovrebbe essere un daemon, o essere installato nelle directory */sbin, o aprire una porta come root.

Of course, the last one is just a safety measure, and is intended to save you from enraging users if you do something wrong in some setuid daemon… When you gain more experience in packaging, you'll be able to package such software.

Visto che si è alle prime armi come maintainer, si consiglia di acquisire un po' d'esperienza creando dei pacchetti semplici cercando di evitare quelli più complicati.

  • Pacchetti semplici

    • pacchetto binario singolo, arch = all (collezione di dati, come le immagini di sfondo)

    • pacchetto binario singolo, arch = all (eseguibili scritti in un linguaggio interpretato come lo shell POSIX)

  • Pacchetti di media difficoltà

    • pacchetto binario singolo, arch = any (binari ELF eseguibili compilati da linguaggi come C e C++)

    • pacchetti binari multipli, arch = any + all (pacchetti per binari ELF eseguibili + documentazione)

    • sorgente originale in un formato diverso da tar.gz o tar.bz2

    • l'archivio dei sorgenti originale ha contenuti non distribuibili.

  • Pacchetti complessi

    • pacchetto di un modulo di un interprete utilizzato da altri pacchetti

    • libreria ELF generica utilizzata da altri pacchetti

    • pacchetti binari multipli che includono un pacchetto di una libreria ELF

    • pacchetto con molteplici sorgenti originali

    • pacchetti di moduli del kernel

    • pacchetti di patch del kernel

    • ogni pacchetto con degli script di manutenzione non banali

Creare pacchetti complessi non è troppo difficile, ma richiede un po' più di conoscenza. Si dovrebbe cercare una guida specifica per ogni caratteristica complessa. Ad esempio, alcuni linguaggi hanno dei loro documenti con le loro linee guida:

There is another old Latin saying: fabricando fit faber (practice makes perfect). It is highly recommended to practice and experiment with all the steps of Debian packaging with simple packages while reading this tutorial. A trivial upstream tarball, hello-sh-1.0.tar.gz, created as follows may offer a good starting point:[8]

$ mkdir -p hello-sh/hello-sh-1.0; cd hello-sh/hello-sh-1.0
$ cat > hello <<EOF
#!/bin/sh
# (C) 2011 Foo Bar, GPL2+
echo "Hello!"
EOF
$ chmod 755 hello
$ cd ..
$ tar -cvzf hello-sh-1.0.tar.gz hello-sh-1.0

La prima cosa da fare è trovare e scaricare il codice sorgente originale del programma. Supponendo che si è recuperato il file dal sito web dell'autore. Generalmente il codice sorgente dei programmi liberi per Unix e derivati sono in formato tar+gzip con estensione .tar.gz, oppure in formato tar+bzip2 con estensione .tar.bz2. Di solito, questi file, contengono la sottodirectory dal nome pacchetto-versione con tutti i sorgenti.

If the latest version of the source is available through a Version Control System (VCS) such as Git, Subversion, or CVS, you need to get it with git clone, svn co, or cvs co and repack it into tar+gzip format yourself by using the --exclude-vcs option.

Se il codice sorgente è in qualche altro formato di archiviazione (per esempio, con estensione .Z o .zip[9]), scompattarlo con i programmi appropriati, e ricomprimerlo.

Se il sorgente del programma viene fornito con alcuni contenuti che non sono conformi con il DFSG, si dovrebbe scompattarlo, rimuovere questi contenuti e ricomprimerlo con una versione modificata dei sorgenti originali contenenti dfsg .

A titolo di esempio, verrà utilizzato il programma gentoo, un gestore file grafico basato su GTK+.[10]

È buona regola creare una sottodirectory nella directory home e nominarla debian o deb o qualsiasi altro nome appropriato (ad es. in questo caso ~/gentoo andrebbe più che bene). Scaricare l'archivio e scompattarlo (con il comando tar xzf gentoo-0.9.12.tar.gz). Bisogna assicurarsi che non ci siano errori, per quanto in apparenza irrilevanti, perché potrebbero causare problemi nell'estrazione dell'archivio sul sistema di altre persone, alcuni strumenti di estrazione a volte ignorano queste anomalie. Nella console dovrebbe esserci quanto segue.

$ mkdir ~/gentoo ; cd ~/gentoo
$ wget http://www.example.org/gentoo-0.9.12.tar.gz
$ tar xvzf gentoo-0.9.12.tar.gz
$ ls -F
gentoo-0.9.12/
gentoo-0.9.12.tar.gz

A questo punto si avrà un'altra sottodirectory, dal nome gentoo-0.9.12. Spostarsi in questa directory e leggere attentamente la documentazione fornita. Di solito si avranno dei file come README*, INSTALL*, *.lsm o *.html. È necessario trovare istruzioni su come compilare e installare correttamente il programma (si potrebbe supporre di installare il programma nella directory /usr/local/bin, ma questo non è il comportamento corretto, tratteremo l'argomento più avanti Sezione 3.3, «Installazione dei file nei loro percorsi»).

Si dovrebbe iniziare la pacchettizzazione con la directory dei sorgenti completamente ripulita, o semplicemente partendo da una nuova estrazione dall'archivio dei sorgenti.

I programmi più semplici sono dotati di un file Makefile, e possono essere compilati semplicemente con il comando make.[11] Alcuni supportano make check, che esegue dei controlli automatici. Per installare il programma nella directory di destinazione, di solito basta eseguire make install.

Adesso si provi a compilare ed eseguire il programma, assicurandosi che funzioni correttamente e che niente sia andato storto durante l'installazione o l'esecuzione.

Di solito, per ripulire la directory di compilazione, si usa il comando make clean (o meglio ancora make distclean). Talvolta c'è anche il comando make uninstall che serve a rimuovere tutti i file installati.

Molti programmi liberi sono scritti utilizzando i linguaggi di programmazione C e C++. Molti di questi utilizzano Autotools o CMake per essere portabili su diverse piattaforme. Questi strumenti vengono utilizzati per generare il Makefile e altri file sorgenti necessari. Dopo di questo, i programmi vengono compilati utilizzando il solito make; make install.

Autotools è il sistema di compilazione della GNU, che comprendere Autoconf, Automake, Libtool, e gettext. Per capire meglio ciò che avviene, si possono leggere i seguenti file sorgenti: configure.ac, Makefile.am, e Makefile.in. [12]

Il primo passo del flusso di lavoro degli Autotools consiste solitamente nell'esecuzione del comando autoreconf -i -f per i sorgenti che verranno successivamente distribuiti insieme ai file generati.

configure.ac-----+-> autoreconf -+-> configure
Makefile.am -----+        |      +-> Makefile.in
src/Makefile.am -+        |      +-> src/Makefile.in
                          |      +-> config.h.in
                      automake
                      aclocal
                      aclocal.m4
                      autoheader

La modifica dei file configure.ac e Makefile.am richiede una minima conoscenza di autoconf e automake. Vedereinfo autoconf e info automake.

Il passo successivo da compiere con Autotools, di solito, consiste nel procurarsi il sorgente del programma e nel compilarlo nella directory binary tramite l'esecuzione dei comandi ./configure && make all'interno della directory dei sorgenti stessi.

Makefile.in -----+                +-> Makefile -----+-> make -> binary
src/Makefile.in -+-> ./configure -+-> src/Makefile -+
config.h.in -----+                +-> config.h -----+
                 |
  config.status -+
  config.guess --+

Si possono modificare molte cose nel file Makefile, come la posizione predefinita di installazione dei file utilizzando l'opzione ./configure --prefix=/usr.

Nonostante non sia richiesto, l'aggiornamento di configure e degli altri file con autoreconf -i -f può migliorare la compatibilità del sorgente. [13]

CMake è un alternativo sistema di compilazione. Per conoscerlo meglio si può leggere il file CMakeLists.txt.

Se il sorgente del programma originale è nominato gentoo-0.9.12.tar.gz, si può usare gentoo come nome pacchetto e 0.9.12 come versione del programma originale. Queste stringhe saranno utilizzate nel file debian/changelog come vedremo più avanti nel Sezione 4.3, «changelog».

Although this simple approach works most of the time, you may need to adjust package name and upstream version by renaming the upstream source to follow Debian Policy and existing convention.

You must choose the package name to consist only of lower case letters (a-z), digits (0-9), plus (+) and minus (-) signs, and periods (.). It must be at least two characters long, must start with an alphanumeric character, and must not be the same as existing packages. It is a good idea to keep its length within 30 characters. [14]

Se il sorgente originale usa un nome troppo generico come test-suite è consigliabile rinominarlo, in modo da identificare meglio il suo contenuto e per non rischiare di sporcare il namespace. [15]

You should choose the upstream version to consist only of alphanumerics (0-9A-Za-z), plus signs (+), tildes (~), and periods (.). It must start with a digit (0-9). [16] It is good idea to keep its length within 8 characters if possible. [17]

If upstream does not use a normal versioning scheme such as 2.30.32 but uses some kind of date such as 11Apr29, a random codename string, or a VCS hash value as part of the version, make sure to remove them from the upstream version. Such information can be recorded in the debian/changelog file. If you need to invent a version string, use the YYYYMMDD format such as 20110429 as upstream version. This ensures that dpkg interprets later versions correctly as upgrades. If you need to ensure smooth transition to the normal version scheme such as 0.1 in the future, use the 0~YYMMDD format such as 0~110429 as the upstream version.

Le stringhe di versione [18] possono essere confrontate usando dpkg(1) come segue:

$ dpkg --compare-versions ver1 op ver2

Le regole per il confronto delle versioni possono essere riassunte in questo modo:

  • Le stringhe sono confrontate dall'inizio alla fine (da sinistra verso destra).

  • Le lettere hanno più priorità delle cifre.

  • I numeri sono confrontati come interi.

  • Le lettere sono confrontate in ordine di codice ASCII.

  • Ci sono regole speciali per il punto (.), il segno più (+), e il carattere tilde (~), eccole descritte:

    0.0 < 0.5 < 0.10 < 0.99 < 1 < 1.0~rc1 < 1.0 < 1.0+b1 < 1.0+nmu1 < 1.1 < 2.0

Un esempio di caso intricato si ha, ad esempio, quando una è presente una pre-release RC come gentoo-0.9.12-ReleaseCandidate-99.tar.gz per il programma gentoo-0.9.12.tar.gz. In questo caso è necessario assicurarsi che l'aggiornamento funzioni correttamente, rinominando il sorgente originale gentoo-0.9.12~rc99.tar.gz.

Una delle prime cose da fare è impostare le variabili d'ambiente della shell $DEBEMAIL e $DEBFULLNAME visto che molti strumenti di gestione di Debian usano queste variabili per recuperare il nome e l'email da utilizzare nei pacchetti.[19].

$ cat >>~/.bashrc <<EOF
DEBEMAIL="your.email.address@example.org"
DEBFULLNAME="Firstname Lastname"
export DEBEMAIL DEBFULLNAME
EOF
$ . ~/.bashrc

I pacchetti classici per Debian sono pacchetti non-nativi, ovvero non specificamente pensati per debian, come ad esempio qualche programma di manutenzione per Debian. Se si desidera creare un pacchetto Debian non-nativo del programma con il sorgente gentoo-0.9.12.tar.gz si può utilizzare il programma dh_make come segue:

$ cd ~/gentoo
$ wget http://example.org/gentoo-0.9.12.tar.gz
$ tar -xvzf gentoo-0.9.12.tar.gz
$ cd gentoo-0.9.12
$ dh_make -f ../gentoo-0.9.12.tar.gz

Ovviamente, si deve sostituire il nome del file con il nome dell'archivio dei sorgenti originali. [20] Vedere dh_make(8) per i dettagli.

You should see some output asking you what sort of package you want to create. Gentoo is a single binary package — it creates only one binary package, i.e., one .deb file — so we will select the first option (with the s key), check the information on the screen, and confirm by pressing ENTER. [21]

L'esecuzione di dh_make, creerà una copia dell'archivio originale del programma, come nome gentoo_0.9.12.orig.tar.gz, nella directory superiore, per consentire, più avanti, la creazione di un pacchetto Debian sorgente non-nativo con nome debian.tar.gz:

$ cd ~/gentoo ; ls -F
gentoo-0.9.12/
gentoo-0.9.12.tar.gz
gentoo_0.9.12.orig.tar.gz

Si presti attenzione a due caratteristiche chiave presenti nel nome del file gentoo_0.9.12.orig.tar.gz:

  • Il nome del pacchetto e la versione sono separati da _ (trattino basso).

  • La stringa .orig è inserita prima di .tar.gz.

Si dovrebbe aver notato che nella sottodirectory dei sorgenti debian sono stati creati molti modelli di file. Questo verrà trattato in Capitolo 4, File richiesti nella directory debian e Capitolo 5, Altri file nella directory debian. Dovreste aver capito che la pacchettizzazione non è un processo automatico. È necessario modificare il sorgente originale per Debian (come descritto in Capitolo 3, Modificare i sorgenti). Dopo di questo, è necessario creare i pacchetti Debian in maniera appropriata (Capitolo 6, Costruzione del pacchetto), provarli Capitolo 7, Controllare il pacchetto per errori, e caricarli (Capitolo 9, Caricamento del pacchetto). Tutti i passaggi verranno approfonditi in seguito.

Se accidentalmente viene cancellato qualche modello di file mentre ci si lavora, è possibile recuperarlo eseguendo dh_make con l'opzione --addmissing nella directory dei sorgenti del pacchetto Debian.

L'aggiornamento di un pacchetto già esistente può diventare complicato, perché è possibile che si siano usate vecchie tecniche di pacchettizzazione. Per adesso, è consigliabile, concentrarsi sulla creazione di nuovi pacchetti per imparare le basi. Si tornerà ad approfondire l'argomento più avanti su Capitolo 8, Aggiornamento del pacchetto.

Please note that the source file does not need to contain any build system discussed in Sezione 2.4, «Sistemi di compilazione semplici» and Sezione 2.5, «Sistemi di compilazione portabili più utilizzati». It could be just a collection of graphical data, etc. Installation of files may be carried out using only debhelper configuration files such as debian/install (see Sezione 5.11, «install»).



[4] Per gli archivi non nativi nel vecchio formato 1.0, viene utilizzato il nome pacchetto_versione-revisione.diff.gz

[5] Vedere 5.6.1 "Sorgente", 5.6.7 "Pacchetto", e 5.6.12 "Versione". L'architettura del pacchetto è conforme al manuale delle Policy di Debian: 5.6.8 "Architettura" ed è assegnata automaticamente al processo di creazione del pacchetto.

[7] Detto questo, ovviamente ci sarà sempre qualche nuovo programma che vale la pena pacchettizzare.

[8] Non ci si preoccupi della mancanza dei Makefile. È possibile installare il programma hello semplicemente usando il comando debhelper come in Sezione 5.11, «install», oppure modificando il sorgente originale aggiungendo un nuovo Makefile con la destinazione dell' install come in Capitolo 3, Modificare i sorgenti .

[9] Si può utilizzare il comando file per scoprire il formato di archiviazione

[10] Il programma in questione è già stato pacchettizzato. La versione corrente usa gli Autotools e la sua costruzione e struttura è molto sostanzialmente differente dagli esempi seguenti, che sono basati sulla versione 0.9.12.

[11] Many modern programs come with a script named configure, which when executed creates a Makefile customized for your system.

[12] Autotools is too big to deal with in this small tutorial. This section is meant to provide keywords and references only. Please make sure to read the Autotools Tutorial and the local copy of /usr/share/doc/autotools-dev/README.Debian.gz, if you need to use it.

[13] Si possono automatizzare queste operazioni utilizzando il pacchetto dh-autoreconf. Vedere Sezione 4.4.3, «Personalizzazione del file rules».

[14] Il campo di default di aptitude del nome del pacchetto è di 30 caratteri. Oltre il 90% dei pacchetti ha un nome più piccolo di 24 caratteri.

[15] If you follow the Debian Developer's Reference 5.1. "New packages", the ITP process will usually catch this kind of issue.

[16] Questa regola dovrebbe aiutare ad evitare confusione con i nome dei file.

[17] La lunghezza predefinita del campo "versione" di aptitude è di 10 caratteri. Di solito le revisioni Debian precedute da un trattino ne utilizzano 2. Per più dell'80% dei pacchetti, la lunghezza della versione dei sorgenti originali è più piccola di 10 caratteri e la revisione Debian è inferiore a 3 caratteri.

[18] La stringa della versione può essere costituita da versione del programma originale (versione), revisione Debian (revisione), oppure da versione (versione-revisione). Vedere Sezione 8.1, «Nuova revisione Debian» per conoscere come incrementare il numero della revisione Debian.

[19] Il seguente testo assume che stiate utilizzando Bash come shell di login. Se si utilizza un'altra shell di login, come la Z shell, bisognerà usare i suoi file di configurazione al posto di ~/.bashrc.

[20] If the upstream source provides the debian directory and its contents, run the dh_make command with the extra option --addmissing. The new source 3.0 (quilt) format is robust enough not to break even for these packages. You may need to update the contents provided by the upstream version for your Debian package.

[21] Ecco le varie opzioni: s che sta per binario Singolo, i per Indipendente dall'architettura, m per binario Multiplo, l per Libreria, k per modulo del Kernel, n per patch del kernel e b per cdbs. Questo documento si basa sull'uso del comando dh (contenuto nel pacchetto debhelper) per la creazione di un pacchetto contenente un singolo binario, verrà trattato anche il funzionamento dei pacchetti indipendenti dall'architettura e i pacchetti con binari multipli. Il pacchetto cdbs offre un'infrastruttura di script alternativa al comando dh e non rientra nell'ambito di questo documento.