Distribuer votre module sur le CPAN - Olivier Mengué

Distribuer votre module sur le
CPAN
Journées Perl 2010
2010-06-11
Olivier Mengué
Paris.pm
[email protected]
http://o.mengue.free.fr/
Olivier Mengué - [email protected]
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/
2010-06-11
Journées Perl 2010
2
Le CPAN
20469 distributions
133665
4883 auteurs
1000 uploads/mois
500 auteurs chaque mois
2010-06-11
Journées Perl 2010
3
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
2010-06-11
Journées Perl 2010
4
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)
2010-06-11
Journées Perl 2010
5
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
2010-06-11
Journées Perl 2010
6
Votre page : http://search.cpan.org/~pauseid/
2010-06-11
Journées Perl 2010
7
Votre page : cpan.uwinipeg.ca
2010-06-11
Journées Perl 2010
8
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
2010-06-11
Journées Perl 2010
9
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
2010-06-11
Journées Perl 2010
10
Build.PL
# Voir Module::Build::Authoring
use Module::Build;
Module::Build->new(
module_name => 'Mon::Module',
dist_author => 'Prénom Nom <[email protected]>',
license => 'perl',
requires => {
'Module' => 'version',
...
},
build_requires => {
'Test::More' => '0.94',
},
)->create_build_script;
2010-06-11
Journées Perl 2010
11
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
2010-06-11
Journées Perl 2010
12
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
2010-06-11
Journées Perl 2010
13
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
2010-06-11
Journées Perl 2010
14
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
2010-06-11
Pour répondre rapidement à un bug
Et vérifier les résultats CPAN Testers
Journées Perl 2010
15
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
2010-06-11
Journées Perl 2010
16
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
2010-06-11
Journées Perl 2010
17
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)
2010-06-11
Journées Perl 2010
18
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
2010-06-11
Journées Perl 2010
19
Plus d'infos
http://articles.mongueurs.net/magazines/linuxmag69.html
Dist::Zilla
Module::Build::Authoring
2010-06-11
Journées Perl 2010
20
Questions ?
Olivier Mengué
[email protected]
http://o.mengue.free.fr/
2010-06-11
Journées Perl 2010
21