[ precedente ] [ Contenuti ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ successivo ]


Guida per il nuovo Maintainer
Capitolo 5 - Altri file nella directory debian


Per controllare la maggior parte delle operazioni che debhelper effettua durante la creazione del pacchetto, si possono inserire dei file di configurazione all'interno della directory debian. Questo capitolo fornirà una panoramica sull'utilizzo di ciascuno di essi ed il loro formato. Si legga Manuale delle policy di Debian e Guida di riferimento per lo sviluppatore Debian per le linee guida sulla creazione dei pacchetti.

Il comando dh_make creerà il modello dei file di configurazione nella directory debian. Molti di questi file terminano con l'estensione ".ex". In altri inoltre il nome del file viene preceduto dal nome del pacchetto in binario, come pacchetto. Si dia uno sguardo a tutti i differenti file di configurazione.

Il comando dh_make non crea alcun modello di file di configurazione per debhelper. In questo caso, è necessario crearlo con un editor.

Se si vuole o si ha bisogno di attivare alcuno di questi file, si effettuino le seguenti operazioni:

Questi file di configurazione di debhelper senza prefisso del pacchetto, come nel file install vengono applicati al primo pacchetto binario. Quando ci sono molti pacchetti binari le loro configurazioni possono essere specificate aggiungendo il loro prefisso al nome del file di configurazione come pacchetto-1.install, pacchetto-2.install, ecc.


5.1 Il file README.Debian

Ogni ulteriore dettaglio o discrepanza tra il pacchetto originale e la versione Debian dovrebbe essere documentato qui.

dh_make ne crea uno predefinito, ecco come appare:

     gentoo per Debian
     -----------------
     
     <possibili note riguardanti questo pacchetto - se non presenti, si cancelli questo file>
     
      -- Josip Rodin <joy-mg@debian.org>, Wed, 11 Nov 1998 21:02:14 +0100

Qui dovrebbero inserire delle brevi informazioni specifiche di Debian. Si veda dh_installdocs(1).


5.2 Il file compat

Il file compat definisce il livello di compatibilità di debhelper. Al momento dovrebbe essere impostato a debhelper V7 nel modo seguente.

     $ echo 7 > debian/compat

5.3 I file conffiles

Una delle cose più fastidiose riguardanti il software accade quando si spende una grande quantità di tempo e di sforzi per personalizzare un programma solo per vedere un aggiornamento spazzare via tutte le modifiche fatte. Debian risolve questo problema applicando un marchio ai file di configurazione in modo tale che, quando si aggiorna un pacchetto, verrà richiesto se si vogliono mantenere o meno i vecchi file di configurazione.

A partire da debhelper V3, dh_installdeb(1) automaticamente marcherà ogni file che si trova nella directory /etc come conffiles, così che se il programma ha soli file di configurazione in quella directory, non ci sarà bisogno di specificarli in questo file. Per la maggioranza dei tipi di pacchetto, l'unico posto in cui si trovano (ed in cui si dovrebbero trovare i conffile) è all'interno di /etc e quindi non c'è bisogno che questo file esista.

Se il programma creato utilizza file di configurazione e li sovrascrive in automatico, è meglio non rendere questi ultimi dei file di configurazione perché dpkg chiederà ogni volta agli utenti di verificare i cambiamenti.

Se il programma di cui si sta creando il pacchetto richiede ad ogni utente di modificare i file di configurazione nella directory /etc, ci sono principalmente 2 modi per non renderli conffiles e quindi di mantenere dpkg tranquillo.

Per maggiori informazioni sugli script del manutentore, si veda I file {post|pre}{inst|rm}, Sezione 5.18.


5.4 I file pacchetto.cron.*

Se il pacchetto creato richiede che vengano programmate delle operazioni per funzionare correttamente, si può utilizzare questo file per lo scopo. Si possono programmare delle operazioni in modo tale che vengano eseguite su base oraria, giornaliera, settimanale, mensile o che vengano eseguite alternativamente in qualsiasi momento si voglia.

Il formato dei file qui presentati è lo script di shell. L'unico che differisce dagli altri è pacchetto.cron.d che segue il formato di crontab(5).

Si noti che qui non è stata illustrata la rotazione dei log; a questo proposito si veda dh_installlogrotate(1) e logrotate(8).


5.5 Il file dirs

Questo file specifica le directory di cui si ha bisogno ma che la normale procedura di installazione ("make install DESTDIR=..." chiamata da "dh_auto_install") non crea. Questo generalmente indica la presenza di un problema nel Makefile.

I file elencati nel file install non hanno bisogno che le directory vengano create prima. Si veda Il file install, Sezione 5.11.

Si raccomanda di provare prima ad eseguire l'installazione ed utilizzare questo file solo se si incorre in problemi. Si noti che non il carattere slash non precede il nome delle directory.


5.6 Il file pacchetto.doc-base

Se il pacchetto generato ha altra documentazione oltre alle pagine del manuale e documenti informativi, dovrebbe essere utilizzato il file doc-base per segnalarla in modo che l'utente possa trovarla con, ad esempio dhelp(1), dwww(1) o doccentral(1).

Questa documentazione è solitamente costituita da documenti HTML, file PS e PDF, disponibili in /usr/share/doc/nomepacchetto/.

Questo è il modo in cui il file doc-base di gentoo, gentoo.doc-base, appare:

     Document: gentoo
     Title: Gentoo Manual
     Author: Emil Brink
     Abstract: This manual describes what Gentoo is, and how it can be used.
     Section: File Management
     
     Format: HTML
     Index: /usr/share/doc/gentoo/html/index.html
     Files: /usr/share/doc/gentoo/html/*.html

Per informazioni sul formato del file si veda install-docs(8) ed il manuale doc-base , reperibile in /usr/share/doc/doc-base/doc-base.html/.

Per ulteriori dettagli su come installare documentazione aggiuntiva, si veda in Installazione in una sotto-directory, Sezione 3.3.


5.7 Il file docs

Questo file specifica il nome dei file di documentazione che si possono avere dh_installdocs(1) li installa nella directory temporanea automaticamente.

Normalmente, questo file includerà tutti i file esistenti nella directory dei sorgenti di più alto livello che sono chiamati "BUGS", "README*", "TODO" ecc.

Per il pacchetto gentoo, nell'esempio, sono stati inclusi anche altri files:

     BUGS
     CONFIG-CHANGES
     CREDITS
     NEWS
     README
     README.gtkrc
     TODO

5.8 Il file emacsen-*

Se il pacchetto generato contiene file Emacs che possono essere compilati al momento dell'installazione, i file emacsen-* possono essere usati per impostarne la compilazione

Tali file sono installati nella directory temporanea con dh_installemacsen(1).

Se non se ne ha bisogno, possono essere eliminati.


5.9 Il file pacchetto.examples

Il comando dh_installexamples(1) installa i file e le directory elencati al suo interno come file di esempio.


5.10 I file pacchetto.init e pacchetto.default

Se il pacchetto generato è un demone che deve partire all'avvio del sistema, hai chiaramente ignorato le mie raccomandazioni iniziali, vero? :-)

Il file pacchetto.init viene installato come lo script /etc/init.d/pacchetto. La sua struttura abbastanza generica è fornita dal comando dh_make come init.d.ex. Probabilmente si dovrà rinominare e modificare un bel po', cercando di assicurarsi di fornire degli header che rispettino gli standard della gerarchia dei filesystem (si veda /usr/share/doc/debian-policy/fhs/). Il file viene installato nella directory temporanea con dh_installinit(1).

Il file pacchetto.default viene installato in /etc/default/pacchetto. Questo file imposta delle variabili che vengono caricate dallo script di init. La maggioranza delle volte questo file predefinito viene utilizzato per disabilitare l'esecuzione di un demone, impostare degli argomenti predefiniti oppure dei timeout. Se lo script di init ha alcune caratteristiche configurabili si dovrà installare queste nel file predefinito, non nello script di init.

Se il programma originale ha un file di init si può decidere di utilizzarlo o meno. Se non viene utilizzato quello script init.d allora ne dovrà essere creato uno nuovo in debian/pacchetto.init. Comunque se lo script di init originale sembra funzionare bene ed installa tutto nella corretta destinazione, si devono comunque impostare i link simbolici rc*. Per fare questo si deve sovrascrivere dh_installinit nel file rules con le seguenti righe:

     override_dh_installinit:
             dh_installinit --onlyscripts

Se non si ha bisogno di tutto ciò, si possono rimuovere i file.


5.11 Il file install

Se ci sono dei file che devono essere installati nel pacchetto ma con il normale comando "make install" non vengono elaborati, i nomi di quest'ultimi e le cartelle di destinazione vanno messe in questo file install. Tali file vengono installati con il comando dh_install(1).[34] Andrebbe innanzitutto controllato che non ci sia uno strumento più specifico da poter utilizzare. Per esempio, i documenti dovrebbero essere elencati nel file docs e non in questo file.

Nel file install compare una riga per ogni file installato, contenente il nome del file (relativo alla directory in cui avviene la costruzione del pacchetto), uno spazio e la directory di installazione (relativa alla posizione del file install). Un esempio dell'utilizzo è quando un file binario non è stato installato, in questo caso il file install dovrebbe essere:

     src/foo/mybin usr/bin

Questo significa che quando il pacchetto verrà installato, ci sarà un file binario /usr/bin/mybin.

Alternativamente, questo file install può presentare il nome del file senza la directory di installazione solo quando il percorso relativo della directory non cambia. Questo formato è solitamente utilizzato per grandi pacchetti che organizzano i risultati della costruzione in pacchetti multipli utilizzando pacchetto-1.install, pacchetto-2.install, ecc.

Il comando dh_install andrà a controllare nella cartella debian/tmp alla ricerca di file, se non ne trova nella directory corrente (or in qualsiasi altro posto si sia indicato di guardare utilizzando --sourcedir).


5.12 pacchetto.info

Se il pacchetto generato ha delle pagine informative, queste andrebbero installate utilizzando il comando dh_installinfo(1) ed elencandole nei file pacchetto.info.


5.13 I file {pacchetto.|source/}lintian-overrides

Se il pacchetto lintian segnala degli errori di diagnostica in un caso in cui esista una policy che ammette delle eccezioni alle regole, si possono utilizzare i file pacchetto.lintian-overrides o source/lintian-overrides per inibire le segnalazioni. Si legga /usr/share/doc/lintian/lintian.html/index.html e si eviti di farne un uso eccessivo.

Il file pacchetto.lintian-overrides è ovviamente utilizzato per il pacchetto binario chiamato pacchetto ed è installato in usr/share/lintian/overrides/pacchetto dal comando dh_lintian.

Il file source/lintian-overrides è utilizzato per il pacchetto sorgente. Questo non viene installato.


5.14 I file manpage.*

I programmi creati dovrebbero avere una pagina di manuale. In caso contrario bisogna crearlo. Il comando dh_make crea diversi file modello per la pagina di manuale. Questi devono essere copiati e modificati per ogni comando senza pagina di manuale. Si faccia attenzione a rimuovere i file modello non utilizzati.


5.14.1 Il file manpage.1.ex

Le pagine del manuale sono solitamente scritte per nroff(1). Anche il file modello manpage.1.ex è scritto per nroff. Si veda la pagina di manuale man(7) per una breve descrizione su come modificare un file del genere.

L'ultimo file delle pagine del manuale dovrebbe includere il nome del programma che si sta documentando, quindi verrà rinominato da "manpage" a "gentoo". Il nome del file include anche ".1" come primo suffisso, il che sta ad indicare che la sezione della pagina del manuale è relativa ad un comando dell'utente. Si verifichi che questa sezione sia quella corretta. Qui di seguito viene presentata una breve lista delle sezioni delle pagine del manuale:

     Section |     Description     |     Notes
        1     User commands          Executable commands or scripts.
        2     System calls           Functions provided by the kernel.
        3     Library calls          Functions within system libraries.
        4     Special files          Usually found in /dev
        5     File formats           E.g. /etc/passwd's format
        6     Games                  Or other frivolous programs
        7     Macro packages         Such as man macros.
        8     System administration  Programs typically only run by root.
        9     Kernel routines        Non-standard calls and internals.

Così la pagina man del pacchetto gentoo dovrebbe chiamarsi gentoo.1. Se non ci fosse alcuna pagina man gentoo.1 nei sorgenti originali, andrebbe creata rinominando il modello manpage.1.ex in gentoo.1 e modificandolo utilizzando le informazioni contenute negli esempi e nei documenti originali.

Si può utilizzare il comando help2man per generare una pagina di manuale, priva del risultato di "--help" and "--version", per ogni programma. [35]


5.14.2 Il file manpage.sgml.ex

Se d'altra parte si preferisce scrivere in SGML piuttosto che utilizzare nroff, si può utilizzare il modello manpage.sgml.ex . Se si procede in questo modo andrà:


5.14.3 Il file manpage.xml.ex

Se si preferisce l'XML all'SGML, si può utilizzare il modello manpage.xml.ex. Se si decide questa modalità si avranno due scelte:


5.15 pacchetto.manpages

Se il pacchetto creato presenta delle pagine del manuale, queste andrebbero installate utilizzando il comando dh_installman(1) ed elencandole nei file pacchetto.manpages .

Per installare il file doc/gentoo.1 come pagine di manuale per il pacchetto gentoo, si deve creare il file gentoo.manpages contenente:

     docs/gentoo.1

5.16 Il file menu

Gli utenti dell'X Window System solitamente hanno un gestore di finestre che può essere personalizzato per lanciare programmi. Se hanno installato il pacchetto menu , verrà creato un set di menu per ogni programma del sistema.

Questo è il modello del file menu.ex che il comando dh_make crea:

     ?package(gentoo):needs="X11|text|vc|wm" \
             section="Applications/see-menu-manual"\
             title="gentoo" command="/usr/bin/gentoo"

Il primo campo dopo i due punti è needs, e specifica il tipo di interfaccia di cui ha bisogno il programma. Questo valore può essere cambiato con una delle alternative elencate, ad esempio text o X11.

Il campo successivo è section, in cui dovrebbero apparire le voci del menu e del sottomenu. L'attuale lista delle sezioni [36] si trova in: /usr/share/doc/debian-policy/menu-policy.html/ch2.html#s2.1

Il campo title indica il nome del programma. Se si vuole si può scrivere in maiuscolo. Basta che si mantenga corto.

Infine, il campo command indica il comando che manda in esecuzione il programma.

Si può quindi cambiare il file menu e la voce del menu nel modo seguente:

     ?package(gentoo): needs="X11" \
             section="Applications/Tools" \
             title="Gentoo" command="gentoo"

Si possono anche aggiungere altri campi come longtitle, icon, hints ecc. Si veda dh_installmenu(1), menufile(5), update-menus(1) e /usr/share/doc/debian-policy/menu-policy.html/ per maggiori informazioni.


5.17 Il file NEWS

Il comando dh_installchangelogs(1) installa questo file.


5.18 I file {post|pre}{inst|rm}

I files postinst, preinst, postrm e prerm [37] vengono chiamati script del manutentore. Questi sono script che vengono messi nell'area di controllo del pacchetto e vengono lanciati dal comando dpkg quando il pacchetto viene installato, aggiornato o rimosso.

Un nuovo manutentore dovrebbe, se possibile, evitare ogni modifica manuale degli script del manutentore perché potrebbero creare dei problemi. Per maggiori informazioni si guardi nel Manuale delle policy di Debian, 6 'Script di manutenzione del pacchetto e procedure di installazione', e si dia un'occhiata ai file di esempio forniti da dh_make.

Se non si è data retta e si sono creati dei script del manutentore personalizzati per un pacchetto, bisogna essere sicuri di averli provati non solo per install e upgrade, ma anche per remove e purge.

Gli aggiornamenti alle nuove versioni dovrebbero essere indolore e non invadenti (gli utenti esistenti non dovrebbero notare gli aggiornamenti a meno di scoprire che vecchi bug sono stati corretti e che vi sono magari delle nuove funzionalità).

Quando l'aggiornamento deve per forza di cose essere invadente (per esempio, file di configurazione sparsi all'interno di diverse cartelle home con strutture totalmente differenti), si può impostare il pacchetto ai valori sicuri predefiniti (esempio, servizi disabilitati) e fornire una valida documentazione come richiesto dalla policy (README.Debian e NEWS.Debian) come ultima spiaggia. Sarebbe meglio non disturbare l'utente con la nota debconf richiamata da questi script del manutentore per gli aggiornamenti.

Il pacchetto ucf fornisce una infrastruttura di gestione simil-conffile per preservare cambiamenti effettuati dall'utente in file che non possono essere etichettati come conffile, come ad esempio quelli gestiti dagli script del manutentore. Questo dovrebbe ridurre al minimo i problemi ad esso associati.

Questi script del manutentore sono delle migliorie di Debian che fanno capire come mai le persone scelgano Debian. Bisogna stare molo attenti a non infastidirle a causa loro.


5.19 Il file TODO

Il comando dh_installdocs(1) installa questo file.


5.20 Il file watch

Questo file è utilizzato per configurare il programma uscan(1) (nel pacchetto devscripts ). Questo viene utilizzato per controllare il sito da cui sono stati presi i sorgenti originali. Viene utilizzato anche da Debian External Health Status (DEHS).

Questo è ciò che si può mettere al suo interno:

     # watch control file for uscan
     version=3
     http://sf.net/gentoo/gentoo-(.+)\.tar\.gz debian uupdate

Normalmente con il file watch, l'URL "http://sf.net/gentoo" viene scaricato per cercare dei collegamenti del tipo "<a href=...>". Il nome base (la parte appena dopo l'ultimo "/") di questi URL sono confrontati con l'espressione regolare Perl (si veda perlre(1)) "gentoo-(.+)\.tar\.gz". Tra i file che combaciano viene scaricato quello avente il numero di versione più grande e viene avviato il programma uupdate per creare un albero dei sorgenti aggiornato.

Sebbene questo sia vero per la maggior parte dei siti, il servizio di scaricamento di SourceForge su http://sf.net è un'eccezione. Quando il file watch ha un URL che corrisponde all'espressione regolare perl "^http://sf\.net/", il programma uscan lo sostituisce con "http://qa.debian.org/watch/sf.php/". Il servizio di reindirizzamento degli URL http://qa.debian.org/ è progettato per mettere a disposizione un sistema stabile per reindirizzare gli URL tipo "http://sf.net/project/tar-name-(.+)\.tar\.gz" presenti i nel file watch. Questo risolve il problema relativo al cambiamento periodico degli URL.


5.21 Il file source/format

Nel file debian/source/format, ci dovrebbe essere una unica riga che indichi il formato desiderato per il pacchetto sorgente (controllare dpkg-source(1) per una lista completa). Dopo squeeze, dovrebbe scrivere:

Il nuovo formato sorgente 3.0 (quilt) registra le modifiche in una serie di patch quilt all'interno di debian/patches. Questi cambiamenti vengono poi automaticamente applicati durante l'estrazione del pacchetto sorgente. [38] Le modifiche di Debian sono semplicemente mantenute in un archivio debian.tar.gz contenente tutti i file sotto la directory debian. Questo nuovo formato supporta l'inclusione di file binari come per esempio le icone PNG del manutentore del pacchetto senza richiedere trucchi.[39]

Quando dpkg-source estrae un pacchetto sorgente nel formato 3.0 (quilt), applica automaticamente tutte le patch elencate nel file debian/patches/series. Si può evitare di applicare le patch alla fine dell'estrazione con l'opzione --skip-patches.


5.22 Il file source/local-options

Quando si vogliono gestire le attività di pacchettizzazione utilizzando un VCS, di norma si crea un ramo (es. upstream) in cui si tiene traccia dei cambiamenti apportanti al sorgente originale, e un altro ramo (es. di solito master per git) in cui si tiene traccia delle modifiche apportate al pacchetto. In fine, è consigliato avere i sorgenti originali non "pachati" con i file in debian/* per il pacchetto Debian, per fare facilitare le operazioni di fusione con il nuovo sorgente originale.

Dopo aver costruito il pacchetto, il sorgente è di norma "pachato. È necessario togliere la patch manualmente, eseguendo "quilt pop -a", prima di caricarlo nel ramo master. Si può automatizzare l'operazione, aggiungendo il file debian/source/local-options con contenuto "unapply-patches". Questo file non è incluso nel sorgente del pacchetto generato, e cambia solamente la modalità di costruzione in locale. Questo file può contenere anche "abort-on-upstream-changes", (si veda dpkg-source(1)).


5.23 I file patches/*

Il vecchio formato sorgente 1.0 creava un singolo, grosso file diff.gz file che conteneva tutti i file di manutenzione del pacchetto che stavano in debian ed i file di patch del sorgente. Un pacchetto così è un poco ingombrante da ispezionare per capire successivamente la sequenza delle modifiche. Per questo tale formato non è considerato soddisfacente.

Il nuovo formato sorgente 3.0 (quilt) salva le patch in alcuni file debian/patches/* utilizzando il comando quilt. Queste patch ed altri dati del pacchetto che sono tutti reperibili nella directory debian vengono compressi nel file debian.tar.gz. Poiché il comando dpkg-source è in grado di gestire le patch formattate con quilt nel sorgente del pacchetto versione 3.0 (quilt) senza il pacchetto quilt, non è necessaria la dipendenza Build-Depends nel pacchetto quilt. [40]

Il comando quilt è documentato in quilt(1). Esso registra le modifiche ai sorgenti come una coda di file di patch -p1 nella directory debian/patches e l'albero dei sorgenti non varia al di fuori della directory debian. L'ordine delle patch è registrato nel file debian/patches/series. Si può applicare (=push), rimuovere(=pop), ed aggiornare le patch con facilità. [41]

Per Modificare i sorgenti, Capitolo 3, sono state create 3 patch in debian/patches.

Dal momento che le patch di Debian sono posizionate in debian/patches, si prega di impostare correttamente il comando quilt come descritto in TODO "ref id="quiltrc"".

Quando una qualsiasi persona fornisce una patch foo.patch per i sorgenti, allora la modifica del pacchetto sorgente di tipo 3.0 (quilt)è abbastanza semplice:

     $ dpkg-source -x gentoo_0.9.12.dsc
     $ cd gentoo-0.9.12
     $ quilt import ../foo.patch
     $ quilt push
     $ quilt refresh
     $ quilt header -e
     ... describe patch

Le patch salvate nel nuovo formato sorgente 3.0 (quilt) devono essere prive di fuzz. Bisogna quindi assicurarsi di ciò eseguendo "quilt pop -a; while quilt push; do quilt refresh; done".


[ precedente ] [ Contenuti ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ successivo ]


Guida per il nuovo Maintainer

version 1.2.25, 2010-12-21 14:06:56 UTC

Josip Rodin joy-mg@debian.org
Traduzione: Calogero Lo Leggio kalos@nerdrug.org
Traduzione: Jacopo Reggiani jacopo.reggiani@gmail.com
Traduzione: Francesco P. Lovergine