perlnewmod - preparare un nuovo modulo per distribuirlo
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.
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.
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.
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.
- 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.
- 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...
Simon Cozens, simon@cpan.org
Aggiornato da Kirrily ``Skud'' Robert, skud@cpan.org
perlmod, perlmodlib, perlmodinstall, h2xs, strict,
Carp, Exporter, perlpod, the Test::Simple manpage, the Test::More manpage
the ExtUtils::MakeMaker manpage, the Module::Build manpage, the Module::Starter manpage
http://www.cpan.org/ , il tutorial di Ken Williams su come costruire
il proprio modulo su http://mathforum.org/~ken/perl_modules.html
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/ .
Traduzione a cura di dree.
Revisione a cura di Flavio Poletti.
Mon Jun 11 22:02:17 2012
|
