5.2. Bezeichnungen

Der erste Teil des Makefile beschreibt die Versionsnummer des Ports und führt ihn in der richtigen Kategorie auf.

5.2.1. PORTNAME und PORTVERSION

Setzen Sie bitte die Variable PORTNAME auf den Basisnamen Ihres Ports und die Variable PORTVERSION auf dessen Versionsnummer.

5.2.2. PORTREVISION und PORTEPOCH

5.2.2.1. PORTREVISION

Die PORTREVISION-Variable ist ein streng monoton wachsender Wert, welcher auf 0 zurückgesetzt wird, nachdem PORTVERSION erhöht wurde (d.h. jedes Mal, wenn ein offizielles Release erfolgt). Sie wird an den Namen des Pakets angehängt, wenn sie ungleich 0 ist. Änderungen an PORTREVISION werden von automatisierten Werkzeugen (z.B. pkg_version(1)) genutzt, um anzuzeigen, dass ein neues Paket verfügbar ist.

PORTREVISION sollte jedes Mal erhöht werden, wenn eine Änderung am Port erfolgt, die beträchtliche Auswirkungen auf den Inhalt oder Struktur des aus dem Port erzeugten Pakets zur Folge hat.

Beispiele dafür, wann PORTREVISION erhöht werden sollte:

  • Hinzufügen von Patches, welche Sicherheitslücken schließen, Fehler beseitigen oder neue Funktionalität zum Port hinzufügen.

  • Änderungen am Makefile des Ports, welche compile-time-Optionen hinzufügen oder entfernen.

  • Änderungen bezüglich Packliste oder am Verhalten während der Installation des Pakets (d.h. Änderungen an einem Skript, welches Ausgangsdaten für das Paket erzeugt, wie z.B. SSH-Hostschlüssel).

  • Versionssprung einer Shared-Library, welche eine Abhängigkeit dieses Ports ist (In diesem Fall würde ein Anwender bei der Installation des alten Pakets scheitern, falls er eine neue Version der Abhängigkeit bereits installiert hat, weil nach der alten Bibliothek libfoo.x anstatt nach libfoo.(x+1)) gesucht wird).

  • Schleichende Änderungen am Distfile, welche bedeutende funktionale Änderungen verursachen, d.h. Änderungen des Distfile erfordern eine Korrektur an distinfo, ohne dass damit zusammenhängend die PORTVERSION verändert wird, obwohl ein diff -ru zwischen der alten und der neuen Version bedeutende Veränderungen am Code nachweist.

Beispiele für Änderungen, welche keine Erhöhung von PORTREVISION erfordern:

  • Stilistische Änderungen am Grundgerüst des Ports ohne funktionale Änderungen am daraus resultierenden Paket.

  • Änderungen an der Variable MASTER_SITES oder andere funktionale Änderungen, welche das resultierende Paket nicht verändern.

  • Marginale Patches am Distfile wie die Korrektur von Tippfehlern, welche nicht wichtig genug sind, um dem Benutzer die Bürde eines Upgrades aufzuerlegen.

  • Build fixes, die ein Paket erst kompilierbar machen, welches ohne diese Änderungen vorher nicht erzeugt werden konnte (solange die Änderungen keine funktionale Differenz bringen auf Plattformen, auf denen dieses Paket schon vorher gebaut werden konnte). Da PORTREVISION den Inhalt des Pakets wiederspiegelt, ist es nicht notwendig PORTREVISION zu erhöhen, wenn das Paket vorher nicht erstellt werden konnte.

Als Faustregel gilt: Stellen Sie sich die Frage, ob die durchgeführte Änderung am Port jedem hilft (entweder aufgrund einer Verbesserung, Beseitigung eines Fehlers, oder der Annahme, dass das neue Paket überhaupt erst funktioniert) und wägen Sie es gegen den Umstand ab, dass jedermann, der seine Ports-Sammlung regelmässig auf dem neuesten Stand hält, zu einer Aktualisierung gezwungen wird. Falls Sie die Frage positiv beantworten sollten, erhöhen Sie die Variable PORTREVISION.

5.2.2.2. PORTEPOCH

Von Zeit zu Zeit geschieht es, dass irgendjemand (Drittanbieter von Software oder FreeBSD Ports Committer) etwas Dummes tut und eine Version einer Software veröffentlicht, deren Versionsnummer niedriger ist als die der vorherigen. Ein Beispiel hierfür ist ein Port, der von foo-20000801 auf foo-1.0 geändert wird (der Erstere wird fälschlicherweise als neue Version behandelt, weil 2000801 ein numerisch größerer Wert ist als 1).

In Situationen wie diesen sollte die Variable PORTEPOCH erhöht werden. Wenn PORTEPOCH größer als 0 ist, wird sie an den Namen des Pakets angehängt, wie in Abschnitt 0 oberhalb bereits beschrieben. PORTEPOCH darf niemals verringert oder auf 0 gesetzt werden, weil der Vergleich des Pakets mit einem früheren Zeitpunkt scheitern würde (d.h. das Paket würde niemals als veraltet erkannt werden): Die neue Versionsnummer (1.0,1 im obigen Beispiel) ist immer noch numerisch kleiner als die vorherige Version (2000801), aber das Suffix ,1 wird von automatisierten Werkzeugen gesondert behandelt und wird als größer erkannt, als das implizit angenommene Suffix ,0 im früheren Paket.

Das Entfernen oder Zurücksetzen von PORTEPOCH führt zu unendlichem Ärger. Wenn Sie die obigen Ausführungen nicht vollständig verstanden haben, lesen Sie es bitte unbedingt nochmals bis Sie es vollständig verinnerlicht haben, oder fragen Sie vor jeder Änderung auf den Mailinglisten nach!

Es wird erwartet, dass PORTEPOCH für die weitaus überwiegende Zahl der Ports nicht verwendet wird und der verantwortungsvolle und vorausschauende Umgang mit PORTVERSION macht es meist überflüssig, falls ein späteres Release die Versionsstruktur ändern sollte. Vorsicht ist geboten, wenn ein Release einer Drittanbieter-Software ohne eine offizielle Versionsnummer veröffentlicht wird, wie z.B. bei Snapshot-Versionen. Man ist versucht, das Release mit dem jeweiligen Datum zu bezeichnen, was unweigerlich zu den oben beschriebenen Problemen führt, wenn das nächste offizielle Release erscheint.

Wenn z.B. ein Snapshot zum Datum 20000917 veröffentlicht wird und die vorherige Version der Software war 1.2, dann sollte der Snapshot die PORTVERSION 1.2.20000917 oder ähnlich erhalten und nicht 20000917, damit das nachfolgende Release, angenommen 1.3, immer noch einen größeren numerischen Wert aufweist.

5.2.2.3. Beispiel für den Gebrauch von PORTREVISION und PORTEPOCH

Der gtkmumble-Port, Version 0.10, befindet sich in der Ports-Sammlung:

PORTNAME=       gtkmumble
PORTVERSION=    0.10

PKGNAME wird zu gtkmumble-0.10.

Ein Sicherheitsloch wurde entdeckt, das einen lokalen Patch von FreeBSD erforderlich macht. PORTREVISION wird entsprechend erhöht.

PORTNAME=       gtkmumble
PORTVERSION=    0.10
PORTREVISION=   1

PKGNAME wird zu gtkmumble-0.10_1

Eine neue Version wird vom Software-Drittanbieter veröffentlicht, bezeichnet mit der Version 0.2 (es stellt sich heraus, dass der Autor beabsichtigte, dass 0.10 eigentlich 0.1.0 bedeuten sollte, nicht was kommt nach 0.9  – Hoppla, aber nun ist es zu spät). Da die neue Unterversion 2 numerisch kleiner ist als die vorherige Version 10, muss PORTEPOCH erhöht werden, um sicherzustellen, dass das neue Paket auch als neuer erkannt wird. Da es ein neues Release des Drittanbieters ist, wird PORTREVISION auf 0 zurückgesetzt (oder aus dem Makefile entfernt).

PORTNAME=       gtkmumble
PORTVERSION=    0.2
PORTEPOCH=      1

PKGNAME wird zu gtkmumble-0.2,1

Das nächste Release ist 0.3. Da PORTEPOCH niemals verringert wird, sind die Versionsvariablen nun wie folgt:

PORTNAME=       gtkmumble
PORTVERSION=    0.3
PORTEPOCH=      1

PKGNAME wird zu gtkmumble-0.3,1

Anmerkung:

Falls PORTEPOCH mit diesem Upgrade auf 0 zurückgesetzt worden wäre, dann würde jemand, der das Paket gtkmumble-0.10_1 installiert hätte, das Paket gtkmumble-0.3 nicht als neuer erkennen, da 3 immer noch numerisch kleiner ist als 10. Bedenken Sie, dass genau dies der springende Punkt an PORTEPOCH ist.

5.2.3. PKGNAMEPREFIX und PKGNAMESUFFIX

Zwei optionale Variablen, PKGNAMEPREFIX und PKGNAMESUFFIX, werden verknüpft mit PORTNAME und PORTVERSION, um PKGNAME zu bilden als ${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION} . Stellen Sie bitte unbedingt sicher, dass diese Variablen den Richtlinien für einen guten Paketnamen entsprechen. Insbesondere dürfen Sie keinesfalls einen Bindestrich (-) in PORTVERSION verwenden. Falls das Paket den language- oder -compiled.specifics-Teil aufweist (siehe unten) benutzen Sie PKGNAMEPREFIX oder PKGNAMESUFFIX respektive. Machen Sie diese Variablen nicht zum Bestandteil von PORTNAME!

5.2.4. LATEST_LINK

Die Umgebungsvariable LATEST_LINK wird während der Paketerstellung verwendet, um einen Kurznamen festzulegen, der danach von pkg_add -r genutzt werden kann. Dadurch wird es beispielsweise möglich, die aktuelle Perl-Version durch einen einfachen Aufruf von pkg_add -r perl zu installieren (ohne die Angabe der korrekten Versionsnummer). Dieser Name muss eindeutig sowie offensichtlich sein.

In einigen Fällen können mehrere Versionen einer Applikation gleichzeitig in der Ports-Sammlung sein. Das index build- und das package build-System müssen nun in der Lage sein, diese als unterschiedliche Ports zu erkennen, obwohl diese Versionen alle die gleichen Variablen PORTNAME, PKGNAMEPREFIX und sogar PKGNAMESUFFIX aufweisen. In solchen Fällen sollte die optionale Variable LATEST_LINK auf einen unterschiedlichen Wert für alle Ports gesetzt werden mit Ausnahme des Haupt-Ports. Beispiele hierfür sind die lang/gcc46 und lang/gcc-Ports und die www/apache*-Familie. Wenn Sie die Umgebungsvariable NO_LATEST_LINK setzen, wird kein Link erzeugt, was für alle Versionen (aber nicht für die Hauptversion) nützlich sein kann. Beachten Sie bitte, dass die Frage der Auswahl der wichtigsten Version (am populärsten, am besten Unterstützt, zuletzt gepatcht usw.) ausserhalb der Möglichkeiten dieses Handbuches liegt. Wir sagen Ihnen nur, wie Sie die anderen Ports spezifizieren, nachdem Sie den Haupt-Port erkoren haben.

5.2.5. Namensregeln für Pakete

Im Folgenden finden Sie die Regeln für die Benennung Ihrer Pakete. Diese sollen gewährleisten, dass das Paketverzeichnis leicht zu durchsuchen ist, da es bereits abertausende Pakete gibt und die Nutzer sich mit Schauder abwenden, wenn Ihre Augen überstrapaziert werden!

Der Paketname soll aussehen wie language_region-name-compiled.specifics-version.numbers.

Der Paketname ist definiert als ${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION} . Stellen Sie bitte sicher, dass die Variablen Ihres Ports diesem Format entsprechen.

  1. FreeBSD bemüht sich ausserordentlich, die Landessprachen seiner Nutzer zu unterstützen. Die language-Variable soll eine Abkürzung mit 2 Buchstaben sein der Sprachen gemäß ISO-639, falls der Port für eine bestimmte Sprache spezifisch ist. Beispiele hierfür sind ja für Japanisch, ru für Russisch, vi für Vietnamesisch, zh für Chinesisch, ko für Koreanisch und de für Deutsch.

    Sollte der Port spezifisch sein für eine gewisse Region innerhalb eines Sprachraumes, dann fügen Sie bitte auch den Ländercode mit 2 Buchstaben hinzu. Beispiele sind en_US für nordamerikanisches Englisch und fr_CH für schweizerisches Französisch.

    Der language-Teil muss in der PKGNAMEPREFIX-Variable gesetzt werden.

  2. Der erste Buchstabe des name-Teils muss kleingeschrieben werden (der Rest des Namens kann Großbuchstaben enthalten. Daher seien Sie bitte umsichtig, wenn Sie den Namen einer Software konvertieren, welche Grossbuchstaben enthält). Es ist Tradition, Perl 5-Module durch ein vorstehendes p5- und durch Umwandlung des doppelten Doppelpunktes in Bindestriche zu bezeichnen. So wird z.B. aus dem Data::Dumper-Modul der p5-Data-Dumper-Port.

  3. Vergewissern Sie sich, dass der Name des Ports und seine Versionsnummer klar getrennt sind und in den Variablen PORTNAME und PORTVERSION stehen. Der einzige Grund, um in PORTNAME einen Versionsteil aufzunehmen ist der, dass die Software wirklich so bezeichnet wird, wie z.B. die Ports textproc/libxml2 oder japanese/kinput2-freewnn. Ansonsten sollte PORTNAME keine versionsspezifischen Bestandteile aufweisen. Es ist vollkommen normal, dass viele Ports den gleichen PORTNAME aufweisen wie z.B. die www/apache*-Ports. In diesem Falle werden unterschiedliche Versionen (und unterschiedliche Indexeinträge) unterschieden durch die Werte von PKGNAMEPREFIX, PKGNAMESUFFIX und LATEST_LINK.

  4. Falls der Port mit verschiedenen, fest kodierten Vorgaben (üblicherweise Teil des Verzeichnisnamens in einer Familie von Ports) gebaut werden kann, dann soll der -compiled.specifics-Teil die einkompilierten Vorgaben anzeigen (der Bindestrich ist optional). Beispiele hierfür sind Papiergrößen und Font-Einheiten.

    Der -compiled.specifics-Teil muss in der Variablen PKGNAMESUFFIX gesetzt werden.

  5. Die Versionszeichenfolge sollte einen Bindestrich (-) am Schluss haben und eine von Punkten getrennte Liste von Integer-Zahlen und kleingeschriebenen Buchstaben sein. Es ist nicht zulässig, einen weiteren Bindestrich innerhalb des Versionsstrings zu verwenden! Die einzige Ausnahme hiervon ist die Zeichenfolge pl (bedeutet patchlevel), welche nur dann gebraucht werden darf, wenn die Applikation über keine Haupt– oder Unterversionsnummern verfügt. Wenn die Versionsbezeichnung der Software Zeichenketten wie alpha, beta, rc oder pre enthält, dann nehmen Sie bitte den ersten Buchstaben daraus und setzen ihn unmittelbar hinter einen Punkt. Falls die Versionszeichenfolge nach diesem Punkt fortgesetzt wird, sollen die Zahlen ohne einen Punkt zwischen den einzelnen Buchstaben folgen.

    Das Ziel ist es, die Ports anhand der Versionszeichenfolge zu sortieren. Stellen Sie bitte unbedingt sicher, dass die Bestandteile der Versionsnummer immer durch einen Punkt getrennt sind und falls Datumsangaben verwendet werden, dass diese im Format 0.0.yyyy.mm.dd und nicht dd.mm.yyyy oder gar dem nicht Y2K-kompatiblen Format yy.mm.dd vorliegen. Es ist wichtig, dass die Versionsnummer mit 0.0. beginnt, da die Versionsnummer im Falle einer Veröffentlichung auf jeden Fall kleiner als yyyy sein wird.

Hier sind einige reale Beispiele, die aufzeigen, wie man den Namen einer Applikation zu einem vernünftigen Paketnamen umwandelt:

SoftwarenamePKGNAMEPREFIXPORTNAMEPKGNAMESUFFIXPORTVERSIONGrund
mule-2.2.2(leer)mule(leer)2.2.2Keine Änderung erforderlich
EmiClock-1.0.2(leer)emiclock(leer)1.0.2keine Großbuchstaben für einzelne Applikationen
rdist-1.3alpha(leer)rdist(leer)1.3.aKeine Zeichenketten wie alpha erlaubt
es-0.9-beta1(leer)es(leer)0.9.b1keine Zeichenketten wie beta erlaubt
mailman-2.0rc3(leer)mailman(leer)2.0.r3keine Zeichenketten wie rc erlaubt
v3.3beta021.src(leer)tiff(leer)3.3Was sollte denn das eigentlich sein?
tvtwm(leer)tvtwm(leer)pl11Versionsstring zwingend erforderlich
piewm(leer)piewm(leer)1.0Versionsstring zwingend erforderlich
xvgr-2.10pl1(leer)xvgr(leer)2.10.1pl nur erlaubt, wenn keine Versionsnummer vorhanden
gawk-2.15.6ja-gawk(leer)2.15.6Japanische Sprachversion
psutils-1.13(leer)psutils-letter1.13Papergröße beim Paketbau fix kodiert
pkfonts(leer)pkfonts3001.0Paket für 300 DPI Schriftarten

Falls es in der Originalquelle überhaupt keinen Anhaltspunkt für irgendeine Versionsbezeichnung gibt und es unwahrscheinlich ist, dass der Autor jemals eine neue Version veröffentlichen wird, dann setzen Sie bitte die Version einfach auf 1.0 (wie im obigen Beispiel piewm). Sie können auch den Autor fragen oder eine Datumszeichenfolge in der Art 0.0.yyyy.mm.dd als Version verwenden.

Wenn Sie Fragen zu FreeBSD haben, schicken Sie eine E-Mail an <de-bsd-questions@de.FreeBSD.org>.

Wenn Sie Fragen zu dieser Dokumentation haben, schicken Sie eine E-Mail an <de-bsd-translators@de.FreeBSD.org>.