perlnewmod – En ligne dans le Cloud

PROGRAMME:

Nom

perlnewmod - préparation d'un nouveau module pour la distribution

DESCRIPTION

Ce document vous donne quelques suggestions sur la manière d'écrire des modules Perl,
les préparer pour la distribution et les rendre disponibles via CPAN.

L’une des choses qui rend Perl vraiment puissant est le fait que les hackers Perl ont tendance à
veulent partager les solutions aux problèmes auxquels ils ont été confrontés, afin que vous et moi n'ayons pas à nous battre
avec le même problème à nouveau.

La principale méthode consiste à abstraire la solution dans un module Perl. Sinon,
Si vous ne savez pas ce qu'est l'un d'entre eux, le reste de ce document ne vous sera pas d'une grande utilité.
Vous manquez également beaucoup de code utile ; pensez à jeter un œil à perlmod,
perlmodlib et perlmodinstall avant de revenir ici.

Lorsque vous constatez qu'il n'existe pas de module disponible pour ce que vous essayez de faire, et
vous avez dû écrire le code vous-même, pensez à regrouper la solution dans un module
et le télécharger sur CPAN afin que d'autres puissent en bénéficier.

Vous devriez également jeter un œil à perlmodstyle pour connaître les meilleures pratiques lors de la création d'un module.

Avertissement
Nous allons ici nous concentrer principalement sur les modules Perl uniquement, plutôt que sur les modules XS.
Les modules ont un objectif assez différent et vous devez prendre en compte des éléments différents avant
leur distribution - la popularité de la bibliothèque que vous collez, la portabilité vers d'autres
systèmes d'exploitation, etc. Cependant, les notes sur la préparation de la partie Perl du module
et son packaging et sa distribution s'appliqueront aussi bien à un module XS qu'à un module Perl pur
une.

Organisateur Ce que devrait I a prendre une développement a module?
Vous devriez créer un module à partir de tout code qui, selon vous, sera utile aux autres.
Tout ce qui est susceptible de combler un vide dans la bibliothèque communale et que quelqu'un d'autre peut
s'intègrent directement dans leur programme. Toute partie de votre code que vous pouvez isoler et extraire
et se connecter à autre chose est un candidat probable.

Prenons un exemple. Imaginons que vous lisiez des données d'un format local dans un hachage de
hachages en Perl, les transformant en un arbre, parcourant l'arbre puis redirigeant chaque nœud vers un
Serveur Acme Transmogrifier.

Maintenant, beaucoup de gens ont l'Acme Transmogrifier, et vous avez dû écrire quelque chose pour
Parlez du protocole à partir de zéro - vous voudriez presque certainement en faire un module.
Le niveau auquel vous le présentez dépend de vous : vous pourriez vouloir des modules au niveau du protocole
analogue à Net::SMTP qui communique ensuite avec des modules de niveau supérieur analogues à Mail::Send.
Le choix vous appartient, mais vous souhaitez obtenir un module pour ce protocole de serveur.

Personne d'autre sur la planète ne parlera de votre format de données local, nous pouvons donc l'ignorer.
Mais qu'en est-il de la chose au milieu ? Construire des structures arborescentes à partir de variables Perl et
alors les parcourir est un joli problème général, et si personne n'a déjà écrit un module
qui fait cela, vous voudrez peut-être modulariser ce code également.

J'espère que vous avez maintenant quelques idées sur ce qu'il est judicieux de modulariser. Voyons voir.
comment c'est fait.

Pas à pas: Préparation le beouf
Avant même de commencer à extraire le code, il y a quelques choses que nous voudrons faire dans
avance.

Regarde autour
Explorez plusieurs modules pour voir comment ils sont écrits. Je suggère de commencer par
Text::Tabs, car il est dans la bibliothèque standard et est agréable et simple, et puis en regardant
à quelque chose d'un peu plus complexe comme File::Copy. Pour le code orienté objet,
Les modules « WWW::Mechanize » ou « Email::* » fournissent de bons exemples.

Ceux-ci devraient vous donner une idée générale de la manière dont les modules sont organisés et écrits.

Vérifiez que c'est nouveau
Il existe de nombreux modules sur CPAN, et il est facile d'en manquer un qui ressemble à ce que
vous prévoyez de contribuer. Passez en revue le
<http://search.cpan.org> et assurez-vous de ne pas être celui qui réinvente la roue !

Discuter du besoin
Vous l'adorerez peut-être. Vous penserez peut-être que tout le monde en a besoin. Mais peut-être pas.
existe-t-il une réelle demande ? Si vous n'êtes pas certain de la demande,
le module aura, pensez à envoyer des sondes sur les « comp.lang.perl.modules »
groupe de discussion, ou en dernier recours, demandez la liste des modules à "[email protected]". Souviens-toi
qu'il s'agit d'une liste fermée avec un délai d'exécution très long - soyez prêt à attendre un
ça va prendre un bon moment pour une réponse de leur part.

Choisissez un nom
Les modules Perl inclus sur CPAN ont une hiérarchie de nommage à laquelle vous devez essayer de vous conformer.
Consultez perlmodlib pour plus de détails sur son fonctionnement et parcourez CPAN et le
Consultez la liste des modules pour vous en faire une idée. Au minimum, rappelez-vous ceci : les modules doivent être
titre en majuscule, (This::Thing) s'inscrit dans une catégorie et explique son objectif
succinctement.

Revérifier
Pendant que vous faites cela, assurez-vous vraiment que vous n'avez pas manqué un module similaire au
celui que vous êtes sur le point d'écrire.

Lorsque vous avez choisi votre nom et que vous êtes sûr que votre module est recherché et non
actuellement disponible, il est temps de commencer à coder.

Pas à pas: Fabrication le module
Préparer : module-démarreur or h2xs
Le manuel de formation module-démarreur L'utilitaire est distribué dans le cadre du package CPAN Module::Starter.
Il crée un répertoire avec des stubs de tous les fichiers nécessaires pour démarrer un nouveau module,
conformément aux « meilleures pratiques » récentes pour le développement de modules, et est invoqué à partir du
ligne de commande, donc :

module-starter --module=Foo::Bar \
--author="Votre nom" --email=[email protected]

Si vous ne souhaitez pas installer le package Module::Starter à partir de CPAN, h2xs est un plus vieux
outil, initialement destiné au développement de modules XS, fourni avec
la distribution Perl.

Une invocation typique de h2xs pour un module Perl pur est :

h2xs -AX --skip-exporter --use-new-tests -n Foo::Bar

Le "-A" omet le code Autoloader, "-X" omet les éléments XS, "--skip-exporter" omet le
Le code d'exportation, « --use-new-tests », configure un environnement de test moderne et « -n »
spécifie le nom du module.

Utiliser des avertissements stricts
Le code d'un module doit être un avertissement et strictement propre, car vous ne pouvez pas garantir la
conditions d'utilisation. De plus, il est déconseillé de distribuer du code qui
ce n'était pas un avertissement ou un nettoyage strict de toute façon, n'est-ce pas ?

Utiliser la carpe
Le module Carp vous permet de présenter vos messages d'erreur depuis l'appelant
perspective ; cela vous donne un moyen de signaler un problème avec l'appelant et non avec votre
module. Par exemple, si vous dites ceci :

avertir « Aucun nom d'hôte n'est donné » ;

l'utilisateur verra quelque chose comme ceci :

Aucun nom d'hôte n'est donné dans /usr/local/lib/perl5/site_perl/5.6.0/Net/Acme.pm
ligne 123.

Il semblerait que votre module fasse quelque chose d'anormal. Il est préférable de placer le
blâmer l'utilisateur et dire ceci :

Aucun nom d'hôte n'est donné dans bad_code, ligne 10.

Pour cela, utilisez Carp et remplacez vos « warn » par des « carp ». Si nécessaire,
« mourir », dites plutôt « croasser ». Cependant, gardez « avertir » et « mourir » à l'endroit pour votre santé mentale.
vérifications - où c'est vraiment votre module qui est en cause.

Utilisez Exporter - judicieusement !
Exporter vous offre un moyen standard d'exporter des symboles et des sous-routines à partir de votre module
dans l'espace de noms de l'appelant. Par exemple, dire « use Net::Acme qw(&frob) »
importer la sous-routine « frob ».

La variable de package @EXPORT déterminera quels symboles seront exportés lorsque le
l'appelant dit simplement « utiliser Net::Acme » - vous ne voudrez presque jamais rien mettre dedans
là. @EXPORT_OK, d'autre part, spécifie quels symboles vous êtes prêt à exporter.
Si vous souhaitez exporter un ensemble de symboles, utilisez %EXPORT_TAGS et définissez une norme
ensemble d'exportation - consultez Exporter pour plus de détails.

Utiliser une documentation simple et ancienne
Le travail n'est pas terminé tant que les formalités administratives ne sont pas terminées, et vous devrez les mettre en place.
un peu de temps pour écrire de la documentation pour votre module. « module-starter » ou « h2xs »
fournir un stub à remplir ; si vous n'êtes pas sûr du format, consultez perlpod
pour une introduction. Fournissez un bon résumé de la façon dont votre module est utilisé dans le code,
description, puis notes sur la syntaxe et la fonction des sous-routines individuelles ou
méthodes. Utilisez les commentaires Perl pour les notes des développeurs et POD pour les notes des utilisateurs finaux.

Écrire des tests
Nous vous encourageons à créer des auto-tests pour votre module afin de vous assurer qu'il fonctionne comme prévu.
prévu sur la myriade de plateformes prises en charge par Perl ; si vous téléchargez votre module sur CPAN, un
Une équipe de testeurs construira votre module et vous enverra les résultats des tests.
« module-starter » et « h2xs » fournissent un cadre de test que vous pouvez étendre ; vous devriez
faire plus que simplement vérifier que votre module compile. Test::Simple et
Test::More sont de bons points de départ pour écrire une suite de tests.

Écrire le fichier README
Si vous téléchargez sur CPAN, les gremlins automatisés extrairont le fichier README et
Placez-le dans votre répertoire CPAN. Il apparaîtra également dans le répertoire principal. par module et par-
category répertoires si vous êtes dans la liste des modules. C'est une bonne idée de les placer ici.
ce que fait réellement le module en détail, et les changements visibles par l'utilisateur depuis la dernière
libérer.

Pas à pas: Distribuer votre module
Obtenir un identifiant utilisateur CPAN
Chaque développeur publiant des modules sur CPAN a besoin d'un identifiant CPAN. Visitez
"http://pause.perl.org/", sélectionnez « Demander un compte PAUSE » et attendez que votre demande soit
être approuvé par les administrateurs de PAUSE.

"perl Makefile.PL; faire un test; faire une distribution"
Une fois de plus, « module-starter » ou « h2xs » a fait tout le travail pour vous. Ils produisent
"Makefile.PL" standard que vous voyez lorsque vous téléchargez et installez des modules, et cela produit
un Makefile avec une cible « dist ».

Une fois que vous vous êtes assuré que votre module réussit ses propres tests - c'est toujours une bonne chose à faire
bien sûr - vous pouvez "make dist", et le Makefile vous produira, espérons-le, une belle archive tar
de votre module, prêt à être téléchargé.

Télécharger l'archive tar
L'e-mail que vous avez reçu lorsque vous avez reçu votre identifiant CPAN vous indiquera comment vous connecter à PAUSE,
le serveur de téléchargement des auteurs Perl. Depuis les menus, vous pouvez télécharger votre module vers
CPAN.

Annoncer à la liste des modules
Une fois téléchargé, il restera invisible dans votre répertoire d'auteurs. Si vous souhaitez le connecter,
Pour accéder au reste du CPAN, vous devrez aller dans « Enregistrer l'espace de noms » sur PAUSE. Une fois
enregistré, votre module apparaîtra dans les listes par module et par catégorie sur CPAN.

Annoncer au clpa
Si vous avez un désir ardent d'annoncer au monde votre sortie, publiez une annonce
au groupe de discussion modéré « comp.lang.perl.announce ».

Corriger les bugs!
Une fois que vous aurez commencé à accumuler des utilisateurs, ils vous enverront des rapports de bugs. Avec un peu de chance,
Ils vous enverront même des correctifs. Bienvenue dans les joies de la maintenance d'un projet logiciel…

Utiliser perlnewmod en ligne avec les services onworks.net