BEZEICHNUNG

       dpkg-gensymbols - Symboldateien (Abhängigkeitsinformationen für Laufzeitbibliotheken)
       erstellen

ÜBERSICHT

       dpkg-gensymbols [Option …]

BESCHREIBUNG

       dpkg-gensymbols durchsucht einen temporären Baubaum (standardmäßig debian/tmp), sucht nach
       Bibliotheken und erstellt eine Datei symbols, die diese beschreibt. Diese Datei wird,
       falls sie nicht leer ist, in das Unterverzeichnis DEBIAN des Baubaums installiert, so dass
       sie schlussendlich in der Steuerinformation des Pakets auftaucht.

       Beim Erstellen dieser Dateien verwendet es als Eingabe einige vom Betreuer bereitgestellte
       Symboldateien. Es sucht nach den folgenden Dateien (und verwendet die erste, die gefunden
       wird):

       •   debian/Paket.symbols.Architektur

       •   debian/symbols.Architektur

       •   debian/Paket.symbols

       •   debian/symbols

       Der Hauptzweck dieser Dateien besteht darin, die minimale Version bereitzustellen, die mit
       jedem von der Bibliothek bereitgestellten Symbol verknüpft ist. Normalerweise entspricht
       dies der ersten Version des Pakets, die dieses Symbol bereitgestellt hat, kann aber vom
       Betreuer erhöht werden, falls die ABI des Symbols ohne brechen der Rückwärtskompatibilität
       erweitert wurde. Es liegt in der Verantwortung des Betreuers, diese Dateien aktuell zu
       halten, aber dpkg-gensymbols hilft dabei.

       Wenn die erstellten Symboldateien sich von denen, die der Betreuer bereitgestellt hat,
       unterscheiden, wird dpkg-gensymbols einen Diff zwischen den zwei Versionen anzeigen. Falls
       die Unterschiede desweiteren zu gravierend sind, wird es sogar fehlschlagen (Sie können
       einstellen, wie große Unterschiede Sie tolerieren können, sehen Sie hierzu die Option -c).

SYMBOLDATEIEN PFLEGEN

       Das grundlegende Austauschformat der Symboldatei wird in deb-symbols(5) beschrieben. Dies
       wird von den in Binärpaketen enthaltenen Symboldateien verwandt. Diese werden aus Vorlage-
       Symboldateien erstellt, deren Format auf Ersterem basiert, in deb-src-symbols(5)
       beschrieben und in Quellpaketen enthalten ist.

       Die Symboldateien sind nur wirklich nützlich, falls sie die Entwicklung eines Paketes über
       mehrere Veröffentlichungen hinweg wiedergeben. Daher muss der Betreuer sie immer
       aktualisieren, wenn eine neues Symbol hinzugefügt wird, so dass die zugeordnete minimale
       Version der Realität entspricht.

       Die in den Bauprotokollen enthaltenen Diffs können als Startpunkt benutzt werden, aber
       zusätzlich hat der Betreuer sicherzustellen, dass sich das Verhalten dieser Symbole nicht
       derart geändert hat, dass irgendetwas, was diese Symbole verwendet und gegen die neue
       Version gelinkt ist, daran hindern würde, mit der alten Version zu funktionieren.

       Meistens kann der Diff direkt auf die Datei debian/Paket.symbols angewandt werden.
       Allerdings werden normalerweise weitere Anpassungen notwendig: es wird beispielsweise
       empfohlen, die Debian-Revision von der minimalen Version zu entfernen, so dass Backports
       mit einer niedrigeren Versionsnummer, aber der gleichen Version der Originalautoren immer
       noch die erstellten Abhängigkeiten erfüllen. Falls die Debian-Revision nicht entfernt
       werden kann, da das Symbol wirklich von der Debian-spezifischen Änderung hinzugefügt
       wurde, dann sollte der Version ‚~’ angehängt werden.

       Bevor irgendein Patch auf die Symboldatei angewendet wird, sollte der Betreuer zweimal
       prüfen, dass der Patch vernünftig ist. Öffentliche Symbole sollten nicht verschwinden,
       daher sollte der Patch idealerweise nur neue Zeilen hinzufügen.

       Beachten Sie, dass Sie in Symboldateien Kommentare verwenden können.

       Vergessen Sie nicht, zu überprüfen, ob alte Versionen aktualisiert werden müssen. Es gibt
       für dpkg-gensymbols keine Möglichkeit, hierzu eine Warnung auszugeben. Wird der Diff blind
       akzeptiert oder wird angenommen, dass nichts geändert werden muss, wenn es keinen Diff
       gibt, ohne auf Änderungen zu prüfen, kann dies dazu führen, dass lockere Abhängigkeiten
       erzeugt werden, laut deren mit älteren Versionen gearbeitet werden kann, obwohl dies nicht
       möglich ist. Dies wird zu schwer zu findenden Fehlern bei (teilweisen) Upgrades führen.

   Gute Bibliotheksverwaltung
       Eine gut verwaltete Bibliothek hat die folgenden Eigenschaften:

       •   ihre API ist stabil (öffentliche Symbole entfallen nie, nur neue öffentliche Symbole
           werden hinzugefügt) und inkompatible Änderungen erfolgen nur, wenn sich der SONAME
           ändert,

       •   idealerweise verwendet sie Symbolversionierung, um ABI-Stabilität trotz interner
           Änderungen und API-Erweiterungen zu erreichen,

       •   sie exportiert nie private Symbole (als Hilfslösung können diese als optional
           gekennzeichnet werden).

       Bei der Verwaltung der Symboldatei kann das Auftauchen und Verschwinden von Symbolen
       leicht bemerkt werden. Es ist aber schwieriger, inkompatbile API- und ABI-Änderungen zu
       bemerken. Daher sollte der Betreuer intensiv die Changelog-Einträge der Originalautoren
       durchschauen und nach Fällen suchen, in denen die Regeln der guten Bibliotheksverwaltung
       gebrochen wurden. Falls mögliche Probleme entdeckt wurden, sollten der Originalautor
       informiert werden, da eine Korrektur vom Originalautor immer besser als eine Debian-
       spezifische Hilfslösung ist.

OPTIONEN

       -PPaketbauverzeichnis
           Sucht nach Paketbauverzeichnis statt nach debian/tmp.

       -pPaket
           Definiert den Paketnamen. Wird benötigt, falls mehr als ein binäres Paket in
           debian/control aufgeführt ist (oder falls es keine Datei debian/control gibt).

       -vVersion
           Definiert die Paketversion. Standardmäßig wird die Version aus debian/changelog
           entnommen. Benötigt, falls der Aufruf außerhalb des Quellpaketbaums erfolgt.

       -eBibliotheksdatei
           Untersucht nur die explizit aufgeführten Bibliotheken, statt nach allen öffentlichen
           Bibliotheken zu suchen. Sie können Shell-Muster, die zur Expansion von Pfadnamen
           verwandt werden (siehe die Handbuchseite File::Glob(3perl) für weitere Details) in
           Bibliotheksdatei verwenden, um mehrere Bibliotheken mit einem einzelnen Argument
           abzugleichen (andernfalls benötigen Sie mehrere -e).

       -lVerzeichnis
           Stellt Verzeichnis der Liste der zu durchsuchenden privaten Laufzeitbibliotheken voran
           (seit Dpkg 1.19.1). Diese Option kann mehrfach angegeben werden.

           Hinweis: Verwenden Sie diese Variable, statt LD_LIBRARY_PATH zu setzen, da diese
           Umgebungsvariable verwandt wird, um den Laufzeit-Linker zu steuern und ihr Missbrauch
           zum Setzen von Pfaden zu Laufzeitbibliotheken zur Bauzeit kann beispielsweise beim
           Cross-Kompilieren problematisch werden.

       -IDateiname
           Verwendet Dateiname als Referenzdatei, um die Symboldatei zu erstellen, die dann im
           Paket selbst integriert wird.

       -O[Dateiname]
           Die erstellte Symbols-Datei auf die Standardausgabe oder nach Dateiname, falls
           angegeben, ausgeben statt in debian/tmp/DEBIAN/symbols (oder Paket-
           Bauverzeichnis/DEBIAN/symbols, falls -P verwandt wurde). Falls Dateiname bereits
           existiert, wird deren Inhalt als Grundlage für die erstellte Symboldatei verwandt. Sie
           können diese Funktionalität benutzen, um eine Symboldatei zu aktualisieren, so dass
           sie zu einer neueren Version der Originalautoren Ihrer Bibliothek passt.

       -t  Schreibt die Symboldatei im Vorlagenmodus statt im zu deb-symbols(5) kompatiblen
           Format. Der Hauptunterschied besteht darin, dass im Vorlagenmodus die Symbolnamen und
           Kennzeichnungen in ihrer Originalform geschrieben werden, im Gegensatz zu den
           verarbeiteten Symbolnamen mit entfernten Kennzeichnungen im Kompatibilitätsmodus.
           Desweiteren könnten einige Symbole beim Schreiben einer Standard-deb-symbols(5)-Datei
           entfernt werden (gemäß der Verarbeitungsregeln für Kennzeichen), während in der
           Symboldateivorlage immer alle Symbole geschrieben werden.

       -c[0-4]
           Definiert die Prüfungen, die beim Vergleich der erstellten Symboldatei mit der
           Vorlagendatei als Startpunkt erfolgen sollen. Standardstufe ist 1. Zunehmende Stufen
           führen mehr Prüfungen durch und enthalten alle Prüfungen der niedrigeren Stufen.

           Stufe 0
               schlägt nie fehl.

           Stufe 1
               Schlägt fehl, wenn einige Symbole verschwunden sind.

           Stufe 2
               falls einige neue Symbole eingeführt wurden.

           Stufe 3
               falls einige Bibliotheken verschwunden sind.

           Stufe 4
               falls einige Bibliotheken hinzugekommen sind.

           Dieser Wert kann von der Umgebungsvariablen DPKG_GENSYMBOLS_CHECK_LEVEL außer Kraft
           gesetzt werden.

       -q  Ruhig verhalten und nie einen Diff zwischen der erstellten Symboldatei und der als
           Startpunkt verwandten Vorlagendatei erstellen oder keine Warnungen bezüglich
           neuer/verschwundener Bibliotheken oder neuer/verschwundener Symbole ausgeben. Diese
           Option deaktiviert nur die informative Ausgabe, aber nicht die Prüfungen selbst (sehen
           Sie hierzu die Option -c).

       -aArchitektur
           Nimmt Arch als Host-Architektur beim Verarbeiten der Symboldateien an. Verwenden Sie
           diese Option, um Symboldateien oder Diffs für beliebige Architekturen zu erstellen,
           vorausgesetzt, die Binärprogramme sind bereits verfügbar.

       -d  Debug-Modus aktivieren. Eine Vielzahl von Meldungen wird angezeigt, um zu erklären,
           was dpkg-gensymbols durchführt.

       -V  Ausführlichen Modus aktivieren. Die erstellte Symboldatei enthält veraltete Symbole
           als Kommentare. Im Vorlagenmodus werden Mustersymbole desweiteren von Kommentaren
           gefolgt, die die echten Symbole aufführen, die auf dieses Muster passen.

       -?, --help
           Zeigt einen Hinweis zum Aufruf und beendet das Programm.

       --version
           Gibt die Version aus und beendet das Programm.

UMGEBUNG

       DPKG_GENSYMBOLS_CHECK_LEVEL
           Setzt die Befehlsüberprüfungsstufe außer Kraft, selbst wenn das Befehlszeilenargument
           -c übergeben wurde (beachten Sie, dass dies der üblichen Konvention widerspricht,
           demnach Befehlszeilenargumente Vorrang gegenüber Umgebungsvariablen haben).

       DPKG_COLORS
           Setzt den Farbmodus (seit Dpkg 1.18.5). Die derzeit unterstützten Werte sind: auto
           (Vorgabe), always und never.

       DPKG_NLS
           Falls dies gesetzt ist, wird es zur Entscheidung, ob Native Language Support, auch als
           Unterstützung für Internationalisierung (oder i18n) bekannt, aktiviert wird (seit Dpkg
           1.19.0). Die akzeptierten Werte sind: 0 und 1 (Vorgabe).

SIEHE AUCH

       <https://people.redhat.com/drepper/symbol-versioning>,
       <https://people.redhat.com/drepper/goodpractice.pdf>,
       <https://people.redhat.com/drepper/dsohowto.pdf>, deb-src-symbol(5), deb-symbols(5), dpkg-
       shlibdeps(1).

ÜBERSETZUNG

       Die deutsche Übersetzung wurde 2004, 2006-2021 von Helge Kreutzmann
       <debian@helgefjell.de>, 2007 von Florian Rehnisch <eixman@gmx.de> und 2008 von Sven
       Joachim <svenjoac@gmx.de> angefertigt. Diese Übersetzung ist Freie Dokumentation; lesen
       Sie die GNU General Public License Version 2 oder neuer für die Kopierbedingungen. Es gibt
       KEINE HAFTUNG.