Diese Richtlinien beschreiben wie deine Distribution aussehen sollte wenn sie jemand herunterlädt, empfängt und nachfolgend entpackt.
Der zumeist begangene, ärgerliche Fehler von unerfahrenen Entwicklern ist, dass sie Tarballs kreieren, welche die Dateien und Verzeichnisse innerhalb der Distribution in das aktuelle Verzeichnis entpacken und somit unter Umständen eine bereits vorhandene, gleichnamige Datei und/oder Verzeichnis überschreiben. Vermeide dies um jeden Preis!
Stelle stattdessen sicher, dass all deine Archivdateien innerhalb eines nach dem Projekt benannten Verzeichnisses enthalten sind, sodass sie sich in ein Verzeichnis unterhalb des aktuellen Verzeichnis entpacken lassen (oder: dass ein neues Verzeichnis kreiert wird).
Hier nun ein Makefile Trick, der angenommen, dass dein Distributionsverzeichnis `foobar' benannt ist und SRC eine Liste all deiner Distributionsdateien enthält, dies vollbringt:
foobar-$(VERS).tar.gz:
@ls $(SRC) | sed s:^:foobar-$(VERS)/: >MANIFEST
@(cd ..; ln -s foobar foobar-$(VERS))
(cd ..; tar -czvf foobar/foobar-$(VERS).tar.gz `cat foobar/MANIFEST`)
@(cd ..; rm foobar-$(VERS))
|
Füge ein README or READ.ME hinzu, welches als "Wegweiser" deiner Sourcedistribution fungiert. In altertümlichen Konventionen war es jeweils üblich, dass dies die erste Datei war die ein unerschrockener Explorer direkt nach dem Entpackungsprozess der Sources gelesen hatte.
Erwähnenswertes welches im README vorhanden sein sollte:
Ein Verweis auf die Projekt Website (sofern eine vorhanden ist).
Erläuterungen betreffend der Systemkonfiguration des Entwicklers und eventuellen Portabilitätsproblemen.
Ein "Wegweiser" der wichtige Dateien und Unterverzeichnisse beschreibt.
Entweder Build/Installationsinstruktionen oder ein Verweis auf eine Datei, die jenes beinhaltet (normalerweise INSTALL).
Entweder eine Liste, die die involvierten Personen miteinbezieht oder ein Verweis auf eine Datei, die jenes beinhaltet (normalerweise CREDITS).
Bevor das README beachtet werden sollte, wird dein unerschrockener Erforscher die Dateinamen im obersten Verzeichnis deiner entpackten Distribution zur Kenntnis genommen haben. Diese Namen selbst beinhalten einige Informationen. Durch die Einhaltung gewisser standardisierter Namensvergabepraktiken ermöglicht man der Person wertvolle Hinweise worin die erhoffte Information zu finden ist.
Einige der standardisierten Dateinamen, die i.d.R. auf der obersten Verzeichnisebene eines entpackten Archives vorzufinden sind werden bezüglich der Bedeutung ihres Dateinamens hier erläutert. Nicht jede Distribution benötigt zwangsläufig all diese Dateien.
der Wegweiser, der als erstes gelesen werden sollte
Konfigurations-, Build- und Installationsanweisungen
Liste der Projektmitwirkenden
kürzliche Projektneuigkeiten
Verlauf des Projektes
Lizenzierungsbedingungen des Projektes (GNU Konvention)
Lizenzierungsbedingungen des Projektes
Auflistung der Dateien innerhalb der Distribution
Oft-gefragte-Fragen Dokument, in schlichtem Textformat, für das Projekt
Generierte Tagdatei für einen allfälligen Gebrauch durch Emacs oder vi
Man nehme zur Kenntnis, dass die Konvention welche Dateinamen mit Grossbuchstaben bezeichnet als menschlich-lesbare Metainformation betreffend dem Archiv zu gelten hat als vielmehr nur eine Art Buildkomponente (TAGS ist bezüglich ersterem eine Ausnahme, aber nicht betreffend zweiterem).
Eine vorhandene FAQ wird dir unter Umständen eine Menge an Ärgernis ersparen. Wenn eine Frage bezüglich des Projektes oftmals erwidert wird, ist es empfehlenswert die entsprechende Antwort der FAQ hinzufügen; dann kann man Endbenützer auf die FAQ verweisen, bevor sie Fragen senden oder Fehler reportieren. Eine ausreichend gehegte FAQ kann die Unterstützungsbürde auf seiten des Entwicklers enorm vermindern.
Eine vorhandene HISTORY oder NEWS Datei mit Zeitstempeln für die jeweilige Veröffentlichung zu pflegen, kann sich ebenso als wertvoll erweisen. Sollte man jemals in einen Gerichtsuntersuchungsfall involviert werden, der eine Urheberrechtsverletzung untersucht, wird es unweigerlich von Nutzen sein (dies war bis jetzt noch nicht der Fall, aber es ist besser, wenn man sich diesbezüglich "versichert") nebst einigen anderen Aspekten.
Deine Software wird im Laufe der Zeit durch die Veröffentlichung von neuen Versionen evolvieren. Einige dieser Änderungen werden nicht rückwarts-kompatibel sein. Deshalb sollte dem Entwurf von Installationslayouts einige ernsthafte Gedanken zugedacht werden, sodass multiple, installierte Versionen auf demselben System koexistieren können. Dies ist insbesondere für Bibliotheken von ungeheurer Wichtigkeit -- es kann nicht allen Clientprogrammen angemutet werden, dass sie unverzüglich mit deinen API-Änderungen Schritt halten.
Die Emacs, Python und Qt Projekte verwenden eine ausgesprochen gute Konvention für die Handhabung dieses Problemes; versionsnummerierte Verzeichnisse. Die Ausgabe einer Qt Bibliotheks Hierarchiestruktur (${ver} stellt die Versionsnummer dar):
/usr/lib/qt
/usr/lib/qt-${ver}
/usr/lib/qt-${ver}/bin # Wo man moc Dateien findet
/usr/lib/qt-${ver}/lib # Wo man .so Dateien findet
/usr/lib/qt-${ver}/include # Wo man Header Dateien findet
|
Jene Strukturierung ermöglicht die Koexistenz von mehreren Versionen auf demselben Rechner. Clientprogramme sehen sich zwar genötigt die Bibliotheksversion spezifizieren zu müssen, die sie benötigen; dies ist jedoch ein relativ geringer Preis verglichen mit Inkonsistenzen, die andernfalls hätten erzeugt werden können.
Das de-facto Standard Format for installierbare, binäre Archive ist dasjenige, das durch den Red Hat Package Manager (RPM) verwendet wird. Es ist in den meisten populären Linux Distributionen enthalten und wird beinahe von allen anderen Linux Distributionen unterstützt (ausser Debian und Slackware; Debian kann jedoch RPMs installieren).
Somit ist es empfehlenswert für deine Projektseite sowohl installierbare RPMs wie auch Source Tarballs zu kreieren.
Überdies kann in dem Source tarball auch die RPM spec Datei inkludiert werden, mit dem Ergebnis, dass es RPMs durch die Verwendung in dem Makefile erzeugt. Die spec Datei sollte die Dateierweiterung `.spec' haben; anhand dieser Dateiendung extrahiert rpm -t es aus einem tarball.
Um die Inkludierung der korrekten Versionsnummer zu automatisieren generiere innerhalb deiner spec Datei ein Shellscript, welches automatisch die korrekte Versionsnummer durch eine Analyse der Makedatei oder einer Versionheaderdatei einfügt.
Bemerkung: wenn du Source RPMs bereitstellen solltest, verwende BuildRoot, um die Kompilierung des Programms in /tmp oder /var/tmp zu erzwingen. Sofern du dies nicht tun solltest, werden während der make Installation deines Builds, die temporären Dateien bereits in ihren endgültigen Pfaden platziert. Dies wird sogar der Fall sein, wenn Dateikollisionen auftreten und selbst wenn du nicht beabsichtigt hast das Archiv zu installieren. Wenn der Prozess beendet sein sollte, sind die Dateien installiert worden und die RPM Datenbank deines Systems wird keinerlei Ahnung davon besitzen. Solcherlei schlecht-agierende SRPMs sind ein Minenfeld und sollten vermieden werden.