4. Buone regole per creare una distribuzione

Le seguenti indicazioni descrivono come la propria distribuzione dovrebbe apparire quando qualcuno la rintraccia, la scarica e la decomprime.

4.1 Essere sicuri che gli archivi tar vengano sempre decompressi in una nuova singola directory

Il più fastidioso errore dei novelli sviluppatori consiste nel fare archivi tar che decomprimono i file e le directory della distribuzione nella directory corrente, magari sovrascrivendo file già esistenti. Non bisogna farlo mai !

Invece, si dev'essere sicuri che i file del proprio pacchetto abbiano tutti una porzione di directory chiamata come il progetto, affinché questi vengano decompressi in una singola directory direttamente sotto quella corrente.

Ecco un trucco per un makefile che agisce in questo modo, assumendo che la directory della propria distribuzione venga chiamata `foobar' e che SRC contenga un elenco dei file della distribuzione stessa. Ciò richiede GNU tar 1.13

VERS=1.0
foobar-$(VERS).tar.gz:
        tar --prefix-name='foobar-$(VERS)/' -czf foobar-$(VERS).tar.gz $(SRC)

Se si ha un versione più vecchia di tar, si può provare una cosa del tipo:

foobar-$(VERS).tar.gz:
        @ls $(SRC) | sed s:^:foobar-$(VERS)/: >MANIFEST
        @(cd ..; ln -s foobar foobar-$(VERS))
        (cd ..; tar -czvf foobar/foobar-$(VERS).tar.gz `cat foobar/MANIFEST`)
        @(cd ..; rm foobar-$(VERS))

4.2 Fornire un README

Bisogna fornire un file chiamato README o READ.ME che funga da mappa per la propria distribuzione. Per una vecchia convenzione, questo è il primo file che gli intrepidi esploratori leggeranno dopo aver decompresso i sorgenti.

È bene che il README includa:

• Una breve descrizione del progetto.
• Un link al sito web del progetto (se ne ha uno).
• Note sull'ambiente di progettazione ed eventuali problemi di portabilità.
• Una mappa che descriva i file importanti e le sotto-directory.
• Istruzioni per l'installazione e la compilazione o un richiamo a un file che contenga le stesse (di solito INSTALL).
• Un elenco di coloro che hanno fatto e che mantengono il progetto o un richiamo ad un file che lo contenga (di solito CREDITS).
• Novità recenti sul progetto o un richiamo ad un file che contenga le stesse (di solito NEWS).

4.3 Rispettare e seguire le regole standard per la titolazione dei file

Prima ancora di leggere il README, l'intrepido esploratore avrà analizzato i nomi dei file nella directory della distribuzione appena decompressa. Quei nomi possono essi stessi fornire delle informazioni. Aderendo a standard fissi sulle regole di nominazione, si può dare all'esploratore degli indizi preziosi su ciò che è in procinto di guardare.

Ecco alcuni nomi standard di file e il loro significato. Non è detto che siano tutti necessari per tutte le distribuzioni.

README or READ.ME

Il file della mappa, da leggersi per primo

INSTALL

istruzioni per la configurazione, struttura e l'installazione

CREDITS

elenco di chi ha contribuito al progetto

NEWS

notizie recenti sul progetto

HISTORY

storia del progetto

COPYING

termini di licenza del progetto (convenzione GNU)

LICENSE

termini di licenza del progetto

MANIFEST

elenco dei file della distribuzione

FAQ

documento testo contenente le domande poste più di frequente (Frequently Asked Question) sul progetto

TAGS

tag-file generato per uso di Emacs o vi

N.B. Si accetta come convenzione generale che i nomi dei file scritti tutti in caratteri maiuscoli costituiscano matainformazioni leggibili sul pacchetto, e non sui suoi componenti.