=head1 NOME perlnewmod - preparare un nuovo modulo per distribuirlo =head1 DESCRIZIONE Questo documento vi dE alcuni suggerimenti su come procedere per scrivere moduli Perl, prepararli per distribuirli e renderli disponibili attraverso CPAN. Una delle cose che rendono il Perl davvero potente E il fatto che gli hacker del Perl tendono a voler condividere le soluzioni ai problemi che hanno giE affrontato, cosicchE voi non dobbiate combatterci di nuovo. Il modo principale per realizzare questa condivisione E mediante un'astrazione della soluzione in un modulo Perl. Se non sapete cos'E una di queste cose, il resto di questo documento non vi sarE di molta utilitE. Vi manca inoltre la conoscenza di una cospicua quantitE di codice utile; considerate l'idea di dare un'occhiata a L, L e L prima di ritornare qua. Quando avete trovato che non c'E un modulo disponibile per quello che state cercando di fare e voi stessi siete stati costretti a scrivere il codice, prendete in considerazione di fare un pacchetto della soluzione, farlo diventare un modulo e caricarlo su CPAN in maniera che altri possano beneficiarne. =head2 Avvertimenti In questa sede andremo a concentrarci principalmente sui moduli scritti unicamente in Perl, piuttosto che moduli XS. I moduli XS servono ad uno scopo piuttosto differente e potreste prendere in considerazione differenti aspetti prima di distribuirli: la popolaritE delle librerie che state unendo tra loro, la portabilitE su altri sistemi operativi e cosE via. Ad ogni modo, le note sulla preparazione del lato Perl del modulo, il renderlo un pacchetto e distribuirlo si applicano ugualmente bene sia ad un modulo XS che ad uno di solo Perl. =head2 Cosa dovrei mettere in un modulo? Dovreste mettere in un modulo tutto quel codice che pensate sarE utile agli altri. Tutto quello che E verosimile riempia un buco nella liberia della comunitE e che qualcun altro possa introdurre direttamente nei propri programmi. Qualsiasi parte del vostro codice che potete isolare, estrarre e inserire in qualcos'altro, E un candidato adatto. Facciamo un esempio. Supponiamo di leggere dei dati da un formato di dati locale ad un hash di hash in Perl, trasformarlo in un albero, traversare l'albero e poi riversare ogni nodo in un Server Transmogrifero della Acme. Ora, un bel numero di persone hanno il Transmogrifero della Acme e e voi avete bisogno di scrivere da zero qualcosa che parli il protocollo - vorrete quasi certamente farne un modulo. Il livello al quale lo imposterete E lasciato a voi: potreste volere dei moduli a livello di protocollo analoghi a L che poi comunicano a moduli di alto livello analoghi a L. La scelta E vostra ma voi volete assolutamente tirare fuori un modulo per il protocollo di quel server. Nessun altro sul pianeta comunicherE utilizzando il vostro formato locale, dunque questo aspetto possiamo ignorarlo. Ma che dire di tutto quel che c'E in mezzo? Costruire strutture ad albero a partire da variabili Perl e poi traversarle, E un problemino carino e generale, e se nessuno sta giE scrivendo un modulo che fa questo, potreste voler modularizzare anche questo codice. CosE, se tutto va bene, ora avete alcune idee su cosa sia buono da modularizzare. Ora andiamo a vedere come si fa. =head2 Passo passo: Preparare il terreno Prima ancora di partire a grattar via il codice, ci sono alcune cose che dovremmo fare in anticipo. =over 3 =item Guardatevi intorno Fate delle ricerca in un po' di moduli per vedere come sono stati scritti. Suggerirei di partire con L, visto che si trova nella libreria standard, E simpatico ed E semplice, e poi date un'occhiata a qualcosa di un po' piE complesso come L. C ed i moduli C, infine, forniscono buoni esempi di codice orientato agli oggetti. Questi dovrebbero darvi una idea generale su come i moduli vanno impostati e scritti. =item Controllate che sia inedito Ci sono un sacco di moduli su CPAN ed E facile non accorgersi di uno che E simile a quello che state pianificando di scrivere. Date una bella arata in L e siate sicuri di non reinventare la ruota! =item Discutetene la necessitE Potreste amarlo. Potreste avere l'impressione che chiunque lo desideri. Ma potrebbe davvero non esserci alcuna vera esigenza per questo modulo. Se non siete sicuri sull'esigenza che si avrE del vostro modulo, prendete in considerazione il fare un sondaggio sul newsgroup C, oppure come ultima spiaggia chiedete nella lista di discussione sui moduli su C. Ricordatevi che questa E una lista chiusa con un tempo di evasione molto lungo - preparatevi ad aspettare un bel po' per una risposta. =item Scegliete un nome I moduli Perl inclusi in CPAN hanno una gerarchia dei nomi alla quale dovreste cercare di adattarvi. Date un'occhiata a L per maggiori dettagli su come questo funzioni e fatevi un giro su CPAN e sulla lista dei moduli per farvi un'idea. Come ultimissima cosa, ricordatevi questo: i moduli dovrebbero avere la prima lettera di ogni stringa in maiuscolo ["Title capitalised", NdT], (Questo::Modo), inserirsi in una categoria e va spiegato il loro scopo in maniera concisa. =item Controllate di nuovo Mentre state facendo questo, assicuratevi di nuovo di non esservi lasciati sfuggire un modulo simile a quello che state scrivendo. Quando avete vagliato il nome e siete sicuri che il modulo sia voluto e non disponibile al momento, E tempo di iniziare a scrivere codice. =back =head2 Passo passo: Fare il modulo =over 3 =item Iniziare con F oppure F L'utility F viene distribuita come parte del pacchetto CPAN denominato L. Essa crea una directory con parti di tutti i file necessari ad iniziare un nuovo modulo, in conformitE con le recenti "best practice" [prassi migliori, NdT] per lo sviluppo di moduli, e viene invocato da linea di comando, dunque: module-starter --module=Pippo::Pluto \ --author="Tuo Nome" --email=tuonome@cpan.org Se non volete installare da CPAN il pacchetto L, F E uno strumento piE vecchio, inteso in origine per lo sviluppo di moduli XS, che si trova come pacchetto nella distribuzione Perl. Una tipica invocazione di L per un modulo di solo Perl E: h2xs -AX --skip-exporter --use-new-tests -n Pippo::Pluto Il C<-A> omette il codice Autoloader, C<-X> omette gli elementi XS, C<--skip-exporter> omette il codice Exporter, C<--use-new-tests> allestisce un ambiente moderno per i test e C<-n> specifica il nome del modulo. =item Usare L e L Il codice di un modulo deve essere sottoposto a warning e a strict, visto che non potete garantire le condizioni sotto le quali sarE usato. Inoltre, non vorrete comunque distribuire del codice che non sia sottoposto a warning e a strict, vero? =item Usare L Il modulo L vi permette di presentare i vostri messaggi di errore dalla prospettiva del chiamante; questo vi fornisce un modo per segnalare un problema con il chiamante e non con il vostro modulo. Per esempio, se dichiarate questo: warn "Non e` stato dato il nome dell'host"; l'utente vedrE qualcosa come questo: Non e` stato dato il nome dell'host at /usr/local/lib/perl5/site_perl/5.6.0/Net/Acme.pm line 123. che sembra come se il vostro modulo stia facendo qualcosa di sbagliato. Invece, volete dare la colpa all'utente, dicendo questo: Non e` stato dato il nome dell'host at cattivo_codice, line 10. Questo si fa usando L e sostituendo i vostri C con dei C. Se avete la necessitE di usare C, dichiarate invece C. Ad ogni modo, mantenete C e C al loro posto per i vostri controlli interni - dove il vostro modulo E davvero colpevole. =item Usare L - assennatamente! L vi fornisce un modo standard per esportare simboli e subroutine dal vostro modulo al namespace del chiamante. Per esempio, dire C importerebbe la subroutine C. La variabile di package C<@EXPORT> determinerE quali simboli saranno esportati quando il chiamante dichiara semplicemente C - difficilmente vorrete metterci qualcosa. C<@EXPORT_OK>, dall'altro lato, specifica quali simboli siete disposti ad esportare. Se volete esportare parecchi simboli, usate gli C<%EXPORT_TAGS> e definite un insieme di esportazione standard - date un'occhiate a L per maggiori dettagli. =item Usare la L ["semplice vecchia documentazione", NdT] Il lavoro non E finito fino a che le scartoffie non sono a posto e avrete la necessitE di dedicare del tempo a scrivere della documentazione per il vostro modulo. C oppure C vi forniranno uno schema da riempire; se non siete sicuri sul formato, date un'occhiata a L per un'introduzione. Si E soliti fornire nel codice una buona sinossi di come funziona il vostro modulo, una descrizione, e poi delle note sulla sintassi e funzionamento delle singole subroutine o metodi. Utilizzate i commenti Perl per le note agli sviluppatori e POD per le note agli utenti finali. =item Scrivere i test Siete incoraggiati a creare dei test automatici per il vostro modulo per assicurarvi che funzioni come stabilito sulla miriade di piattaforme supportate dal Perl; se effettuate un upload del vostro modulo su CPAN, una schiera di tester ne effetuerE il build e vi manderE i risultati dei test. Di nuovo, C e C forniranno una infrastruttura per i test che potete estendere - dovrete fare qualcosa di piE del semplice controllo che il vostro modulo compili. L e L sono dei buoni punti da cui partire quando si sta scrivendo un insieme di programmi di test. =item Scrivere il file README [LEGGIMI, NdT] Se state effettuando un upload su CPAN, dei gremlin automatizzati estrarranno il file README e lo metteranno nella vostra directory su CPAN. ApparirE anche nelle directory principali F e F ["per modulo" e "per categoria", NdT] se lo avete inserito nella lista dei moduli. E una buona idea mettervi, in dettaglio, quello che il modulo svolge effettivamente, ed i cambiamenti che l'utente puE notare dall'ultima versione. =back =head2 Passo passo: distribuire il vostro modulo =over 3 =item Ottenere un identificativo utente per CPAN Ogni sviluppatore che pubblica dei moduli su CPAN necessita di un identificativo CPAN. Visitate C, selezionate "Request PAUSE Account" ["Richiesta di un Account PAUSE", NdT] ed aspettate che la vostra richiesta venga approvata dagli amministratori di PAUSE. =item C Ancora una volta, C oppure C hanno fatto tutto il lavoro per voi. Essi producono il C standard che potete vedere quando scaricate e installate dei moduli e questo produce un Makefile con un target di C. Una volta che vi siete assicurati che il vostro modulo abbia passato i propri test - E sempre una buona cosa assicurarsene - potete eseguire un C e il Makefile, se tutto va bene, produrrE una simpatica tarball [il file creato con l'utility tar, NdT] del vostro modulo, pronto per effettuarne l'upload. =item Fare un upload della tarball L'email che avete ottenuto quando avete ricevuto il vostro ID di CPAN vi rivela come effettuare il login su PAUSE, il Perl Authors Upload SErver ["Server di Upload degli Autori di Perl", NdT]. Qui, dal menu, potete fare un upload del vostro modulo su CPAN. =item Fare un annuncio sulla lista di discussione sui moduli Una volta caricato, il modulo resterE nella vostra directory autore senza essere notato. Se volete che venga connesso al resto di CPAN, dovrete andare su "Register Namespace" ["Registrare il Namespace", NdT] su CPAN. Una volta registrati, il vostro modulo apparirE nell'elenco di quelli by-module e by-category su CPAN. =item Fare un annuncio su clpa Se avete un bruciante desiderio di dire al mondo della vostra versione del modulo, inviate un annuncio sul newgroup moderato C. =item Eliminare i bug! Una volta che avete iniziato a mettere assieme utenti, questi vi manderanno segnalazioni di bug. Se siete fortunati, vi manderanno anche delle correzioni. Benvenuti alle gioie della manutenzione di un progetto software... =back =head1 AUTORE Simon Cozens, C Aggiornato da Kirrily "Skud" Robert, C =head1 CONSULTATE ANCHE L, L, L, L, L, L, L, L, L, L L, L, L http://www.cpan.org/ , il tutorial di Ken Williams su come costruire il proprio modulo su http://mathforum.org/~ken/perl_modules.html =head1 TRADUZIONE =head2 Versione La versione su cui si basa questa traduzione E ottenibile con: perl -MPOD2::IT -e print_pod perlnewmod Per maggiori informazioni sul progetto di traduzione in italiano si veda L . =head2 Traduttore Traduzione a cura di dree. =head2 Revisore Revisione a cura di Flavio Poletti. =cut