Distribution auf Dist::Zilla umstellen
In diesem Artikel zeige ich dir, wie du eine bestehende Distribution mit möglichst wenig Aufwand auf Dist::Zilla umstellen kannst.
Hauptteil
In einem vorherigen Artikel habe ich Dist::Zilla vorgestellt und beschrieben, dass diese Distribution dir beim Entwickeln einer CPAN-fähigen Distribution lästige Handarbeit abnimmt. Dadurch kannst du dich auf’s Wesentliche konzentrieren: Code schreiben.
Damit das in Dist::Zilla enthaltene Programm dzil die ehemals manuellen Schritte automatisieren kann, muss es minimal konfiguriert werden. Dafür muss eine Datei namens dist.ini in der bestehenden Distribution angelegt werden. Ein Beispiel zeige ich dir weiter unten.
Damit man die Vorteile von dzil aufwandsarm nutzen kann, muss die Distro den „Standard-Perl-Aufbau“ haben: Die Testprogramme liegen im Verzeichnis t, die Module im Verzeichnis lib, und ausführbare Programme in bin.
Dieser Aufbau wird empfohlen, da dzil plugin-basiert arbeitet; bei Abweichungen muss dann jeweils für die Plugins die Abweichung konfiguriert werden. Diesen Aufwand kann man sich sparen, wenn man dem Standard folgt.
Manchmal erwartet aber auch ein Plugin einfach einen fest verdrahteten Aufbau, an den man sich dann wohl oder übel halten muss (wenn man nicht den Code des Plugins ändern möchte).
Loslegen!
Um eine Distribution zu „dzilisieren“ ist gar nicht soviel notwendig.
Im ersten Schritt legst du eine einfache dist.ini an:
name = Deine-Distro
author = Dein Name <email@example.com>
license = Perl_5
copyright_holder = Dein Name <email@example.com>
copyright_year = 2022
version = 0.001
[@Basic]
Wenn deine bestehende Distro vom Perl-Standard abweichen sollte, dann empfehle ich dir, sie nun auf den Standard-Aufbau umzubauen.
Wichtigste Befehle ausprobieren
Dann kannst du auch schon die wichtigsten Befehle von dzil ausführen. Das sind meiner Meinung nach build (Paketieren der Distro), test (Ausführen der Testprogramme innerhalb dieser paketierten Distro) und zum Abschluss release (Distro auf CPAN veröffentlichen).
Wenn bei einem dieser Befehle etwas nicht funktioniert oder nicht deinen Erwartungen entspricht, dann gibt es grundsätzlich zwei mögliche Ursachen: Die Konfiguration passt noch nicht ganz (gerade zu Beginn ist das sehr wahrscheinlich) oder deine Distro entspricht nicht den Erwartungen der Plugins. Da hilft dann nur langsames Herantasten und vermutlich ein Anpassen der Konfiguration dist.ini.
Ein Beispiel: Beim Befehl build wird vermutlich zu Beginn die Versionsnummer noch nicht passen. Die Lösung ist einfach: Ändere den Eintrag in der Konfiguration.
Du kannst übrigens auch nach dem Umstieg auf Dist::Zilla mit prove weiter arbeiten, während du entwickelst. Den Befehl test sollte aber gelegentlich trotzdem schon ausführen, damit du feststellen kannst, ob die Tests nach dem Paketieren der Distro noch durchlaufen.
Noch ein Hinweis zu release: Bevor dieser Befehl erfolgreich ausgeführt werden kann, müssen die Zugangsdaten für PAUSE konfiguriert sein (wobei du das Passwort am besten nie in der Datei speicherst, sondern immer von Hand angibst). Du kannst also nicht versehentlich eine Distro auf CPAN veröffentlichen.
Konfiguration nach und nach ergänzen
Herzlichen Glückwunsch! Eigentlich hast du jetzt schon die Distro dzilisiert. Jetzt solltest du erst einmal den Umgang mit dzil üben und zur Gewohnheit werden lassen.
Dann kannst du nach und nach Plugins ergänzen und die Konfiguration dafür ergänzen.
Über das Plugin-System ist dzil sehr mächtig im Funktionsumfang. Um Anregungen zu bekommen, welche bisher manuellen Arbeitsschritte dir das Programm abnehmen kann, solltest du im Netz nach Konfigurationen anderer Autoren suchen.
Wenn du dann deine Konfiguration ergänzt, solltest du Vorsicht bei Reihenfolge walten lassen. Die Plugin-Reihenfolge ist wichtig, da die Plugins teilweise aufeinander aufbauen. Die Phasen im Ablauf von dzil sind wichtig; Plugins solltest du daher pro Phase gruppieren.
Ein guter Einstieg in die Ergänzung der Funktionalität sind sogenannte bundles, die mehrere Plugins bündeln. Ein sehr mächtiges bundle ist jenes namens „Starter“, das vom Autor in einer eigenen kleinen Blog-Serie vorgestellt wird.
Zusammenfassung
Das Programm dzil nimmt lästige Handarbeit ab bei der Entwicklung von CPAN-fähigen Perl-Distributionen. Um es aufwandsarm verwenden zu können, sollte die Distro den Perl-Standard-Aufbau haben.
Wenn du deine Distro auf die Arbeit mit dzil umstellst, dann solltest du mit einer einfachen Konfiguration anfangen und dabei falls nötig deine Distro standardisieren.
Anschließend kannst du dich dann durch Übung an den Umgang mit dzil gewöhnen und die Konfiguration nach und nach erweitern. Mit der Zeit automatisierst du dann ehemals lästige Handarbeit.
Einführung in Dist::Zilla
Eine Perl-Distribution besteht neben dem eigentlichen Code auch aus Dateien und Code, um die Distribution über CPAN zur Verfügung zu stellen. Das manuelle Erstellen dieser Dateien hält vom Entwickeln ab und wird schnell lästig. Dist::Zilla automatisiert diese Vorgänge. In diesem Artikel gebe ich einen Überblick über den Zweck von Dist::Zilla und zeige einen Einstieg in dessen Verwendung.
Das Problem: Langsam durch Handarbeit
CPAN ist der Ort, an dem Perl-Distributionen liegen. Damit Distributionen über CPAN bereitgestellt und von dort installiert werden können, muss ihr Inhalt und ihre Form einigen Anforderungen genügen. Diese Anforderungen können Autoren durch Handarbeit erfüllen.
Diese Handarbeit ist allerdings lästig und hält von der Hauptaufgabe ab: Code schreiben! Dist::Zilla ist eine Distribution, die das Werkzeug dzil bereitstellt, mit dem diese Handarbeit automatisiert werden kann. Dadurch werden Autoren schneller und als angenehme Nebenwirkung vereinheitlichen sie ihre Distributionen.
Die Notwendigkeit von Infrastruktur-Code
Perl-Distributionen sind im Kern ein Archiv von Dateien mit bestimmten Aufbau. Nur ein Teil dieses Archivs ist der eigentliche Code. Viele andere Dateien davon bilden nur die Infrastruktur, damit die Distribution auf CPAN bereitgestellt und von dort geladen werden kann; daher sind diese Dateien grundsätzlich notwendig. Leider ist es jedoch so, dass sie nicht nur einmal erstellt, sondern teilweise vor jedem erneuten Release geändert werden müssen.
Automatisierung hilft
Dist::Zilla nimmt dem Autor einer Distribution die Erstellung und Pflege dieser Dateien durch Automatisierung ab. Im Ergebnis muss dann (fast) nur noch der eigentliche Code geschrieben werden. Die Einschränkung betrifft die Konfiguration von dzil, die in der Datei dist.ini getroffen wird.
In dieser Konfiguration werden Metadaten und weitere Informationen untergebracht. Die Funktionsweise von Dist::Zilla kann der Autor über Plugins erweitern; die Plugins werden ebenfalls in dieser Datei konfiguriert.
Das Tool dzil
Das Werkzeug dzil bietet viele Kommandos, die durch den Aufruf von dzil angezeigt werden:
$ dzil
dzil <command> [-?hIVv] [long options...]
-v --verbose log additional output
-V STR... --verbose-plugin STR... log additional output from some
plugins only
-I STR... --lib-inc STR... additional @INC dirs
-? -h --help show help
Available commands:
commands: list the application's commands
help: display a command's help screen
add: add modules to an existing dist
authordeps: list your distribution's author dependencies
build: build your dist
clean: clean up after build, test, or install
cover: code coverage metrics for your distribution
install: install your dist
listdeps: print your distribution's prerequisites
new: mint a new dist
nop: do nothing: initialize dzil, then exit
perltidy: perltidy your dist
regenerate: write release staging contents into source tree
release: release your dist
run: run stuff in a dir where your dist is built
setup: set up a basic global config file
smoke: smoke your dist
test: test your dist
xtest: run xt tests for your dist
Für den Einstieg sind folgende drei Kommandos wichtig: build, test und release.
- Durch den Aufruf von
dzil builderstellt der Autor die Distribution anhand der Konfigurationdist.ini. - Mit
dzil testerstellt der Autor die Distribution und lässt darin die Tests ablaufen. - Schließlich kann der Autor die Distribution mit
dzil releaseauf CPAN veröffentlichen.
Zusammenfassung
In diesem Artikel habe ich einen kurzen Überblick über Dist::Zilla gegeben und die Möglichkeiten aufgezeigt. In den nächsten Teilen dieser Artikelserie werde ich auf die einzelnen Aspekte näher eingehen. Wenn du neugierig geworden bist und schon selbst ein bisschen durch das vorhandene Material stöbern möchtest, empfehle ich dir folgende Seiten:
- Die Homepage von
Dist::Zilla - Dist::Zilla auf MetaCPAN
- Ein Walk-Through durch eine echte
dist.ini
Permalink: /2022-06-08-einfa14hrung-in-distzilla
An Modul-Autoren: Badges für CPANCover
Sowohl für Nutzer als auch für Entwickler ist es ganz schön, wenn auf einen Blick der Zustand eines Moduls ersichtlich ist: Sind Fehler bekannt? Kann das Projekt gebaut werden? Wie ist die Testabdeckung?
Dazu können z.B. bei Gitlab oder GitHub sogenannte Badges angezeigt werden. Hier ein kleines Beispiel unseres Moduls Markdown::Table.
Paul Johnson stellt eine Seite bereit, auf der die Testabdeckung mit Devel::Cover angezeigt wird: CPANCover. Für das oben genannte Modul ist die Testabdeckung unter http://cpancover.com/latest//Markdown-Table-0.04/index.html zu finden.
Wir stellen einen Dienst bereit, der die Daten von CPANCover als einen solchen Badge zur Verfügung stellt: CPANCoverBadge. Das ist eine ganz kleine Anwendung, die auch auf CPAN liegt. Es werden einfach nur die Daten von CPANCover ausgelesen und mit Badge::Simple ein solches Badge erstellt. Für Markdown::Table 0.04 ist das Badge dann unter https://cpancoverbadge.perl-services.de/Markdown-Table-0.04 zu finden.
Um dieses Badge z.B. in der README.md anzuzeigen, muss mit Markdown-Mitteln die Grafik angezeigt werden:
[](https://cpancoverbadge.perl-services.de/Markdown-Table-0.04)
Für alle, die Dist::Zilla nutzen, gibt es ein Plugin, um diverse Badges einzubauen: Dist::Zilla::Plugin::GitHubREADME::Badge
Damit muss in der dist.ini ein Block eingefügt werden, in der die Badges konfiguriert werden:
[GitHubREADME::Badge]
badges = travis
badges = cpants
badges = issues
badges = cpancover
phase = build
place = top
Damit werden die vier oben gezeigten Badges eingeblendet.
Permalink: /2021-02-09-badges-cpancover