C.2.2 Aggiungere nuove funzionalità

Ognuno è libero di aggiungere tutte le nuove funzionalità che vuole a gawk. Comunque, se si desidera che tali modifiche siano incorporate nella distribuzione di gawk, ci sono parecchi passi da fare per rendere possibile la loro inclusione:

1. Prima di inserire la nuova funzionalità all’interno di gawk, prendere in considerazione la possibilità di scriverla sotto forma di estensione (vedi la sezione Scrivere estensioni per gawk). Se ciò non è possibile, continuare con i passi rimanenti descritti in questa lista.
2. Essere disposti a firmare un documento liberatorio appropriato. Se l’FSF deve poter distribuire le modifiche, queste vanno dichiarate di pubblico dominio, tramite la firma di un documento apposito, oppure attribuendo il copyright delle modifiche all’FSF. Entrambe queste azioni sono semplici da fare, e molte persone già l’hanno fatto. Se ci sono domande da fare, mettersi in contatto con me (vedi la sezione Segnalazione di problemi e bug), oppure “assign chiocciola gnu punto org”.
3. Utilizzare l’ultima versione. È molto più semplice per me integrare modifiche se sono basate sull’ultima versione disponibile di gawk o, meglio ancora, sull’ultimo codice sorgente presente nel deposito Git. Se la versione di gawk è molto vecchia, potrei non essere affatto in grado di integrare le modifiche. (Vedi la sezione Ottenere la distribuzione di gawk, per informazioni su come ottenere l’ultima versione di gawk.)
4. Seguire gli Standard di codifica GNU. Questo documento descrive come dovrebbe essere scritto il software GNU. Se non lo si è letto, è bene farlo, preferibilmente prima di iniziare a modificare gawk. (Gli Standard di codifica GNU sono disponibili nel sito web del Progetto GNU. Sono disponibili anche versioni in formato Texinfo, Info, e DVI.)
5. Usare lo stile di codifica gawk. Il codice sorgente in C di gawk segue le istruzioni dello Standard di codifica GNU, con qualche piccola eccezione. Il codice è formattato usando lo stile tradizionale “K&R”, in particolare per ciò che riguarda il posizionamento delle parentesi graffe e l’uso del carattere TAB. In breve, le regole di codifica per gawk sono le seguenti:
   • Usare intestazioni di funzione (prototipi) in stile ANSI/ISO quando si definiscono delle funzioni.
   • Mettere il nome della funzione all’inizio della riga in cui la si sta definendo.
   • Usare ‘#elif’ invece di nidificare istruzioni ‘#if’ all’interno di un’istruzione ‘#else’.
   • Mettere il tipo di codice di ritorno della funzione, anche se è int, sulla riga immediatamente sopra quella che contiene il nome e gli argomenti della funzione.
   • Mettere degli spazi attorno alle parentesi usate nelle strutture di controllo (if, while, for, do, switch e return).
   • Non mettere spazi davanti alle parentesi usate nelle chiamate di funzione.
   • Mettere spazi attorno a tutti gli operatori C e dopo le virgole, nelle chiamate di funzione.
   • Non usare l’operatore virgola per produrre degli effetti collaterali multipli, tranne che nelle parti di inizializzazione e incremento dei cicli for, e nel corpo delle macro.
   • Usare dei caratteri TAB per l’indentazione, e non dei semplici spazi.
   • Usare lo stile “K&R” per formattare le parti di programma incluse fra parentesi graffe.
   • Usare confronti con NULL e '\0' per le condizioni contenute nelle istruzioni if, while e for, e anche nelle varie clausole case delle istruzioni switch, invece del semplice puntatore o il semplice valore del carattere.
   • Usare i valori true e false per le variabili booleane, la costante simbolica NULL per i valori dei puntatori, e la costante carattere '\0' quando è il caso, invece dei valori 1 e 0.
   • Fornire un commento descrittivo di una riga per ogni funzione.
   • Non usare la funzione alloca() per allocare memoria dalla stack. Il farlo genera dei problemi di portabilità che non giustificano il vantaggio secondario di non doversi preoccupare di liberare la memoria. Usare invece malloc() e free().
   • Non usare confronti nella forma ‘! strcmp(a, b)’ o simili. Come disse una volta Henry Spencer, “strcmp() non è una funzione booleana!” Usare invece ‘strcmp(a, b) == 0’.
   • Per aggiungere nuovi valori a flag binari, usare costanti esadecimali esplicite (0x001, 0x002, 0x004, etc.) invece che spostare di un bit a sinistra in incrementi successivi (‘(1<<0)’, ‘(1<<1)’, etc.).

   NOTA: Qualora fossi costretto a riformattare completamente il codice per farlo aderire allo stile di codifica usato in gawk, potrei anche decidere di ignorare del tutto le modifiche proposte.

6. Aggiornare la documentazione. Insieme col nuovo codice, fornire nuove sezioni e/o capitoli per questo Documento. Per quanto possibile, usare il formato Texinfo, invece di fornire soltanto del testo ASCII non formattato (sebbene un semplice testo sia già meglio che nessuna documentazione). Le convenzioni da seguire in GAWK: Programmare efficacemente in AWK sono elencate dopo la parole chiave ‘@bye’ alla fine del file sorgente Texinfo. Se possibile, aggiornare anche la pagina di manuale in formato man.

   Si dovrà anche firmare un documento liberatorio relativo alle modifiche apportate alla documentazione.

7. Inviare le modifiche come file di differenze nel formato contestuale unificato. Usare ‘diff -u -r -N’ per confrontare i sorgenti originali dell’albero di sorgenti gawk con la versione proposta. Si raccomanda di usare la versione GNU di diff o, ancora meglio, ‘git diff’ o ‘git format-patch’. Per inviare le modifiche proposte spedire l’output prodotto da diff. (Vedi la sezione Segnalazione di problemi e bug, per l’indirizzo di posta elettronica.)

   L’uso di questo formato rende semplice per me l’applicazione delle modifiche alla versione principale del sorgente di gawk (usando il programma di utilità patch). Se invece tocca a me applicare le modifiche a mano, con un editor di testo, potrei decidere di non farlo, specialmente se le modifiche sono molte.

8. Includere una descrizione da aggiungere al file ChangeLog riguardo alla modifica da voi proposta. Questo serve a minimizzare l’attività a me richiesta, rendendo più facile per me l’accettazione delle modifiche, che diventa più semplice se si include anche questa parte nel file di differenze (nel formato diff).

Sebbene questa possa sembrare una richiesta molto esigente, si tenga presente che, anche se il nuovo codice non è opera mia, tocca poi a me manutenerlo e correggere eventuali errori. Se non è possibile per me farlo senza perderci troppo tempo, potrei anche lasciar perdere la modifica.