weidner/archives/2013/06/

Ein neues Perl-Modul anfangen

Es gibt verschiedene Gründe für mich, ein neues Perl-Modul anzufangen:

Egal welcher Grund zutrifft, ich gehe immer nach dem selben Schema vor, um ein neues Perl-Modul zu beginnen:

  1. Ich schreibe ein README, das den Einsatzzweck des Moduls beschreibt.

  2. Ich denke mir einen Namen für das Modul aus.

  3. Ich erzeuge ein Gerüst mit module-starter.

  4. Ich füge das README ein und eventuell vorhandene Skripte.

  5. Ich überprüfe das Modul formal mit make distcheck.

  6. 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:

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:

  1. Einen neuen Zweig anlegen.

  2. Die zu ignorierenden Dateien bestimmen.

  3. 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
Tags: