Ubuntu Manpage: deb-symbols - Debians erweiterte Vorlagendatei für Laufzeitbibliotheken

BEZEICHNUNG

       deb-symbols - Debians erweiterte Vorlagendatei für Laufzeitbibliotheken

ÜBERSICHT

       debian/Paket.symbols.Arch, debian/symbols.Arch, debian/Paket.symbols, debian/symbols

BESCHREIBUNG

Die Symboldateivorlagen werden in Debian-Quellpaketen ausgeliefert. Deren Format ist eine
Obermenge der in Binärpaketen ausgelieferten Symboldateien, siehe deb-symbols(5).

Kommentare
In Symboldateien werden Kommentare unterstützt. Jede Zeile, die mit ‚#’ als erstem Zeichen
beginnt, ist ein Kommentar, falls sie nicht mit ‚#include’ beginnt (siehe Abschnitt
Includes verwenden). Zeilen, die mit ‚#MISSING:’ anfangen, sind besondere Kommentare, die
verschwundene Symbole dokumentieren.

Verwendung der #PACKAGE#-Ersetzung
In einigen seltenen Fällen sind die Namen der Bibliotheken nicht auf allen Architekturen
gleich. Um zu vermeiden, dass der Paketname in der Symboldatei fest kodiert wird, können
Sie die Markierung #PACKAGE# verwenden. Während der Installation der Symboldatei wird sie
durch den echten Paketnamen ersetzt. Anders als die Markierung #MINVER# wird #PACKAGE# nie
in der Symboldatei innerhalb eines Binärpakets auftauchen.

Verwendung von Symbolkennzeichnungen
Symbolkennzeichnungen sind nützlich, um Symbole zu markieren, die in irgendeiner Weise
besonders sind. Jedes Symbol kann eine beliebige Anzahl zugeordneter Kennzeichnungen
besitzen. Während alle Kennzeichnungen ausgewertet und gespeichert werden, werden nur
einige von dpkg-gensymbols verstanden und lösen eine Spezialbehandlung der Symbole aus.
Lesen Sie den Unterabschnitt Standardsymbolkennzeichnungen für eine Referenz dieser
Kennzeichnungen.

Kennzeichnungsspezifikationen kommen direkt vor dem Symbolnamen (dazwischen sind keine
Leerraumzeichen erlaubt). Sie beginnen immer mit einer öffnenden Klammer (, enden mit
einer schließenden Klammer ) und müssen mindestens eine Kennzeichnung enthalten. Mehrere
Kennzeichnungen werden durch das Zeichen | getrennt. Jede der Kennzeichnungen kann
optional einen Wert enthalten, der von der Kennzeichnung durch das Zeichen = getrennt
wird. Kennzeichennamen und -werte können beliebige Zeichenketten sein, sie dürfen
allerdings keine der der besonderen Zeichen ) | = enthalten. Symbolnamen, die einer
Kennzeichnungsspezifikation folgen, können optional mit den Zeichen ' oder " zitiert
werden, um Leerraumzeichen darin zu erlauben. Falls keine Kennzeichnungen für das Symbol
spezifiziert sind, werden Anführungszeichen als Teil des Symbolnamens behandelt, der bis
zum ersten Leerzeichen geht.

(Kennz1=bin markiert|Name mit Leerraum)"zitiertes gekennz Symbol"@Base 1.0
(optional)gekennzeichnet_unzitiertes_Symbol@Base 1.0 1
ungekennzeichnetes_Symbol@Base 1.0
Das erste Symbol im Beispiel heißt I<zitiertes gekennz Symbol> und hat zwei Kennzeichnungen: I<Kennz1> mit dem Wert I<bin markiert> und I<Name mit Leerraum> ohne Wert. Das zweite Symbol heißt I<gekennzeichnet_unzitiertes_Symbol> und ist nur mit dem Kennzeichen namens I<optional> gekennzeichnet. Das letzte Symbol ist ein Beispiel eines normalen, nicht gekennzeichneten Symbols.

Da Symbolkennzeichnungen eine Erweiterung des Formats deb-symbols(5) sind, können sie nur
Teil der in Quellpaketen verwandten Symboldateien sein (diese Dateien sollten dann als
Vorlagen zum Bau der Symboldateien, die in Binärpakete eingebettet werden, gesehen
werden). Wenn dpkg-gensymbols ohne die Option -t aufgerufen wird, wird es alle Symbole
ausgeben, die zum Format deb-symbols(5) kompatibel sind: Es verarbeitet die Symbole
entsprechend der Anforderungen ihrer Standardkennzeichnungen und entfernt alle
Kennzeichnungen aus der Ausgabe. Im Gegensatz dazu werden alle Symbole und ihre
Kennzeichnungen (sowohl die Standardkennzeichnungen als auch die unbekannten) im
Vorlagenmodus (-t) in der Ausgabe beibehalten und in ihrer Originalform, wie sie geladen
wurden, auch geschrieben.

Standard-Symbolkennzeichnungen
optional
Ein als „optional“ gekennzeichnetes Symbol kann jederzeit von der Bibliothek
verschwinden und wird nie zum Fehlschlag von dpkg-gensymbols führen. Verschwundene
optionale Symbole werden kontinuierlich als MISSING (Fehlend) in dem Diff in jeder
neuen Paketversion auftauchen. Dieses Verhalten dient als Erinnerung für den Betreuer,
dass so ein Symbol aus der Symboldatei entfernt oder wieder der Bibliothek hinzugefügt
werden muss. Wenn das optionale Symbol, das bisher als MISSING angegeben gewesen war,
plötzlich in der nächsten Version wieder auftaucht, wird es wieder auf den Status
„existing“ (existierend) gebracht, wobei die minimale Version unverändert bleibt.

Diese Markierung ist für private Symbole nützlich, deren Verschwinden keinen ABI-Bruch
auslöst. Beispielsweise fallen die meisten C++-Template-Instanziierungen in diese
Kategorie. Wie jede andere Markierung kann auch diese einen beliebigen Wert haben: sie
könnte angeben, warum dieses Symbol als optional betrachtet wird.

arch=Architekturliste
arch-bits=Architektur-Bits
arch-endian=Architektur-Bytereihenfolge
Diese Markierungen erlauben es, den Satz an Architekturen einzugrenzen, auf denen das
Symbol existieren sollte. Die Markierungen arch-bits und arch-endian werden seit Dpkg
1.18.0 unterstützt. Wenn die Symbolliste mit den in der Bibliothek entdeckten Symbolen
aktualisiert wird, werden alle architekturspezifischen Symbole, die nicht auf die
aktuelle Host-Architektur passen, so behandelt, als ob sie nicht existierten. Falls
ein architekturspezifisches Symbol, das auf die aktuelle Host-Architektur passt, in
der Bibliothek nicht existiert, werden die normalen Regeln für fehlende Symbole
angewandt und dpkg-gensymbols könnte dadurch fehlschlagen. Auf der anderen Seite,
falls das architekturspezifische Symbol gefunden wurde, wenn es nicht existieren
sollte (da die aktuelle Host-Architektur nicht in der Markierung aufgeführt ist oder
nicht auf die Bytereihenfolge und Bits passt), wird sie architekturneutral gemacht
(d.h. die Architektur-, Architektur-Bits- und Architektur-Bytereihenfolgemarkierungen
werden entfernt und das Symbol wird im Diff aufgrund dieser Änderung auftauchen), aber
es wird nicht als neu betrachtet.

Beim Betrieb im standardmäßigen nicht-Vorlagen-Modus werden unter den
architekturspezifischen Symbolen nur die in die Symboldatei geschrieben, die auf die
aktuelle Host-Architektur passen. Auf der anderen Seite werden beim Betrieb im
Vorlagenmodus alle architekturspezifischen Symbole (darunter auch die von fremden
Architekturen) immer in die Symboldatei geschrieben.

Das Format der Architekturliste ist das gleiche wie das des Feldes Build-Depends in
debian/control (außer den einschließenden eckigen Klammern []). Beispielsweise wird
das erste Symbol aus der folgenden Liste nur auf den Architekturen Alpha, Any-amd64
und Ia64 betrachtet, das zweite nur auf Linux-Architekturen, während das dritte
überall außer auf Armel betrachtet wird.

(arch=alpha any-amd64 ia64)64_Bit_spezifisches_Symbol@Base 1.0
(arch=linux-any)Linux_spezifisches_Symbol@Base 1.0
(arch=!armel)Symbol_das_Armel_nicht_hat@Base 1.0

Architektur-Bits ist entweder 32 oder 64.

(arch-bits=32)32_Bit_spezifisches_Symbol@Base 1.0
(arch-bits=64)64_Bit_spezifisches_Symbol@Base 1.0

Architektur-Bytereihenfolge ist entweder little oder big.

(arch-endian=little)Little_Endian_spezifisches_Symbol@Base 1.0
(arch-endian=big)Big_Endian_spezifisches_Symbol@Base 1.0

Mehrere Einschränkungen können aneinandergehängt werden.

(arch-bits=32|arch-endian=little)32_Bit_Le_Symbol@Base 1.0

allow-internal
dpkg-gensymbols verfügt über eine interne Liste von Symbolen, die nicht in
Symboldateien auftauchen sollten, da sie normalerweise nur Nebeneffekte von
Implementierungsdetails in der Werkzeugkette darstellen (seit Dpkg 1.20.1). Falls Sie
aus irgendeinem Grund wollen, dass diese Symbole in der Symboldatei aufgenommen
werden, sollten Sie das Symbol mit allow-internal kennzeichnen. Dies kann für einige
grundlegende Bibliotheken der Werkzeugkette wie „libgcc“ notwendig sein.

ignore-blacklist
Ein veralteter Alias für allow-internal (seit Dpkg 1.20.1, unterstützt seit Dpkg
1.15.3).

c++ Gibt c++-Symbolmuster an. Lesen Sie den nachfolgenden Unterabschnitt Verwendung von
Symbolmustern.

symver
Gibt symver (Symbolversion)-Symbolmuster an. Lesen Sie den nachfolgenden
Unterabschnitt Verwendung von Symbolmustern.

regex
Gibt regex-Symbolmuster an. Lesen Sie den nachfolgenden Unterabschnitt Verwendung von
Symbolmustern.

Verwendung von Symbolmustern
Anders als die Standardsymbolspezifikation kann ein Muster mehrere reale Symbole aus der
Bibliothek abdecken. dpkg-gensymbols wird versuchen, jedes Muster auf jedes reale Symbol,
für das kein spezifisches Symbolgegenstück in der Symboldatei definiert ist, abzugleichen.
Wann immer das erste passende Muster gefunden wurde, werden alle Kennzeichnungen und
Eigenschaften als Basisspezifikation des Symbols verwandt. Falls keines der Muster passt,
wird das Symbol als neu betrachtet.

Ein Muster wird als verloren betrachtet, falls es auf kein Symbol in der Bibliothek passt.
Standardmäßig wird dies ein Versagen von dpkg-gensymbols in der Stufe -c1 oder höher
auslösen. Falls der Fehlschlag allerdings unerwünscht ist, kann das Muster mit der
Kennzeichnung optional markiert werden. Falls das Muster dann auf nichts passt, wird es im
Diff nur als MISSING (fehlend) auftauchen. Desweiteren kann das Muster wie jedes Symbol
auf die spezielle Architektur mit der Kennzeichnung arch beschränkt werden. Bitte lesen
Sie den Unterabschnitt Standard-Symbolkennzeichnungen oben für weitere Informationen.

Muster sind eine Erweiterung des Formats deb-symbols(5); sie sind daher nur in
Symboldatei-Vorlagen gültig. Die Musterspezifikationssyntax unterscheidet sich nicht von
der eines spezifischen Symbols. Allerdings dient der Symbolnamenteil der Spezifikation als
Ausdruck, der gegen Name@Version eines realen Symbols abgeglichen wird. Um zwischen den
verschiedenen Mustertypen zu unterscheiden, wird es typischerweise mit einer speziellen
Kennzeichnung gekennzeichnet.

Derzeit unterstützt dpkg-gensymbols drei grundlegene Mustertypen:

c++ Dieses Muster wird durch die Kennzeichnung c++ verzeichnet. Es passt nur auf die
entworrenen („demangled“) Symbolnamen (wie sie vom Hilfswerkzeug c++filt(1) ausgegeben
werden). Dieses Muster ist sehr hilfreich, um auf Symbole zu passen, bei dem die
verworrenen („mangled“) Namen sich auf verschiedenen Architekturen unterscheiden
während die entworrenen die gleichen bleiben. Eine Gruppe solcher Symbole ist non-
virtual thunks, die einen architekturspezifischen Versatz in ihren verworrenen Namen
eingebettet haben. Eine häufige Instanz dieses Falles ist ein virtueller Destruktor,
der unter rautenförmiger Vererbung ein nicht-virtuelles Thunk-Symbol benötigt. Selbst
wenn beispielsweise _ZThn8_N3NSB6ClassDD1Ev@Base auf 32 Bit-Architekturen
_ZThn16_N3NSB6ClassDD1Ev@Base auf 64 Bit-Architekturen ist, kann es mit einem einzigen
c++-Muster abgeglichen werden:

libdummy.so.1 libdummy1 #MINVER#
[…]
(c++)"non-virtual thunk to NSB::ClassD::~ClassD()@Base" 1.0
[…]

Der entworrene Name oben kann durch Ausführung folgenden Befehls erhalten werden:

$ echo '_ZThn8_N3NSB6ClassDD1Ev@Base' | c++filt

Bitte beachten Sie, dass per Definition zwar der verworrene Name in der Bibliothek
eindeutig ist, die aber nicht notwendigerweise für die entworrenen Namen zutrifft. Ein
Satz von unterschiedlichen realen Symbolen können den gleichen entworrenen Namen
haben. Beispielsweise ist das der Fall bei nicht-virtuellen Thunk-Symbolen in
komplexen Vererbungskonfigurationen oder bei den meisten Konstruktoren und
Destruktoren (da g++ typischerweise zwei reale Symbole für sie generiert). Da diese
Kollisionen aber auf dem ABI-Niveau passieren, sollten sie nicht die Qualität der
Symboldatei reduzieren.

symver
Dieses Muster wird durch die Kennzeichnung symver verzeichnet. Gut betreute
Bibliotheken verfügen über versionierte Symbole, wobei jede Version zu der Version der
Originalautoren passt, in der dieses Symbol hinzugefügt wurde. Falls das der Fall ist,
können Sie ein symver-Muster verwenden, das auf jedes zu einer spezifizierten Version
zugehörige Symbol passt. Beispiel:

libc.so.6 libc6 #MINVER#
(symver)GLIBC_2.0 2.0
[…]
(symver)GLIBC_2.7 2.7
access@GLIBC_2.0 2.2

Alle den Versionen GLIBC_2.0 und GLIBC_2.7 zugeordneten Symbole werden zu einer
minimalen Version 2.0 bzw. 2.7 führen, wobei das Symbol access@GLIBC_2.0 die Ausnahme
darstellt. Es wird zu einer minimalen Abhängigkeit auf libc6 Version 2.2 führen,
obwohl es im Geltungsbereich des Musters „(symver)GLIBC_2.0“ gehört, da spezielle
Symbole vor Mustern Vorrang haben.

Bitte beachten Sie, dass Platzhaltermuster im alten Format (angezeigt durch
„*@version“ im Symbolnamenfeld) zwar noch unterstützt werden, sie aber durch die
Syntax im neuen Format „(symver|optional)version“ abgelöst wurden. Beispielsweise
sollte „*@GLIBC_2.0 2.0“ als „(symver|optional)GLIBC_2.0 2.0“ geschrieben werden,
falls das gleiche Verhalten benötigt wird.

regex
Muster mit regulären Ausdrücken werden durch die Kennzeichnung regex verzeichnet. Sie
passen auf den regulären Ausdruck von Perl, der im Symbolnamenfeld angegeben ist. Ein
regulärer Ausdruck wird wie er ist abgeglichen. Denken Sie daher daran, ihn mit dem
Zeichen ^ zu beginnen, da er ansonsten auf jeden Teil der Zeichenkette des realen
Symbols name@version passt. Beispiel:

libdummy.so.1 libdummy1 #MINVER#
(regex)"^mystack_.*@Base$" 1.0
(regex|optional)"private" 1.0

Symbole wie „mystack_new@Base“, „mystack_push@Base“, „mystack_pop@Base“ usw. passen
auf das erste Muster, während dies z.B. für „ng_mystack_new@Base“ nicht der Fall ist.
Das zweite Muster wird auf alle Symbole, die die Zeichenkette „private“ in ihren Namen
enthalten, passen und die abgeglichenen Symbole erben die Kennzeichnung optional vom
Muster.

Die oben aufgeführten grundlegenden Muster können - wo es Sinn ergibt - kombiniert werden.
In diesem Fall werden sie in der Reihenfolge verarbeitet, in der die Kennzeichnungen
angegeben sind. Im Beispiel

(c++|regex)"^NSA::ClassA::Private::privmethod\d$int$@Base" 1.0
(regex|c++)N3NSA6ClassA7Private11privmethod\dEi@Base 1.0

werden die Symbole „_ZN3NSA6ClassA7Private11privmethod1Ei@Base“ und
„_ZN3NSA6ClassA7Private11privmethod2Ei@Base“ verglichen. Beim Vergleichen des ersten
Musters wird das rohe Symbol erst als C++-Symbol entworren, dann wird der entworrene Name
mit den regulären Ausdruck verglichen. Auf der anderen Seite wird beim Vergleichen des
zweiten Musters der reguläre Ausdruck gegen den rohen Symbolnamen verglichen, dann wird
das Symbol überprüft, ob es ein C++-Symbol ist, indem das Entwirren versucht wird. Ein
Fehlschlag eines einfachen Musters wird zum Fehlschlag des gesamten Musters führen. Daher
wird beispielsweise „__N3NSA6ClassA7Private11privmethod\dEi@Base“ auf keines der Muster
passen, da es kein gültiges C++-Symbol ist.

Im Allgemeinen werden die Muster in zwei Kategorien eingeteilt: Aliase (grundlegende c++-
und symver-Muster) und generische Muster (regex und alle Kombinationen grundlegender
Muster). Abgleichen von grundlegenden alias-basierenden Mustern ist schnell (O(1)),
während generische Muster O(N) (wobei N die Anzahl der generischen Muster ist) für jedes
Symbol ist. Daher wird empfohlen, generische Muster nicht zu viel zu verwenden.

Wenn mehrere Muster auf das gleiche Symbol passen, werden Aliase (zuerst c++, dann symver)
gegenüber den generischen Mustern bevorzugt. Generische Muster werden in der Reihenfolge,
in der sie in der Symboldateivorlage gefunden werden, verglichen, bis zum ersten Erfolg.
Beachten Sie aber, dass das manuelle Anordnen der Vorlagendateieinträge nicht empfohlen
wird, da dpkg-gensymbols Diffs basierend auf der alphanumerischen Reihenfolge ihrer Namen
erstellt.

Includes verwenden
Wenn der Satz der exportierten Symbole sich zwischen Architekturen unterscheidet, kann es
ineffizient werden, eine einzige Symboldatei zu verwenden. In diesen Fällen kann sich eine
Include-Direktive in einer Reihe von Arten als nützlich erweisen:

• Sie können den gemeinsamen Teil in eine externe Datei auslagern und diese Datei dann
in Ihre Paket.symbols.Arch-Datei mit einer include-Direktive wie folgt einbinden:

#include "I<Pakete>.symbols.common"

• Die Include-Direktive kann auch wie jedes Symbol gekennzeichnet werden:

(Kennzeichen|…|KennzeichenN)#include "einzubindende-Datei"

Als Ergebnis werden alle Symbole aus der einzubindende-Datei standardmäßig als mit
Kennzeichen … KennzeichenN gekennzeichnet betrachtet. Sie können diese Funktionalität
benutzen, um eine gemeinsame Datei Paket.symbols zu erstellen, die
architekturspezifische Symboldateien einbindet:

gemeinsames_Symbol1@Base 1.0
(arch=amd64 ia64 alpha)#include "Paket.symbols.64bit"
(arch=!amd64 !ia64 !alpha)#include "Paket.symbols.32bit"
gemeinsames_Symbol2@Base 1.0

Die Symboldateien werden Zeile für Zeile gelesen und include-Direktiven werden bearbeitet,
sobald sie erkannt werden. Das bedeutet, dass der Inhalt der mit include eingebundenen
Datei jeden Inhalt überschreiben kann, der vor der Include-Direktive aufgetaucht ist und
Inhalt nach der Direktive alles aus der eingebundenen Datei überschreiben kann. Jedes
Symbol (oder sogar weitere #include-Direktiven) in der eingebundenen Datei kann
zusätzliche Kennzeichnungen spezifizieren oder Werte der vererbten Kennzeichnungen in
ihrer Kennzeichnungsspezifikation überschreiben. Allerdings gibt es keine Möglichkeit für
ein Symbol, die ererbten Kennzeichnungen zu überschreiben.

Eine eingebundene Datei kann die Kopfzeile wiederholen, die den SONAME der Bibliothek
enthält. In diesem Fall überschreibt sie jede vorher gelesene Kopfzeile. Allerdings ist es
im Allgemeinen am besten, die Wiederholung von Kopfzeilen zu vermeiden. Eine Art, dies zu
erreichen, ist wie folgt:

#include "libirgendwas1.symbols.common"
arch_spezifisches_Symbol@Base 1.0

SIEHE AUCH

       deb-symbols(5), dpkg-shlibdeps(1), dpkg-gensymbols(1).

ÜBERSETZUNG

       Die deutsche Übersetzung wurde 2004, 2006-2022 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.