Créer une distribution

Après ce rapide tour d'horizon, passons aux choses sérieuses et aux moyens pour créer une distribution.

h2xs

La manière officielle de créer un nouveau module est d'utiliser le programme h2xs(1). Il est présent depuis fort longtemps dans la distribution Perl, mais il est en réalité assez mal employé. En effet, comme son nom l'indique, h2xs sert avant tout à créer des modules d'extensions en XS à partir des fichiers d'en-têtes d'une bibliothèque C (fichiers .h). Son intérêt est qu'il est capable de générer la majeure partie du code XS de manière automatique, libérant ainsi le programmeur Perl de cette pénible tâche.

Toutefois comme les auteurs de modules pur Perl voulaient bénéficier du squelette de distribution qu'il construisait pour les modules XS, une option a été ajoutée afin de ne pas générer de code XS. Son utilisation dans ce cas-ci ressemble à ceci :

    $ h2xs -XAn Acme::GreatModule
    Writing Acme/GreatModule/GreatModule.pm
    Writing Acme/GreatModule/Makefile.PL
    Writing Acme/GreatModule/test.pl
    Writing Acme/GreatModule/Changes
    Writing Acme/GreatModule/MANIFEST

Examinons un peu le début de distribution qu'il vient de nous créer. La première constatation est que l'arborescence Acme/GreatModule/ est un peu inutile, on s'attend plutôt à trouver Acme-GreatModule/. De plus, il place le fichier GreatModule.pm à la racine de la distribution, alors qu'il est plus propre de le placer dans une arborescence lib/Acme/. Pour un seul module, ce n'est pas très grave, mais quand d'autres modules viennent s'ajouter au premier, cela peut rapidement devenir fouillis !

Autre défaut, le code d'exemple dans le fichier GreatModule.pm a tendance à inclure beaucoup de choses inutiles comme une contrainte sur la version de Perl et l'utilisation d'Exporter alors que nous ne lui avons rien demandé. Encore une fois, rien de dramatique, mais comme la plupart des modules Perl développés aujourd'hui offrent une interface objet, un auteur passe finalement déjà trop de temps à effacer tous ces trucs inutiles (et à modifier Makefile.PL pour prendre en compte ces modifications). Enfin il n'y a pas de fichier README ni d'information de droit d'auteur et de licence.

Le h2xs des versions récentes de Perl (5.8.x) a un peu amélioré les choses : un fichier README est généré avec le squelette pour ajouter le copyright et la licence, et le test de base (le chargement du module) est déplacé dans le répertoire t/. Toutefois il génère toujours par défaut une contrainte sur la version de Perl en cours (donc 5.8). Cela peut se changer avec l'option -b, mais il faut y penser.

Pour résumer, h2xs a l'avantage d'être présent dans toute distribution de Perl, et s'il peut suffire dans le cas de modules simples pur Perl, il peut rapidement fatiguer l'auteur de nombreux modules.

Script personnalisé

Après un tel réquisitoire contre h2xs, certains vont demander si la solution est d'écrire son petit script Perl ou shell qui génère les fichiers et qui... La réponse est : NON !

Non, parce que ce script sera forcément faux ou incomplet.

Non, parce qu'il y a déjà une meilleure solution.

module-starter

Pour pallier cette épine qui se faisait de plus en plus sentir dans la communauté Perl, Andy Lester a développé un programme qui fait ça de manière propre et complète, module-starter. Ses avantages par rapport à h2xs sont qu'il est prévu pour créer le squelette d'une distribution, qu'il le fait de manière propre et moderne, et qu'en plus il gère Module::Build. Son inconvénient est qu'il n'est pas installé par défaut, mais comme il n'est utile que pour l'auteur d'un module et non pas son utilisateur, il ne faut pas hésiter à l'installer :

    $ sudo perl -MCPAN -e'install Module::Starter'

Son utilisation est tout aussi simple que ne l'est h2xs, si ce n'est qu'on fournit le nom et l'adresse email de l'auteur dès la création de la distribution (ce qui évite d'éditer moults fichiers) et qu'on peut spécifier plusieurs modules :

    $ module-starter --module=Acme::GreatModule,Acme::SecondGreat \
        --author="Jean Suifier" --email="jean@suifier.net"
    Created starter directories and files

module-starter crée cette arborescence :

  Acme-GreatModule/
    Changes
    MANIFEST
    Makefile.PL
    README
    lib/
      Acme/
        GreatModule.pm
        SecondGreat.pm
    t/
      00.load.t
      pod-coverage.t
      pod.t

On constate que c'est déjà bien mieux rangé, les fichiers .pm sont dans une arborescence dans lib/, et plusieurs tests sont présents dans t/. On peut éventuellement regretter le fait que les tests utilisent Test::More (qui n'a été intégré à Perl qu'à partir de 5.8), mais on peut facilement remédier à cela.

Les squelettes de modules générés utilisent le mode de documentation mixé, c'est-à-dire que la documentation de chaque fonction est située juste à côté de sa définition. Le code Perl et la documentation Pod s'entremêlent donc tout au long du fichier. Certains apprécient le fait que la documentation soit aussi près du code concerné, d'autres préfèrent la conserver tout à la fin, après __END__ pour des raisons de performances. En effet, l'interpréteur doit sauter chaque passage entre les balises =pod et =cut, mais d'un autre côté, ce coût est très minime et n'est payé qu'à la compilation, pas à l'exécution. Au final, il s'agit donc surtout d'une question de goût personnel.

Autre aspect intéressant, module-starter tente dès le départ de vous forcer à fournir un module propre et documenté en incluant les tests de vérification du Pod (fichier t/pod.t) et de couverture de documentation (fichier t/pod-coverage.t). Le premier vérifie simplement que votre documentation Pod ne contient pas d'erreurs de balisage, alors que le second vérifie que vous avez bien documenté toutes les fonctions et méthodes définies dans chaque module, sous réserve que vous installiez Test::Pod et Test::Pod::Coverage, ce que vous devriez faire dès maintenant.

En résumé, module-starter est vraiment l'outil que vous devez utiliser. Mais pour être tout à fait honnête, la comparaison entre module-starter et h2xs est nécessairement défavorable à ce dernier : la création d'un squelette de distribution n'est pas son véritable rôle, qui est la création de fichiers XS (rôle qu'il remplit très bien d'ailleurs), alors que module-starter a été écrit spécifiquement pour ça.

Modules de construction et d'installation

L'introduction de Module::Build a créé une certaine agitation dans la communauté Perl, car CPAN.pm (le module, pas le réseau) ne connaissant que ExtUtils::MakeMaker, les distributions ne comportant qu'un fichier Build.PL ne pouvaient pas être installées par ce biais si commode. Il s'agit en réalité d'un faux problème qui montre que beaucoup d'auteurs ne se sont pas rendus compte que l'utilisation de l'un n'est pas exclusive de l'autre. Plus précisément, il est parfaitement possible pour l'auteur d'utiliser le moderne Module::Build pour programmer ses modules et construire sa distribution tout en fournissant un Makefile.PL pour que CPAN.pm puisse l'installer sans se poser de questions.

Voyons immédiatement comment faire en reprenant l'exemple de tout à l'heure. Comme nous ne lui avions pas spécifié un module de construction particulier, un builder, il a automatiquement utilisé ExtUtils::MakeMaker. On peut lui indiquer le builder à utiliser avec les options suivantes :

  --builder=module Build with 'ExtUtils::MakeMaker' or 'Module::Build'
  --eumm           Same as --build=ExtUtils::MakeMaker
  --mb             Same as --build=Module::Build

On peut même lui indiquer d'utiliser les deux en même temps. La création d'une distribution utilisant les deux builders devient alors triviale :

    $ module-starter --module=Acme::GreatModule,Acme::SecondGreat \
        --author="Jean Suifier" --email="jean@suifier.net" --eumm --mb

module-starter crée alors les deux fichiers Build.PL et Makefile.PL avec les bons paramètres (et l'astuce permettant aux deux de cohabiter).

En réalité, module-starter ne permettait pas au départ d'utiliser les deux builders, mais suite aux suggestions de l'auteur, Andy Lester a gentiment accepté d'ajouter ces fonctionnalités dans module-starter version 1.00, ce qui vous permet, chers lecteurs, de rester paresseux et d'éviter de devoir bidouiller des trucs inutiles et ennuyeux ;-).

Notez que vous pouvez déjà construire votre distribution (avec Build.PL ou Makefile.PL, au choix) sans devoir éditer aucun fichier ! Pas question de distribuer une archive ne contenant rien d'utile, mais cela vous montre que tout le travail ennuyeux de préparation de la distribution a déjà été effectué, vous pouvez donc vous concentrer sur l'écriture de votre module. La première exécution de l'un des builders affichera un avertissement sur le fait que META.yml est manquant. C'est normal, il sera automatiquement créé lorsque vous construirez la distribution. Voyons d'ailleurs comment faire.

Lorsque vous exécutez perl Makefile.PL ou perl Build.PL, ces programmes créent un builder, respectivement Makefile et Build. Les deux offrent les mêmes actions, exécutées avec make action ou ./Build action.

help - donne la liste des actions disponibles.
build - action par défaut si aucune n'est spécifiée; elle copie les fichiers .pm, compile les fichiers .xs et génère la documentation.
test - exécute les tests unitaires.
dist - construit la distribution et crée l'archive .tar.gz, prête à être déposée sur le CPAN.
disttest - construit la distribution et exécute dans le répertoire créé l'un de Build.PL ou Makefile.PL, puis exécute les actions build et test.
distmeta - (disponible seulement avec Module::Build); génère le fichier META.yml.
manifest - met à jour le fichier MANIFEST par rapport aux fichiers présents dans l'arborescence.

Quelques détails en plus sur l'action manifest. Elle permet de mettre à jour automatiquement le fichier MANIFEST en examinant l'arborescence courante, et en vérifiant si le nom ne correspond pas aux expressions régulières présentes dans MANIFEST.SKIP. Voici un bon point de départ pour un fichier MANIFEST.SKIP :

    # fichiers et répertoires de CVS, RCS, et autres
    /CVS/
    ^.cvsignore$

    # fichiers et répertoires générés par les builders
    ^blib
    ^_build
    ^Build$
    ^cover_db
    ^Makefile(\.old)?$
    ^MANIFEST\.
    ^pm_to_blib$

    # fichiers temporaires, de backup, etc
    ~$
    \.bak$
    \.old$
    \.sw[a-z]$

Lors de la construction d'une distribution, un auteur va typiquement exécuter les commandes suivantes (l'exemple est ici donné avec Module::Build) :

    $ perl Build.PL
    $ ./Build
    $ ./Build test
    $ ./Build disttest
    $ ./Build dist

Vous devez alors obtenir une archive correctement nommée, dans notre exemple Acme-GreatModule-0.01.tar.gz, prête à être déposée sur le CPAN ou à être installée sur une autre machine par les commandes habituelles.

La documentation

Si vous voulez que votre module soit apprécié, vous devez le documenter correctement. C'est d'ailleurs une conséquence logique de la première vertu du programmeur, la Paresse, qui pousse à écrire une documentation complète afin d'éviter de devoir répondre inlassablement aux mêmes questions (ou de pouvoir se contenter de jeter un « lisez ce foutu manuel » aux utilisateurs les plus ennuyeux). Comme vous avez été de bons élèves, vous avez utilisé module-starter pour créer votre distribution, et celui-ci, respectant votre paresse, a déjà écrit un squelette de documentation. Vous n'avez plus qu'à compléter le fichier README et à écrire la documentation de votre module au fur et à mesure de son développement.

Gardez à l'esprit que quand votre module sera diffusé (en particulier sur search.cpan.org), des liens seront créés au sein de la documentation, permettant de relier les différentes pages entre elles. En particulier, n'hésitez pas à indiquer les modules similaires ou associés (ou les dépendances) dans la section SEE ALSO. Cela facilitera la vie de l'utilisateur de votre module, et donc la vôtre.

Pensez à préciser de manière explicite votre droit d'auteur et la licence d'utilisation de votre module dans tous les fichiers qui seront installés. Par défaut, module-starter (ainsi que h2xs) ont déjà rempli pour vous la partie sur le droit d'auteur (section COPYRIGHT), mais vous pouvez être amenés à la modifier ou la compléter suivant les cas (développement au sein d'une société par exemple).

La licence est par défaut celle de Perl, qui est constituée de la disjonction de l'Artistic License (licence artistique) et de la GNU General Public License (licence publique générale du GNU). Vous pouvez spécifier une autre licence libre (LGPL, BSD révisée) ou non-libre. Dans tous les cas, vous devez ajouter un fichier LICENSE qui spécifie explicitement les termes de la licence d'utilisation. Un petit rappel : licence (avec un c) est le mot français, license (avec un s) est le mot anglais.

D'ailleurs, souvenez-vous que la communauté Perl est mondiale, et que la plupart des personnes s'attendront donc à pouvoir lire la documentation en anglais. Cela n'interdit pas d'inclure aussi une version française, mais la politesse conseille toutefois d'écrire un minimum de documentation (au moins le README) en anglais, afin que les non-francophones aient une chance de savoir à quoi sert votre module.

Le numéro de version

Comme tout logiciel qui se respecte, votre module doit avoir un numéro de version. En Perl, il est toutefois demandé d'utiliser des numéros de versions à deux composantes plutôt qu'à trois, ceci pour des raisons techniques. En effet un numéro de version à deux composantes peut être vu comme un nombre flottant, ce qui simplifie la comparaison. Pour cette raison, les versions des modules Perl suivent généralement un format V.RR, où V est le numéro de version majeur et RR (ou RRR) est le numéro de release, de distribution. Vous pouvez aussi ajouter le suffixe _DD pour signaler une version de développement.

Prenons quelques exemples pour mieux comprendre. Notre ami Jean Suifier distribue une première version de son module Acme::GreatModule, qu'il numérote 0.01. Ayant un bon retour de la part des utilisateurs, il continue et distribue une version de développement 0.01_01, qui indique qu'elle est basée sur la version 0.01. Il peut ainsi distribuer plusieurs versions beta 0.01_02, 0.01_03, avant de distribuer une version 0.02 finale.

Pour une distribution comportant plusieurs modules, il est généralement conseillé de donner un numéro de version séparé à chaque module, la distribution ayant comme version celle du module principal. Vous pouvez complètement décorréler la version de la distribution de la version des modules inclus en supprimant le paramètre dist_version_from de Build.PL et en le remplaçant par dist_version, avec comme valeur la version. Pour Makefile.PL on fait de même en remplaçant VERSION_FROM par VERSION.

À noter toutefois qu'il est déconseillé d'utiliser le numéro de révision CVS (ou de votre système de gestion de versions) comme valeur pour $VERSION car cela peut engendrer des résultats bizarres (en particulier lorsqu'un programme existe dans plusieurs branches).

Nous verrons plus loin en quoi attribuer un numéro de version unique à chaque nouvelle release est important.

Les tests automatisés

L'un des points forts du système d'installation des modules Perl est le support, lors de la procédure d'installation, d'une phase de tests automatiques permettant de vérifier le bon fonctionnement du ou des modules sur la machine cible avant l'installation proprement dite. Ces tests unitaires ont un protocole de déroulement très simple et codifié dans la documentation du module Test::Harness. Ce module est utilisé par le builder pour exécuter les tests qui doivent se trouver dans des fichiers .t dans le répertoire t/. Test::Harness attend de ces programmes qu'ils affichent simplement l'état de chaque test, "ok" ou "not ok", suivi du numéro du test. Ces programmes peuvent être réalisés de manière complètement indépendante de tout module Perl, mais il est conseillé d'utiliser l'un des modules Test ou Test::More, qui offrent des fonctions pour faciliter grandement le travail et évite de devoir connaître les subtilités du protocole de dialogue.

Ces deux modules offrent comme fonctionnalités de base la fonction ok() dont le but est d'afficher "ok" ou "not ok" en fonction de la valeur des arguments. Voyons immédiatement un exemple :

    use Test;
    use Acme::GreatModule;

    plan tests => 2;

    # est-ce que $VERSION est défini ?
    ok( $Acme::GreatModule::VERSION );

    # est-ce que $VERSION est un numéro de version valide ?
    ok( $Acme::GreatModule::VERSION =~ /^\d+\.\d+(?:_\d{2})?$/ );

Juste après l'utilisation du module Test (ou Test::More) on trouve la déclaration du plan prévu, qui indique le nombre de tests qui seront effectués. Ensuite on charge le module qui doit être testé et on vérifie qu'il a bien défini un numéro de version, puis que celui-ci correspond bien à un numéro de version Perl. Vous l'aurez deviné, ok() affiche "ok" si l'expression qu'on lui donne est vraie, et "not ok" dans le cas contraire. On peut aussi utiliser la forme à deux arguments de ok(), pour lui laisser faire la comparaison :

    # est-ce que $PI a la bonne valeur ?
    ok( $PI, 4 * atan2(1,1) );

Test fournit aussi une fonction skip() pour passer des tests qui ne peuvent pas être exécutés (parce qu'il manque un module, parce que la plate-forme ne supporte pas certaines fonctionnalités, etc). Test::More fournit d'autres fonctions qui offrent des sémantiques plus pointues que ok(), telles que is() et isnt() pour tester si une valeur est égale ou différente d'une autre, like() pour vérifier qu'une valeur correspond à une expression régulière, is_deeply() pour vérifier si deux structures complexes sont identiques à tous les niveaux.

À noter que le répertoire t/ permet d'inclure des modules et des fichiers qui ne seront utilisés que pour les tests, et qui ne seront pas indexés (ce point sera développé plus loin). En particulier, cela signifie que vous pouvez sans risque inclure une copie des modules Test et Test::More dans t/, afin de ne pas créer de dépendances artificielles.

Dernier point intéressant à connaître pour ce rapide tour des tests de votre module : la couverture de code, c'est-à-dire vérifier que les tests mis en place exécutent réellement l'ensemble du code des modules testés. Le module Perl Devel::Cover permet justement de vérifier cet aspect. Et son utilisation est rendue encore plus simple qu'elle ne l'est naturellement grâce à Module::Build qui offre depuis la version 0.25_01 une action testcover. L'exécution de ./Build testcover exécutera donc la suite de tests en chargeant Devel::Cover et générera un rapport HTML très lisible dans cover_db/coverage.html. Le programmeur orgueilleux sera alors tenté (avec raison) d'écrire des tests pour avoir une couverture maximale.

Tester la distribution

Les scripts de tests peuvent (et doivent) être utilisés pour tester tous les aspects possibles de votre distribution. Cela concerne aussi bien le code du module fourni (vérifier qu'il se comporte comme attendu), que des aspects plus extérieurs : présence de tous les fichiers, vérification du POD, des dépendances, etc. module-starter a déjà créé certains scripts de tests, t/00.load.t pour vérifier que le module se charge bien, t/pod.t pour vérifier que le POD est correct et t/pod-coverage.t pour vérifier que la documentation couvre bien toutes les fonctions définies.

On peut ensuite ajouter les vérifications fournies par Test::Distribution qui examine plusieurs points. Pour l'utiliser, il suffit d'ajouter le script t/distchk.t :

    use strict;
    use Test::More;
    eval "use Test::Distribution";
    plan skip_all => "Test::Distribution required for checking distribution" if $@;

Évidemment, il est plus que fortement conseillé d'installer tous les modules utilisés par ces scripts de tests pour qu'ils soient utiles, à savoir Test::Pod, Test::Pod::Coverage, Test::Distribution, ainsi que toutes leurs dépendances. Avec le shell cpan, il suffit de confirmer leur installation.

Portabilité

Un auteur avisé doit garder ce point à l'esprit : Perl est portable, et porté sur beaucoup de systèmes aux caractéristiques très différentes. Il doit donc en tenir compte lorsqu'il écrit un module. Nous ne nous attarderons pas ici sur les problèmes de portabilité liés aux fonctionnalités de Perl (par exemple la disponibilité de fonctions comme fork()), mais aux problèmes sur les noms de fichiers, cet article traitant de la manière de créer une distribution. Pour les autres aspects de portabilité, le lecteur est invité à consulter perlport[3].

En effet, les systèmes d'exploitation ne sont pas tous égaux (et sont même très différents) sur les noms de fichiers valides. Voici donc quelques conseils pour éviter de vous attirer les récriminations d'utilisateurs mécontents.

Ne mettez jamais dans le même répertoire deux fichiers dont le nom ne diffère que par la casse (majuscules-minuscules) comme test.pl et Test.PL. Plusieurs systèmes d'exploitation (DOS, Windows, Mac OS Classic, Mac OS X, VMS) utilisent des systèmes de fichiers insensibles à la casse, ce qui ferait que l'un des fichiers écraserait l'autre lors du désarchivage de la distribution. C'est par une erreur de ce genre que bien des utilisateurs de Mac OS X ont vu leur commande Unix head(1) écrasée par la commande HEAD(1) installée par LWP.
Tentez de vous limiter sur la longueur des noms de fichiers. Plusieurs systèmes ont des limitations sur la longueur des noms de fichier : DOS n'autorise que des noms de 8 caractères plus 3 d'extension alors que Mac OS Classic autorise jusqu'à 31 caractères. En conséquence essayez de nommer les fichiers de sorte que les premiers caractères permettent d'obtenir tout de même un nom unique.
N'utilisez pas de caractères comme / : \ ? * < ! > @ | & ; car certains sont utilisés comme séparateur des noms de répertoires ou ont une signification spéciale.
N'utilisez pas non plus d'espace car la plupart des systèmes (y compris les Unix) s'en accommodent mal voire ne les autorisent pas du tout.
N'utilisez pas plus d'un point dans un nom car des systèmes comme DOS et VMS n'aiment pas ce genre de plaisanteries.
En fait, n'utilisez que les caractères suivants, recommandés par perlport qui le tient de la norme C ANSI :
```
    a b c d e f g h i j k l m n o p q r t u v w x y z
    A B C D E F G H I J K L M N O P Q R T U V W X Y Z
    0 1 2 3 4 5 6 7 8 9
    . _ -
```
en évitant de mettre autre chose qu'un alpha-numérique en premier caractère. (Et ne nommez pas les répertoires en .s).

Vous trouvez ces limitations effrayantes ? C'est bien, c'était le but : vous rappeler qu'Unix n'est pas le seul système (ou architecture de système) au monde. D'autres systèmes existent, avec leurs caractéristiques propres qu'il s'agit de respecter dans la mesure du possible.

Vous pourriez écrire un script pour vérifier que les fichiers sont nommés en respectant ces conseils mais comme ça ne présente que peu d'intérêt et que vous n'avez pas envie de tout vous retaper à chaque fois, autant utiliser directement le module Test::Portability::Files qui est à votre disposition sur le CPAN. Le script de test, t/portfs.t, se résume alors à :

    use Test::More;
    eval "use Test::Portability::Files";
    plan skip_all => "Test::Portability::Files required for testing filenames portability" if $@;
    run_tests();

Et vous pouvez même copier-coller le synopsis du module, voire directement copier le fichier t/portfs.t inclus pour vous éviter même cette saisie ;-).

Notez que vous pouvez appeler la fonction options() pour sélectionner les tests à exécuter. La documentation vous expliquera le reste.

Créer une distribution pour le CPAN

Chapeau de l'article

Introduction

Quelques définitions

Survol d'un module Perl

Dissection d'une distribution

Les fichiers destinés aux humains

Les fichiers destinés aux programmes

Les fichiers à installer

Les fichiers de tests

Fichiers divers

Installation

`ExtUtils::MakeMaker`

`Module::Build`

Créer une distribution

h2xs

Script personnalisé

module-starter

Modules de construction et d'installation

La documentation

Le numéro de version

Les tests automatisés

Tester la distribution

Portabilité

Le CPAN

PAUSE

Obtenir un identifiant

Choisir un nom

Charger une archive sur le CPAN

Conclusion

Références

Auteur