Ein neues Perl-Modul anfangen
Es gibt verschiedene Gründe für mich, ein neues Perl-Modul anzufangen:
Ich will ein Stück Code veröffentlichen.
Ein Skript ist zu unübersichtlich geworden und soll in kleinere, wiederverwendbare Bibliotheken aufgeteilt werden.
Ich will die Test-Infrastruktur von Perl nutzen und meinem Code auch auf anderen Plattformen testen (lassen).
Egal welcher Grund zutrifft, ich gehe immer nach dem selben Schema vor, um ein neues Perl-Modul zu beginnen:
Ich schreibe ein README, das den Einsatzzweck des Moduls beschreibt.
Ich denke mir einen Namen für das Modul aus.
Ich erzeuge ein Gerüst mit module-starter.
Ich füge das README ein und eventuell vorhandene Skripte.
Ich überprüfe das Modul formal mit
make distcheck.Ich stelle das Modul unter Versionskontrolle.
Nach Ablauf dieser Schritte bin ich bereit, mit dem Modul zu arbeiten und kann die Arbeit jederzeit unterbrechen, wieder aufnehmen oder den bisherigen Stand veröffentlichen.
README
Ein Artikel von Tom Preston Werner brachte mich auf die Idee, als allererstes eine Kurzbeschreibung des Moduls zu verfassen. Damit weiss ich auch nach längerer Zeit noch, was der eigentliche Zweck des Modules ist, auch wenn ich noch gar nicht daran gearbeitet habe. Ausserdem benötige ich eine Kurzbeschreibung, so ist es von Vorteil, wenn ich damit anfange.
Mitunter schreibe ich Tage oder Wochen an dem README, bevor ich mit der Arbeit am Modul anfange. Dann fließen oft noch weitere Ideen ein, die später ein Refactoring des Codes erfordert hätten.
Ein Name für das Modul
Auf pause.perl.org gibt es Hinweise On The Naming of Modules.
Der Name sollte einen Kontext geben, damit potentielle Benutzer daraus bereits eine Vorstellung bekommen können, worum es geht, und er sollte Hauptmerkmale des Moduls beschreiben. Zum Beispiel zeigt der Name Algorithm::CheckDigits an, dass es bei diesem Modul um Algorithmen geht und zwar konkret um Prüfsummen.
Module, die nicht veröffentlicht werden sollen, sind unter Local:: relativ sicher vor Namenskollisionen.
Beeinhaltet ein Modul nur ein oder mehrere Skripte, dann ist es unter App:: gut aufgehoben.
Ein Gerüst für das Modul
Dieses erzeuge ich mit module-starter:
$ module-starter --module=App::CleanXHTML
Ich brauche nur den Namen des Modules anzugeben, alle anderen Informationen holt sich module-starter aus ~/.module-starter/config. Diese Datei sieht bei mir in etwa so aus:
author: Mathias Weidner
email: mamawe@cpan.org
builder: Module::Build
Es gibt noch mehr interessante Einstellungen in dieser Datei, aber das ist nicht Thema dieses Artikels.
README und Skripts einfügen
Ich begebe mich in das neu angelegte Verzeichnis und füge den am Anfang geschriebenen Text in die Datei README ein. Habe ich bereits Skripts, dann lege ich ein Unterverzeichnis bin an und kopiere diese dorthin.
Das Modul überprüfen
Module-starter nimmt mir bereits sehr viel Arbeit beim Anlegen des Modules ab. Trotzdem fallen noch einige Nacharbeiten an.
Build.PL
Als erstes ergänze ich die Datei Build.PL:
Ich sortiere die Parameter für den Aufruf von Module::Build->new() alphabetisch, damit ich später schneller zurecht finde.
Ich füge
create_makefile_pl => 'small',ein, da ich wegen der Kommandozeilenvervollständigung lieber mit make als mit ./Build arbeite.Ich füge mit
dist_abstract => 'Ein kurzer Satz.'eine sehr kurze Zusammenfassung des Moduls an, die dann als Abstract in den Meta-Informationen auftaucht.Habe ich Skripts, führe ich diese in
script_files => [ 'path/to/script' ],auf.
Als nächstes erzeuge ich Makefile.PL und aktualisiere MANIFEST:
$ perl Build.PL
$ ./Build manifest
$ ./Build disttest
$ ./Build dist
$ ./Build distclean
Danach kann ich mit perl Makefile.PL ein Makefile erzeugen und die
Kommandozeilenvervollständigung für make nutzen. Ich erzeuge noch einmal mit
make dist ein Modul-Archiv und kontrolliere, ob es die nötigen Dateien
enthält.
Unter Versionskontrolle stellen
Ich verwende monotone zur Versionskontrolle und stelle das Modul wie folgt darunter:
Einen neuen Zweig anlegen.
Die zu ignorierenden Dateien bestimmen.
Die zum Modul gehörenden Dateien einchecken.
Einen neuen Zweig anlegen
Für Perl-Module habe ich ein gemeinsames lokales Repository. Dieses gebe ich beim Aufsetzen des Arbeitsverzeichnisses ebenso wie den Namen des Entwicklungszweiges an:
$ mtn --db :perl --branch net.mamawe.perl-app-cleanxhtml setup .
Den Namen des Entwicklungszweiges bilde ich aus den Bestandteilen der Domain
mamawe.net, perl und dem Modulnamen, wie hier gezeigt. Dabei verwende ich
nur Kleinbuchstaben und lediglich . und - als Sonderzeichen.
Die zu ignorierenden Dateien bestimmen
Als erstes erzeuge ich ad-hoc eine Datei .mtn-ignore, die ich dann noch bearbeiten muss:
$ mtn ls unknown >> .mtn-ignore
$ vim .mtn-ignore
Ich entferne aus der ad-hoc angelegten Datei .mtn-ignore die Namen aller
Dateien, die ich aufnehmen will. Dann füge ich an den Anfang jeder
verbliebenen Zeile ein ^ ein, um die Muster zu verankern.
Am Ende der eindeutigen Dateinamen hänge ich ein $ an.
Bei generischen Namen wie App-CleanXHTML- lasse ich das $ weg.
Bei Verzeichnissen muss ich zwei Zeilen vorsehen:
^blib$
^blib/
^_build/
^_build$
Das eine Muster ist für das Verzeichnis selbst, das andere für Dateien in diesem Verzeichnis (deren Pfadname beginnt immer mit verzeichnisname/).
Die Dateien einchecken
Habe ich soweit alles für die Versionskontrolle vorbereitet, rufe ich make
manifest auf. Alle Dateien, die jetzt in MANIFEST gelandet sind und dort
nicht hingehören, trage ich in die Datei MANIFEST.SKIP ein und rufe make
manifest ein weiteres Mal auf.
MANIFEST.SKIP selbst gehört auch unter Versionskontrolle. Gegebenen falls
ändere ich .mtn-ignore ein weiteres Mal, bis mtn ls unknown genau die
Dateien anzeigt, die ich einchecken will.
Zum Schluss stelle ich die Dateien unter Revisionskontrolle, überprüfe noch einmal die Vollständigkeit, checke den initialen Stand ein und synchronsiere:
$ mtn add --unknown --recursive
$ mtn status
$ mtn commit -m Initial
$ mtn sync
Ab jetzt kann ich überall, wo ich Zugriff auf das Repository habe, an diesem Modul arbeiten.
Posted 2013-06-28