deb-symbols - Debians erweiterte Vorlagendatei für Laufzeitbibliotheken
debian/Paket.symbols.Arch,
debian/symbols.Arch,
debian/Paket.symbols,
debian/symbols
Die Symboldateivorlagen werden in Debian-Quellpaketen ausgeliefert. Deren Format
ist eine Obermenge der in Binärpaketen ausgelieferten Symboldateien,
siehe
deb-symbols(5).
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.
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.
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.
- 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.
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 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.
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
deb-symbols(5),
dpkg-shlibdeps(1),
dpkg-gensymbols(1).
Die deutsche Übersetzung wurde 2004, 2006-2023 von Helge Kreutzmann
<
[email protected]>, 2007 von Florian Rehnisch <
[email protected]>
und 2008 von Sven Joachim <
[email protected]> 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.