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

bezeichnung
übersicht
beschreibung
symboldateien pflegen
optionen
umgebung
siehe auch
übersetzung

Provided by: dpkg-dev_1.22.15ubuntu1_all

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 erscheint.

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).

Dieses Programm wurde in Dpkg 1.14.8 hinzugefügt.

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 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

       DEB_HOST_ARCH
           Setzt die Host-Architektur, falls die Option --arch nicht angegeben wurde.

       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-2025 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.