Distribuer votre module sur le CPAN

Une introduction à la publication de modules Perl sur le CPAN.

Transcript

1. 2010-06-11 Journées Perl 2010 Olivier Mengué Paris.pm dolmen@cpan.org http://o.mengue.free.fr/ Distribuer votre module sur le CPAN
2. 2010-06-11 Journées Perl 2010 2 Olivier Mengué - dolmen@cpan.org http://search.cpan.org/~dolmen/ 2010? Number::Phone::FR 2010 Parse::nm 2009 POE::Component::Schedule 2009 Acme::PM::Paris::Meetings 2005 Text::FixedLengthMultiline ~ 100 rapports de bugs sur des modules du CPAN ~ 20 patchs http://o.mengue.free.fr/presentations/
3. 2010-06-11 Journées Perl 2010 3 Le CPAN 20469 distributions 133665 4883 auteurs 1000 uploads/mois 500 auteurs chaque mois
4. 2010-06-11 Journées Perl 2010 4 Glossaire Module : un package public, dans un fichier .pm, documenté L'implémentation peut nécessiter d'autres packages secondaires Script : un programme Perl, exécutable extension .pl facultative POD : la documentation de votre code, embarquée ou séparée dans un fichier .pod Distribution 0..n modules 0..n scripts Métadonnées Tout ce qu'il faut pour installer le module/script Tout ce qu'il faut pour construire une nouvelle distribution
5. 2010-06-11 Journées Perl 2010 5 Une distribution scripts/ : scripts (avec ou sans .pl) lib/ : modules (.pm) De la documentation README Changes / ChangeLog POD Une licence d'utilisation Un script d'installation : Makefile.PL / Build.PL Des métadonnées : MANIFEST META.yml Une suite de test Cette structure est utilisable également pour vos distributions privées (en dehors du CPAN, le DarkPAN)
6. 2010-06-11 Journées Perl 2010 6 PAUSE : Perl Authors Upload SErver https://pause.perl.org/ Créez votre identifiant d'auteur CPAN Request PAUSE account Les pages importantes : Login Upload a file to CPAN Delete file
7. 2010-06-11 Journées Perl 2010 7 Votre page : http://search.cpan.org/~pauseid/
8. 2010-06-11 Journées Perl 2010 8 Votre page : cpan.uwinipeg.ca
9. 2010-06-11 Journées Perl 2010 9 L'environnement de travail Archivez vos fichiers ! Un bon module est un module qui est maintenu Git, Subversion, Mercurial, CVS... Publiez un serveur public Collaboration Suivi par vos utilisateurs
10. 2010-06-11 Journées Perl 2010 10 Script d'installation ExtUtils::MakeMaker : Makefile.PL l'ancêtre, disponible partout nécessite « make » Module::Build : Build.PL dans le core seulement depuis 5.10 assez populaire, donc cette dépendance n'est plus un pb fonctionne mieux sous Windows très bien maintenu mon favori Module::Install : Makefile.PL embarqué dans votre distribution => alourdi basé sur EU::MM
11. 2010-06-11 Journées Perl 2010 11 Build.PL # Voir Module::Build::Authoring use Module::Build; Module::Build->new( module_name => 'Mon::Module', dist_author => 'Prénom Nom <pauseid@cpan.org>', license => 'perl', requires => { 'Module' => 'version', ... }, build_requires => { 'Test::More' => '0.94', }, )->create_build_script;
12. 2010-06-11 Journées Perl 2010 12 Les dépendances requires pour le fonctionnement une fois installé config_requires pour l'exécution de « perl Build.PL » (généralement vide) build_requires pour l'exécution de « ./Build », « ./Build test » build_recommends pour des tests plus poussés ; votre build doit savoir s'en passer N'indiquez pas dans requires/build_requires des modules qui ne sont nécessaires qu'à vous en tant qu'auteur
13. 2010-06-11 Journées Perl 2010 13 MANIFEST : la liste des fichiers Laissez M::I / EU::MM le construire Mais dites-lui quoi ignorer : regexps dans MANIFEST.SKIP ^.git \B.svn\b .tar.gz$ ^_build\b ^Build$ ^Build.bat$ ^Makefile$ ^cover_db\b \bcore$ MYMETA.yml Ignorez aussi les fichiers pour votre $EDITOR .gitignore
14. 2010-06-11 Journées Perl 2010 14 perl Build.PL ./Build manifest crée MANIFEST ./Build crée blib/ ./Build distmeta crée META.yml ./Build dist crée Distribution-version.tar.gz => upload ./Build disttest ./Build testcover crée cover_db. Voir cover_db/coverage.html
15. 2010-06-11 Journées Perl 2010 15 Numéros de versions Choisissez un schéma et tenez vous-y Format assez libre, mais évitez les fantaisies ! our $VERSION = '#.##' dans vos modules et scripts Utilisez le même numéro pour votre module et votre distribution CPAN reconnaît deux types de versions : Publiques Développeur version développeur : #.##_## (le '_' fait la différence) masquées sur search.cpan.org et dans le shell CPAN ls DOLMEN install DOLMEN/Parse-nm-0.04_90.tar.gz à utiliser pour publier une pré-version Pour répondre rapidement à un bug Et vérifier les résultats CPAN Testers
16. 2010-06-11 Journées Perl 2010 16 Votre suite de tests automatisés : t/*.t Tests de votre module Votre suite de test borne ce qui est permis Elle montre à vos utilisateurs comment utiliser votre module Les cas où ça fonctionne Les cas où ça ne doit pas fonctionner « Build testcover » pour vérifier la couverture de votre suite Tests de votre distribution, avant publication Numéro de version, couverture de la documentation, fichiers de base Ces tests ne doivent pas bloquer un utilisateur qui installe votre distribution => conditionnels si RELEASE_TESTING=1 Un minimum : Test::Distribution
17. 2010-06-11 Journées Perl 2010 17 L'upload Sur PAUSE Surveillez vos mails dans les 15 minutes qui suivent Erreurs sur votre distribution Au bout de quelques heures votre distribution apparaît sur search.cpan.org
18. 2010-06-11 Journées Perl 2010 18 search.cpan.org Vous donne pour votre module les liens utiles : La doc en ligne (perldoc) Les bugs ouverts sur rt.cpan.org Les rapports CPANTesters uwinipeg.ca vous donne encore plus de liens : Les rapports de build ActivePerl (Windows)
19. 2010-06-11 Journées Perl 2010 19 Pourquoi distribuer sur le CPAN ? Votre ID PAUSE vous donne un alias mail @cpan.org Un feedback rapide et automatique sur la portabilité de votre distribution sur des dizaines de plateformes dans les 48h après un upload : CPAN Testers reports : cpantesters.org Windows : rapports ActiveState Un bugtracker : rt.cpan.org Même authentification pour toutes les distributions du CPAN => facile pour vous et vos utilisateurs Soumission par le web ou par mail Pour vos utilisateurs : Installation directe avec les dépendances via les shells Un archivage jusqu'à la fin des temps : BackPAN
20. 2010-06-11 Journées Perl 2010 20 Plus d'infos http://articles.mongueurs.net/magazines/linuxmag69.html Dist::Zilla Module::Build::Authoring
21. 2010-06-11 Journées Perl 2010 21 Questions ? Olivier Mengué dolmen@cpan.org http://o.mengue.free.fr/