perlnewmod – Online in der Cloud

PROGRAMM:

NAME/FUNKTION

perlnewmod – Vorbereiten eines neuen Moduls für die Verteilung

BESCHREIBUNG

Dieses Dokument gibt Ihnen einige Vorschläge zum Schreiben von Perl-Modulen.
Vorbereitung für den Vertrieb und Bereitstellung über CPAN.

Eines der Dinge, die Perl wirklich mächtig machen, ist die Tatsache, dass Perl-Hacker dazu neigen
möchten die Lösungen für Probleme, mit denen sie konfrontiert waren, teilen, damit Sie und ich nicht kämpfen müssen
wieder mit dem gleichen Problem.

Dies geschieht hauptsächlich durch die Abstraktion der Lösung in ein Perl-Modul. Wenn nicht
Wissen Sie, was eines davon ist, der Rest dieses Dokuments wird Ihnen nicht viel nützen.
Außerdem entgeht Ihnen eine Menge nützlicher Code. Werfen Sie einen Blick auf Perlmod.
perlmodlib und perlmodinstall, bevor Sie hierher zurückkehren.

Wenn Sie festgestellt haben, dass für das, was Sie tun möchten, kein Modul verfügbar ist, und
Wenn Sie den Code selbst schreiben mussten, denken Sie darüber nach, die Lösung in ein Modul zu packen
und es auf CPAN hochzuladen, damit andere davon profitieren können.

Sie sollten auch einen Blick auf perlmodstyle werfen, um Best Practices für die Erstellung eines Moduls zu finden.

Warnung
Wir konzentrieren uns hier hauptsächlich auf reine Perl-Module und nicht auf XS-Module. XS
Module dienen einem ganz anderen Zweck und man sollte vorher verschiedene Dinge bedenken
Verteilen Sie sie - die Beliebtheit der Bibliothek, die Sie kleben, die Portabilität auf andere
Betriebssysteme usw. Beachten Sie jedoch die Hinweise zur Vorbereitung der Perl-Seite des Moduls
und das Verpacken und Verteilen lässt sich für ein XS-Modul genauso gut anwenden wie für reines Perl
eins.

Was sollte I um in a Modul?
Sie sollten aus jedem Code, von dem Sie glauben, dass er für andere nützlich sein wird, ein Modul erstellen.
Alles, was geeignet ist, eine Lücke in der Gemeinschaftsbibliothek zu füllen, und was jemand anderes kann
direkt in ihr Programm einbinden. Jeder Teil Ihres Codes, den Sie isolieren und extrahieren können
und an etwas anderes anzuschließen ist ein wahrscheinlicher Kandidat.

Nehmen wir ein Beispiel. Angenommen, Sie lesen Daten aus einem lokalen Format in einen Hash ein.
Hashes in Perl erstellen, diese in einen Baum umwandeln, den Baum durchlaufen und dann jeden Knoten an einen weiterleiten
Acme Transmogrifier-Server.

Nun haben ziemlich viele Leute den Acme Transmogrifier, und Sie mussten etwas schreiben
Sprechen Sie das Protokoll von Grund auf an – Sie möchten daraus mit ziemlicher Sicherheit ein Modul machen.
Die Ebene, auf der Sie es vorschlagen, bleibt Ihnen überlassen: Möglicherweise möchten Sie Module auf Protokollebene
analog zu Net::SMTP, die dann analog zu Mail::Send mit übergeordneten Modulen kommunizieren.
Sie haben die Wahl, aber Sie möchten ein Modul für dieses Serverprotokoll herausbringen.

Niemand sonst auf dem Planeten wird über Ihr lokales Datenformat sprechen, also können wir das ignorieren.
Aber was ist mit dem Ding in der Mitte? Aufbau von Baumstrukturen aus Perl-Variablen und
Dann ist das Durchqueren ein schönes, allgemeines Problem, und wenn noch niemand ein Modul geschrieben hat
Wenn das erledigt ist, möchten Sie vielleicht auch diesen Code modularisieren.

Hoffentlich haben Sie jetzt ein paar Ideen, was sich gut modularisieren lässt. Mal sehen
wie es gemacht wird.

Schritt für Schritt: Vorbereitung die Farbe
Bevor wir überhaupt mit dem Auskratzen des Codes beginnen, möchten wir noch ein paar Dinge erledigen
voraus.

Umschauen
Stöbern Sie in einer Reihe von Modulen, um zu sehen, wie sie geschrieben sind. Ich würde vorschlagen, mit zu beginnen
Text::Tabs, da es sich in der Standardbibliothek befindet und schön und einfach ist, und dann suchen
bei etwas etwas Komplexerem wie File::Copy. Für objektorientierten Code:
„WWW::Mechanize“ oder die „Email::*“-Module liefern einige gute Beispiele.

Diese sollen Ihnen einen allgemeinen Eindruck davon vermitteln, wie Module aufgebaut und geschrieben sind.

Überprüfen Sie, ob es neu ist
Es gibt viele Module zu CPAN, und es ist leicht, eines zu übersehen, das dem ähnelt
Sie planen, einen Beitrag zu leisten. Viel Spaß beim Pflügen
<http://search.cpan.org> und stellen Sie sicher, dass Sie nicht derjenige sind, der das Rad neu erfindet!

Besprechen Sie den Bedarf
Es könnte Ihnen gefallen. Sie könnten das Gefühl haben, dass alle anderen es brauchen. Aber vielleicht nicht
Es gibt tatsächlich eine echte Nachfrage danach. Wenn Sie sich über die Nachfrage nicht sicher sind
Modul haben wird, denken Sie darüber nach, Fühler auf „comp.lang.perl.modules“ auszusenden.
Newsgroup, oder fragen Sie als letzten Ausweg nach der Modulliste unter „[E-Mail geschützt] ". Erinnern
dass es sich um eine geschlossene Liste mit einer sehr langen Bearbeitungszeit handelt – seien Sie bereit, eine Weile zu warten
Ich freue mich über eine Antwort von ihnen.

Wähle einen Namen
In CPAN enthaltene Perl-Module verfügen über eine Namenshierarchie, in die Sie sich einfügen sollten.
Weitere Informationen zur Funktionsweise finden Sie unter perlmodlib und stöbern Sie in CPAN und dem
Sehen Sie sich die Modulliste an, um ein Gefühl dafür zu bekommen. Denken Sie zumindest daran: Module sollten es sein
Der großgeschriebene Titel (This::Thing) passt in eine Kategorie und erklärt deren Zweck
kurz und bündig.

Nochmal Überprüfen
Stellen Sie dabei unbedingt sicher, dass Sie kein ähnliches Modul verpasst haben
eine, die du gleich schreiben wirst.

Wenn Sie Ihren Namen geklärt haben und sicher sind, dass Ihr Modul gesucht wird und nicht
derzeit verfügbar ist, ist es Zeit, mit dem Codieren zu beginnen.

Schritt für Schritt: Making die Modulen
Beginnen mit Modulstarter or h2xs
Die Modulstarter Das Dienstprogramm wird als Teil des Module::Starter CPAN-Pakets verteilt.
Es erstellt ein Verzeichnis mit Stubs aller notwendigen Dateien, um ein neues Modul zu starten.
gemäß aktueller „Best Practice“ für die Modulentwicklung und wird von aufgerufen
Befehlszeile, also:

module-starter --module=Foo::Bar \
--author="Ihr Name" --email=[E-Mail geschützt]

Wenn Sie das Module::Starter-Paket nicht von CPAN installieren möchten, h2xs ist ein älterer
Tool, das ursprünglich für die Entwicklung von XS-Modulen gedacht war und im Lieferumfang enthalten ist
die Perl-Distribution.

Ein typischer Aufruf von h2xs für ein reines Perl-Modul ist:

h2xs -AX --skip-exporter --use-new-tests -n Foo::Bar

Das „-A“ lässt den Autoloader-Code weg, „-X“ lässt XS-Elemente weg, „--skip-exporter“ lässt das weg
Der Exportercode „--use-new-tests“ richtet eine moderne Testumgebung ein und „-n“
Gibt den Namen des Moduls an.

Verwenden Sie strenge Warnungen und Warnungen
Der Code eines Moduls muss warnend und strikt sauber sein, da Sie dies nicht garantieren können
Bedingungen, unter denen es verwendet wird. Außerdem möchten Sie keinen solchen Code verbreiten
war doch sowieso keine Warnung oder strikte Sauberkeit, oder?

Verwenden Sie Karpfen
Mit dem Carp-Modul können Sie Ihre Fehlermeldungen vom Anrufer präsentieren
Perspektive; Dies gibt Ihnen die Möglichkeit, ein Problem mit dem Anrufer und nicht mit Ihrem eigenen zu signalisieren
Modul. Wenn Sie zum Beispiel Folgendes sagen:

warnen „Kein Hostname angegeben“;

Der Benutzer sieht etwa Folgendes:

Unter /usr/local/lib/perl5/site_perl/5.6.0/Net/Acme.pm ist kein Hostname angegeben
Zeile 123.

Es sieht so aus, als ob Ihr Modul etwas falsch macht. Stattdessen möchten Sie das setzen
Geben Sie dem Benutzer die Schuld und sagen Sie Folgendes:

In bad_code, Zeile 10, ist kein Hostname angegeben.

Sie tun dies, indem Sie „Carp“ verwenden und Ihre „Warn“s durch „Carp“s ersetzen. Wenn du musst
„sterben“, sagen Sie stattdessen „krächzen“. Behalten Sie jedoch „warnen“ und „sterben“ im Interesse Ihrer geistigen Gesundheit bei
prüft, ob wirklich Ihr Modul schuld ist.

Nutzen Sie Exporter – mit Bedacht!
Exporter bietet Ihnen eine Standardmethode zum Exportieren von Symbolen und Unterprogrammen aus Ihrem Modul
in den Namensraum des Aufrufers. Wenn Sie zum Beispiel „use Net::Acme qw(&frob)“ sagen, würde dies der Fall sein
Importieren Sie die Unterroutine „frob“.

Die Paketvariable @EXPORT bestimmt, welche Symbole beim Exportieren exportiert werden
Der Anrufer sagt einfach „use Net::Acme“ – Sie werden kaum jemals etwas eingeben wollen
Dort. @EXPORT_OK hingegen gibt an, welche Symbole Sie exportieren möchten.
Wenn Sie eine Reihe von Symbolen exportieren möchten, verwenden Sie %EXPORT_TAGS und definieren Sie einen Standard
Exportsatz – Weitere Informationen finden Sie unter Exporter.

Verwenden Sie einfache alte Dokumentation
Die Arbeit ist erst beendet, wenn der Papierkram erledigt ist und Sie ihn einreichen müssen
Etwas Zeit, um eine Dokumentation für Ihr Modul zu schreiben. „module-starter“ oder „h2xs“ wird es tun
Stellen Sie einen Stub zur Verfügung, den Sie ausfüllen können. Wenn Sie sich über das Format nicht sicher sind, schauen Sie sich Perlpod an
für eine Einführung. Geben Sie eine gute Übersicht darüber, wie Ihr Modul im Code verwendet wird, a
Beschreibung und anschließend Hinweise zur Syntax und Funktion der einzelnen Unterprogramme bzw
Methoden. Verwenden Sie Perl-Kommentare für Entwicklernotizen und POD für Endbenutzernotizen.

Schreiben Sie Tests
Wir empfehlen Ihnen, Selbsttests für Ihr Modul zu erstellen, um sicherzustellen, dass es ordnungsgemäß funktioniert
vorgesehen für die unzähligen Plattformen, die Perl unterstützt; Wenn Sie Ihr Modul auf CPAN hochladen, a
Eine Vielzahl von Testern erstellt Ihr Modul und sendet Ihnen die Testergebnisse zu. Nochmal,
„module-starter“ und „h2xs“ bieten ein Test-Framework, das Sie erweitern können – das sollten Sie auch
Machen Sie etwas mehr, als nur zu überprüfen, ob Ihr Modul kompiliert werden kann. Test::Einfach und
Test::More sind gute Ausgangspunkte für das Schreiben einer Testsuite.

Schreiben Sie die README-Datei
Wenn Sie auf CPAN hochladen, extrahieren die automatisierten Gremlins die README-Datei und
Platzieren Sie das in Ihrem CPAN-Verzeichnis. Es wird auch im Hauptmenü angezeigt nach Modul und durch-
Kategorie Verzeichnisse, wenn Sie es in die Modulliste schaffen. Es ist eine gute Idee, es hier zu platzieren
was das Modul tatsächlich im Detail macht und welche für den Benutzer sichtbaren Änderungen seit dem letzten
freizugeben.

Schritt für Schritt: Verteilen Wir koordinieren den Versand Modulen
Holen Sie sich eine CPAN-Benutzer-ID
Jeder Entwickler, der Module auf CPAN veröffentlicht, benötigt eine CPAN-ID. Besuchen
"http://pause.perl.org/", wählen Sie „PAUSE-Konto anfordern“ und warten Sie auf Ihre Anfrage
müssen von den PAUSE-Administratoren genehmigt werden.

„perl Makefile.PL; make test; make dist“
Auch hier hat „module-starter“ oder „h2xs“ die ganze Arbeit für Sie erledigt. Sie produzieren die
Standard „Makefile.PL“, den Sie sehen, wenn Sie Module herunterladen und installieren, und dies erzeugt
ein Makefile mit einem „dist“-Ziel.

Sobald Sie sichergestellt haben, dass Ihr Modul seine eigenen Tests besteht, ist das immer eine gute Sache
Klar – Sie können „make dist“ machen, und das Makefile wird Ihnen hoffentlich einen schönen Tarball produzieren
Ihres Moduls, bereit zum Hochladen.

Laden Sie den Tarball hoch
In der E-Mail, die Sie nach Erhalt Ihrer CPAN-ID erhalten haben, erfahren Sie, wie Sie sich bei PAUSE anmelden.
der Perl-Autoren-Upload-Server. Von den dortigen Menüs aus können Sie Ihr Modul hochladen
CPAN.

Melden Sie sich zur Modulliste an
Nach dem Hochladen bleibt es unbemerkt in Ihrem Autorenverzeichnis. Wenn Sie möchten, dass es angeschlossen wird
Zum Rest des CPAN müssen Sie auf PAUSE zu „Namespace registrieren“ gehen. Einmal
Wenn Sie sich registriert haben, wird Ihr Modul in der Auflistung nach Modulen und Kategorien auf CPAN angezeigt.

Melden Sie sich bei clpa an
Wenn Sie den brennenden Wunsch verspüren, der Welt von Ihrer Freilassung zu erzählen, veröffentlichen Sie eine Ankündigung
zur moderierten Newsgroup „comp.lang.perl.announce“.

Fehler beheben!
Sobald Sie anfangen, Benutzer anzusammeln, senden diese Ihnen Fehlerberichte. Wenn du Glück hast,
Sie schicken Ihnen sogar Patches. Willkommen zu den Freuden der Pflege eines Softwareprojekts ...

Verwenden Sie perlnewmod online über die Dienste von onworks.net