Poul-Henning Kamp Beigesteuert von Dieses Kapitel dokumentiert verschiedene Vorgaben und Richtlinien für das FreeBSD-Quelltextverzeichnis. Ports Maintainer Wenn ein bestimmter Bereich der FreeBSD-Distribution von einer Person oder Gruppe gepflegt wird, kann dies durch Hinzufügen der Zeile MAINTAINER= email-addresses im Makefile der Öffentlichkeit mitgeteilt werden. Dies bedeutet folgendes: Der Maintainer ist verantwortlich für diesen Code. Dies bedeutet, dass er einerseits für die Behebung von Fehlern und das Beantworten von Problemberichten für diesen Code die Verantwortung trägt, andererseits, falls es sich um beigesteuerte Software handelt, er neue Versionen verfolgt und diese bereitstellt. Änderungen an Verzeichnissen, welcher ein Maintainer definiert hat, sollten an den Maintainer für eine Überprüfung gesendet werden, bevor diese committed werden. Nur wenn der Maintainer in einer inakzeptablen Zeitspanne auf mehrere E-Mails nicht antwortet, können die Änderungen durch den Commit, auch ohne Überprüfung des Maintainers, vollzogen werden. Dennoch wird vorgeschlagen, dass die Änderungen, falls möglich, durch jemand anderen überprüft werden. Es ist natürlich nicht akzeptabel einer Person oder Gruppe den Status eines Maintainers zu geben, so lange dieser Pflicht nicht zugestimmt wurde. Andererseits muss es kein Committer und auch eine eine Gruppe von Menschen ist selbstverständlich legitim. Poul-Henning Kamp Beigesteuert von David O'Brien Beigesteuerte Software Einige Teile der FreeBSD-Distribution enthalten Software, welche aktiv ausserhalb des FreeBSD-Projektes gepflegt wird. Aus historischen Gründen nennen wir dies contributed Software. Beispiele dazu sind sendmail, gcc und patch. Über die Jahre wurden verschiedenen Methoden genutzt, um diese Art der Software zu handhaben, und alle haben Vorteile wie auch Nachteile. So gibt es keinen klaren Gewinner. Es wurde viel über diesen Umstand debattiert und so wurde eine Methode als die offizielle Methode gewählt, um in Zukunft diese Art der Software zu importieren. Ferner wird es dringend vorgeschlagen, dass existierende, beigesteuerte Software sich diesem Modell nähert, da es signifikante Vorteile gegenüber der alten Methode gibt. Beispielsweise die Leistungsfähigkeit einfach Diffs von der offiziellen Version zu beziehen und das für jedermann (auch ohne CVS-Zugang). Dies wird es deutlich einfacher machen Änderungen an die Hauptentwickler zurüfliessen zu lassen. Letztendlich kommt es auf die Menschen an, welche die Arbeit leisten. Wenn die Nutzung dieses Modells teilweise nicht möglich ist, so k¨nnen Ausnahmen von diesen Regeln gewährt werden, diese müssen aber durch das Core Team und mit Übereinstimmung der anderen Developer genehmigt werden. Die Fähigkeit dieses Paket auch in Zukunft pflegen zu können ist eine der Schlüsselfragen bei dieser Entscheidung. Durch einige bedauernswerte Einschränkungen beim Design des RCS-Dateiformates und wie CVS Vendor Branches nutzt, sind kleine und/oder kosmetische Änderungen sehr entmutigend bei Dateien, welche den Herstellerzweig verfolgen. Sprechende Fehlerbehebungen sind explizit unter der kosmetischen-Kategorie vorhanden und sollten bei Dateien mit einer 1.1.x.x-Revision verhindert werden. Das Repository kann sich durch Änderungen an einzelnen Zeichen dramatisch aufblähen. Die eingebettete Tcl-Programmiersprache soll als Beispiel dienen, wie dieses Modell funktioniert: src/contrib/tcl enthält den Quelltext wie vom Maintainer dieses Paketes bereitgestellt. Teile, welche unter FreeBSD nicht nutzbar sind, können entfernt werden. Im Fall von Tcl wurden die Unterverzeichnisse mac, win und compat vor dem Import entfernt. src/lib/libtcl enthält nur ein Makefile im bmake-Stil, welches die Regeln des Standard-Makefile bsd.lib.mk nutzt, um die Bibliothek zu erstellen und die Dokumentation zu installieren. src/usr.bin/tclshenthält nur ein Makefile im bmake-Stil, welches das tclsh-Programm erstellt und installiert, ebenso die dazugehörigen Manualpages, welche die Regeln von bsd.prog.mk nutzen. src/tools/tools/tcl_bmake enthält einige Shellskripte, welche hilfreich sein können, wenn die tcl-Software aktualisiert werden soll. Diese sind nicht Teil des Erstellens und der Installation der Software. Das Entscheidende ist hier das src/contrib/tcl-Verzeichnis, welches durch die entsprechenden Regeln erstellt wird: Es wird unterstellt, dass der Quelltext im Original vorhanden ist (ohne RCS-Schlüsselworte und im korrekten CVS-Herstellerzweig) mit so wenig wie möglich FreeBSD-spezifischen Änderungen. Sollte es Zweifel geben, wie hier zu verfahren ist, ist es selbstverständlich zuerst nachzufragen und nicht auf gut Glück etwas zu probieren in der vagen Hoffnung, dass es irgendwie tut. CVS vergibt keine Fehler beim Importieren und ein hoher Arbeitsaufwand wäre die Folge, um diesen grossen Fehler wieder wettzumachen. Durch die Eingangs schon erwähnten Einschränkungen durch das Design beim CVS-Herstellerzweig, ist es erforderlich, dass offizielle Fehlerbehebungen vom Hersteller bei den Originalquellen der Distribution einfliessen und als Resultat wird dies in den Herstellerzweig reimportiert. Offizielle Fehlerbehebungen sollten nie direkt in FreeBSD eingepflegt und committed werden, da dies den Herstellerzweig zerstören würde und der Import von zukünftigen Versionen wäre um ein Vielfaches schwerer, da es zu Konflikten kommen würde. Da einige Pakete Dateien enthalten, die zur Kompatibilität mit anderen Architekturen und Umgebungen wie FreeBSD gedacht sind, ist es zulässig diese Teile zu löschen, wenn sie für FreeBSD nicht von Interesse sind, da dadurch Speicherplatz gespart wird. Dateien welche ein Copyright enthalten und eine Art von Release-Informationen zu den vorhandenen Dateien, sollten nicht gelöscht werden. Falls es einfacher erscheint können die bmake-Makefiles vom Verzeichnisbaum durch einige Dienstprogramme automatisch erstellt werden, was es hoffentlich sogar noch einfacher macht auf eine Version zu aktualisieren. Ist dies geschehen, so stellen Sie bitte sicher diese Werkzeuge in das Verzeichnis src/tools mit dem Port an sich einzuchecken, so dass es für zukünftige Maintainer vorhanden ist. Im Verzeichnis src/contrib/tcl sollte eine Datei mit dem Namen FREEBSD-upgrade hinzugefügt werden und sollten den Stand wie folgt anzeigen: Welche Dateien wurden ausgelassen. Von wo die Original-Distribution stammt und/oder wo die offizielle Masterseite zu finden ist. Wohin Fehlebereinigungen an den Originalautor gesendet werden können. Möglicherweise eine Übersicht welche FreeBSD-spezifischen Änderungen vorgenommen wurden. Importieren Sie jedoch FREEBSD-upgrade nicht mit den beigesteuerten Quelldateien. Stattdessen sollen Sie cvs add FREEBSD-upgrade ; cvs ci nach dem initialen Import nutzen. Ein Beispiel von src/contrib/cpio sehen Sie hier: This directory contains virgin sources of the original distribution files on a "vendor" branch. Do not, under any circumstances, attempt to upgrade the files in this directory via patches and a cvs commit. New versions or official-patch versions must be imported. Please remember to import with "-ko" to prevent CVS from corrupting any vendor RCS Ids. For the import of GNU cpio 2.4.2, the following files were removed: INSTALL cpio.info mkdir.c Makefile.in cpio.texi mkinstalldirs To upgrade to a newer version of cpio, when it is available: 1. Unpack the new version into an empty directory. [Do not make ANY changes to the files.] 2. Remove the files listed above and any others that don't apply to FreeBSD. 3. Use the command: cvs import -ko -m 'Virgin import of GNU cpio v<version>' \ src/contrib/cpio GNU cpio_<version> For example, to do the import of version 2.4.2, I typed: cvs import -ko -m 'Virgin import of GNU v2.4.2' \ src/contrib/cpio GNU cpio_2_4_2 4. Follow the instructions printed out in step 3 to resolve any conflicts between local FreeBSD changes and the newer version. Do not, under any circumstances, deviate from this procedure. To make local changes to cpio, simply patch and commit to the main branch (aka HEAD). Never make local changes on the GNU branch. All local changes should be submitted to "cpio@gnu.ai.mit.edu" for inclusion in the next vendor release. obrien@FreeBSD.org - 30 March 1997 Es dürfte bisweilen notwendig sein belastende Dateien in den FreeBSD-Quelltextbaum zu integrieren. Zum Beispiel braucht ein Gerät ein Stück binären Code, welcher zuerst geladen werden muss, damit das Gerät funktioniert, und wir haben keine Quellen zu diesem Code, dann wird die binäre Datei als belastend bezeichnet. Die folgenden Richtlinien sind beim Aufnehmen von belastenden Dateien in den FreeBSD-Quelltext zu beachten. Jede Datei, die durch die System-CPU(s) ausgeführt wird und nicht im Quellformat vorliegt, ist belastend. Jede Datei, deren Lizenz restriktiver ist als die BSD- oder GNU-Lizenz, ist belastend. Eine Datei, welche herunterladbare binär Daten enthält, ist nicht belastend, ausser wenn (1) oder (2) hierfür gelten. Es muss in einem ASCII-Format gespeichert werden welches Architekturneutral ist (file2c oder uuencoding wird empfohlen). Jede belastende Datei braucht eine spezielle Genehmigung vom Core Team, bevor diese in das CVS-Repository aufgenommen werden darf. Belastende Dateien liegen unter src/contrib oder src/sys/contrib. Das komplette Modul sollte zusammen aufbewahrt werden. Es gibt keinen Grund dieses zu teilen, ausser es gibt einen Code-Austausch mit Quelltext, der nicht belastend ist. Objekt-Dateien sind arch/filename.o.uu> . Kernel-Dateien: Sollten immer nach conf/files.* verweisen (um den Bau einfach zu halten). Sollten immer in LINT sein, aber das Core team entscheidet je nach Fall, ob es auskommentiert wird oder nicht. Das Core Team kann sich zu einem späteren Zeitpunkt immer noch anders entscheiden. Der Release Engineer entscheidet, ob es in ein Release aufgenommen wird, oder nicht. Userland-Dateien: Core Team Das Core Team entscheidet, ob der Code Teil von make world wird oder nicht. Release Engineer Der Release Engineer entscheidet, ob es in das Release aufgenommen wird, oder nicht. Satoshi Asami Beigesteuert von Peter Wemm David O'Brien Sollten Sie den Support für Shared-Libraries bei einem Port oder einem Stück Software, welches dies nicht hat, hinzufügen, die Versionsnummer sollten diesen Regeln folgen. Im Allgemeinen hat die sich daraus resultierende Nummer nichts mit der Release-Version der Software zu tun. Die drei Grundsätze von Shared-Libraries sind: Starten Sie von 1.0. Gibt es eine Änderung die rückwärtskompatibel ist, so springen Sie zur nächsten Minor-Nummer (beachten Sie dass ELF-Systeme die Minor-Nummer ignorieren). Gibt es eine imkompatible Änderung, so springen Sie bitte zur nächsten Major-Nummer. Zum Beispiel hinzufügen von Funktionen und Fehlerbehebungen so wird zur nächsten Minor-Nummer gesprungen, beim Löschen einer Funktion, dem Ändern von Funktionsaufrufen usw., wird sich die Major-Nummer ändern. Bleiben Sie bei Versionsnummern in der Form major.minor (x.y). Unser dynamischer Linker a.out kann mit Versionsnummern in der Form x.y.z nicht gut umgehen. Jede Versionsnummer nach dem y (die dritte Zahl) wird völlig ignoriert, wenn Versionsnummern der Shared-Libraries verglichen werden, um zu sehen, welche Bibliothek hiermit verlinkt. Sind zwei Shared-Libraries vorhanden, die sich nur in der micro-Revision unterscheiden, so wird ld.so zu der höheren verlinken. Dies bedeutet: Wenn Sie mit libfoo.so.3.3.3 verlinken, dass der Linker nur 3.3 in den Header aufnimmt und linked alles, was mit libfoo.so.3 .(alles >=3).(höchste verfügbare Nummer). ld.so wird immer die höchste minor-Revision nutzen. Beispielsweise wird es die libc.so.2.2 bevorzugen statt der libc.so.2.0, auch dann, wenn das Programm ursprünglich mit libc.so.2.0 verlinkt war. Unser dynamischer ELF-Linker kann kejne Minor-Versionen handhaben. Dennoch sollten die Major- und Minor-Nummern genutzt werden, da unsere Makefiles damit umgehen können basierend auf dem entsprechenden System. Für non-port-Bibliotheken ist es auch unsere Richtlinie, die Shared-Library-Versionsnummer nur einem zwischen den Releases zu ändern. Es ist unsere Richtlinie die Major Nummer der Shared-Libraries nur bei Major OS-Releases zu ändern (beispielsweise von 3.0 auf 4.0). Wenn Sie also eine Änderunge an einer Systembibliothek vornehmen, welche eine neue Versionsnummer benötigt, überprüfen Sie die Commit-Logs des Makefiles. Es liegt in der Verantwortung des Committers, dass eine solche Änderungen seit dem letzten Release im Makefile der Shared-Library erscheint.