NOME

perlnewmod - preparare un nuovo modulo per distribuirlo

DESCRIZIONE

Questo documento vi dà 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 è il fatto che gli hacker del Perl tendono a voler condividere le soluzioni ai problemi che hanno già affrontato, cosicché voi non dobbiate combatterci di nuovo.

Il modo principale per realizzare questa condivisione è mediante un'astrazione della soluzione in un modulo Perl. Se non sapete cos'è una di queste cose, il resto di questo documento non vi sarà di molta utilità. Vi manca inoltre la conoscenza di una cospicua quantità di codice utile; considerate l'idea di dare un'occhiata a perlmod, perlmodlib e perlmodinstall prima di ritornare qua.

Quando avete trovato che non c'è 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.

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 popolarità delle librerie che state unendo tra loro, la portabilità su altri sistemi operativi e così 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.

Cosa dovrei mettere in un modulo?

Dovreste mettere in un modulo tutto quel codice che pensate sarà utile agli altri. Tutto quello che è verosimile riempia un buco nella liberia della comunità e che qualcun altro possa introdurre direttamente nei propri programmi. Qualsiasi parte del vostro codice che potete isolare, estrarre e inserire in qualcos'altro, è 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 è lasciato a voi: potreste volere dei moduli a livello di protocollo analoghi a Net::SMTP che poi comunicano a moduli di alto livello analoghi a Mail::Send. La scelta è vostra ma voi volete assolutamente tirare fuori un modulo per il protocollo di quel server.

Nessun altro sul pianeta comunicherà utilizzando il vostro formato locale, dunque questo aspetto possiamo ignorarlo. Ma che dire di tutto quel che c'è in mezzo? Costruire strutture ad albero a partire da variabili Perl e poi traversarle, è un problemino carino e generale, e se nessuno sta già scrivendo un modulo che fa questo, potreste voler modularizzare anche questo codice.

Così, se tutto va bene, ora avete alcune idee su cosa sia buono da modularizzare. Ora andiamo a vedere come si fa.

Passo passo: Preparare il terreno

Prima ancora di partire a grattar via il codice, ci sono alcune cose che dovremmo fare in anticipo.

Guardatevi intorno

Fate delle ricerca in un po' di moduli per vedere come sono stati scritti. Suggerirei di partire con Text::Tabs, visto che si trova nella libreria standard, è simpatico ed è semplice, e poi date un'occhiata a qualcosa di un po' più complesso come File::Copy. WWW::Mechanize ed i moduli Email::*, infine, forniscono buoni esempi di codice orientato agli oggetti.

Questi dovrebbero darvi una idea generale su come i moduli vanno impostati e scritti.

Controllate che sia inedito

Ci sono un sacco di moduli su CPAN ed è facile non accorgersi di uno che è simile a quello che state pianificando di scrivere. Date una bella arata in http://search.cpan.org e siate sicuri di non reinventare la ruota!

Discutetene la necessità

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 avrà del vostro modulo, prendete in considerazione il fare un sondaggio sul newsgroup comp.lang.perl.modules, oppure come ultima spiaggia chiedete nella lista di discussione sui moduli su modules@perl.org. Ricordatevi che questa è una lista chiusa con un tempo di evasione molto lungo - preparatevi ad aspettare un bel po' per una risposta.

Scegliete un nome

I moduli Perl inclusi in CPAN hanno una gerarchia dei nomi alla quale dovreste cercare di adattarvi. Date un'occhiata a perlmodlib 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.

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, è tempo di iniziare a scrivere codice.

Passo passo: Fare il modulo

Iniziare con module-starter oppure h2xs

L'utility module-starter viene distribuita come parte del pacchetto CPAN denominato Module::Starter. Essa crea una directory con parti di tutti i file necessari ad iniziare un nuovo modulo, in conformità 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 Module::Starter, h2xs è uno strumento più vecchio, inteso in origine per lo sviluppo di moduli XS, che si trova come pacchetto nella distribuzione Perl.

Una tipica invocazione di h2xs per un modulo di solo Perl è:

h2xs -AX --skip-exporter --use-new-tests -n Pippo::Pluto 

Il -A omette il codice Autoloader, -X omette gli elementi XS, --skip-exporter omette il codice Exporter, --use-new-tests allestisce un ambiente moderno per i test e -n specifica il nome del modulo.

Usare strict e warnings

Il codice di un modulo deve essere sottoposto a warning e a strict, visto che non potete garantire le condizioni sotto le quali sarà usato. Inoltre, non vorrete comunque distribuire del codice che non sia sottoposto a warning e a strict, vero?

Usare Carp

Il modulo Carp 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 vedrà 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 Carp e sostituendo i vostri warn con dei carp. Se avete la necessità di usare die, dichiarate invece croak. Ad ogni modo, mantenete warn e die al loro posto per i vostri controlli interni - dove il vostro modulo è davvero colpevole.

Usare Exporter - assennatamente!

Exporter vi fornisce un modo standard per esportare simboli e subroutine dal vostro modulo al namespace del chiamante. Per esempio, dire use Net::Acme qw(&gingillo) importerebbe la subroutine gingillo.

La variabile di package @EXPORT determinerà quali simboli saranno esportati quando il chiamante dichiara semplicemente use Net::Acme - difficilmente vorrete metterci qualcosa. @EXPORT_OK, dall'altro lato, specifica quali simboli siete disposti ad esportare. Se volete esportare parecchi simboli, usate gli %EXPORT_TAGS e definite un insieme di esportazione standard - date un'occhiate a Exporter per maggiori dettagli.

Usare la plain old documentation ["semplice vecchia documentazione", NdT]

Il lavoro non è finito fino a che le scartoffie non sono a posto e avrete la necessità di dedicare del tempo a scrivere della documentazione per il vostro modulo. module-starter oppure h2xs vi forniranno uno schema da riempire; se non siete sicuri sul formato, date un'occhiata a perlpod per un'introduzione. Si è 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.

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 effetuerà il build e vi manderà i risultati dei test. Di nuovo, module-starter e h2xs forniranno una infrastruttura per i test che potete estendere - dovrete fare qualcosa di più del semplice controllo che il vostro modulo compili. Test::Simple e Test::More sono dei buoni punti da cui partire quando si sta scrivendo un insieme di programmi di test.

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. Apparirà anche nelle directory principali by-module e by-category ["per modulo" e "per categoria", NdT] se lo avete inserito nella lista dei moduli. È una buona idea mettervi, in dettaglio, quello che il modulo svolge effettivamente, ed i cambiamenti che l'utente può notare dall'ultima versione.

Passo passo: distribuire il vostro modulo

Ottenere un identificativo utente per CPAN

Ogni sviluppatore che pubblica dei moduli su CPAN necessita di un identificativo CPAN. Visitate http://pause.perl.org/, selezionate "Request PAUSE Account" ["Richiesta di un Account PAUSE", NdT] ed aspettate che la vostra richiesta venga approvata dagli amministratori di PAUSE.

perl Makefile.PL; make test; make dist

Ancora una volta, module-starter oppure h2xs hanno fatto tutto il lavoro per voi. Essi producono il Makefile.PL standard che potete vedere quando scaricate e installate dei moduli e questo produce un Makefile con un target di dist.

Una volta che vi siete assicurati che il vostro modulo abbia passato i propri test - è sempre una buona cosa assicurarsene - potete eseguire un make dist e il Makefile, se tutto va bene, produrrà una simpatica tarball [il file creato con l'utility tar, NdT] del vostro modulo, pronto per effettuarne l'upload.

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.

Fare un annuncio sulla lista di discussione sui moduli

Una volta caricato, il modulo resterà 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 apparirà nell'elenco di quelli by-module e by-category su CPAN.

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 comp.lang.perl.announce.

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...

AUTORE

Simon Cozens, simon@cpan.org

Aggiornato da Kirrily "Skud" Robert, skud@cpan.org

CONSULTATE ANCHE

perlmod, perlmodlib, perlmodinstall, h2xs, strict, Carp, Exporter, perlpod, Test::Simple, Test::More ExtUtils::MakeMaker, Module::Build, Module::Starter http://www.cpan.org/ , il tutorial di Ken Williams su come costruire il proprio modulo su http://mathforum.org/~ken/perl_modules.html

TRADUZIONE

Versione

La versione su cui si basa questa traduzione è ottenibile con:

perl -MPOD2::IT -e print_pod perlnewmod

Per maggiori informazioni sul progetto di traduzione in italiano si veda http://pod2it.sourceforge.net/ .

Traduttore

Traduzione a cura di dree.

Revisore

Revisione a cura di Flavio Poletti.

cpanm POD2::IT

perl -MCPAN -e shell
install POD2::IT