Commit | Line | Data |
---|---|---|
1479465f GJ |
1 | .\" dpkg manual page - dpkg-gensymbols(1) |
2 | .\" | |
3 | .\" Copyright © 2007-2011 Raphaël Hertzog <hertzog@debian.org> | |
4 | .\" Copyright © 2009-2010 Modestas Vainius <modestas@vainius.eu> | |
5 | .\" Copyright © 2012-2015 Guillem Jover <guillem@debian.org> | |
6 | .\" | |
7 | .\" This is free software; you can redistribute it and/or modify | |
8 | .\" it under the terms of the GNU General Public License as published by | |
9 | .\" the Free Software Foundation; either version 2 of the License, or | |
10 | .\" (at your option) any later version. | |
11 | .\" | |
12 | .\" This is distributed in the hope that it will be useful, | |
13 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
14 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
15 | .\" GNU General Public License for more details. | |
16 | .\" | |
17 | .\" You should have received a copy of the GNU General Public License | |
18 | .\" along with this program. If not, see <https://www.gnu.org/licenses/>. | |
19 | . | |
20 | .\"******************************************************************* | |
21 | .\" | |
22 | .\" This file was generated with po4a. Translate the source file. | |
23 | .\" | |
24 | .\"******************************************************************* | |
25 | .TH dpkg\-gensymbols 1 %RELEASE_DATE% %VERSION% dpkg\-Programmsammlung | |
26 | .nh | |
27 | .SH BEZEICHNUNG | |
28 | dpkg\-gensymbols \- erstelle Symboldateien (Abhängigkeitsinformationen für | |
29 | Laufzeitbibliotheken) | |
30 | . | |
31 | .SH ÜBERSICHT | |
32 | \fBdpkg\-gensymbols\fP [\fIOption\fP …] | |
33 | . | |
34 | .SH BESCHREIBUNG | |
35 | \fBdpkg\-gensymbols\fP durchsucht einen temporären Baubaum (standardmäßig | |
36 | debian/tmp), sucht nach Bibliotheken und erstellt eine Datei \fIsymbols\fP, die | |
37 | diese beschreibt. Diese Datei wird, falls sie nicht leer ist, in das | |
38 | Unterverzeichnis DEBIAN des Baubaums installiert, so dass sie schlussendlich | |
39 | in der Steuerinformation des Pakets auftaucht. | |
40 | .P | |
41 | Beim Erstellen dieser Dateien verwendet es als Eingabe einige vom Betreuer | |
42 | bereitgestellte Symboldateien. Es sucht nach den folgenden Dateien (und | |
43 | verwendet die erste, die gefunden wird): | |
44 | .IP • 4 | |
45 | debian/\fIPaket\fP.symbols.\fIArchitektur\fP | |
46 | .IP • 4 | |
47 | debian/symbols.\fIArchitektur\fP | |
48 | .IP • 4 | |
49 | debian/\fIPaket\fP.symbols | |
50 | .IP • 4 | |
51 | debian/symbols | |
52 | .P | |
53 | Der Hauptzweck dieser Dateien besteht darin, die minimale Version | |
54 | bereitzustellen, die mit jedem von der Bibliothek bereitgestellten Symbol | |
55 | verknüpft ist. Normalerweise entspricht dies der ersten Version des Pakets, | |
56 | die dieses Symbol bereitgestellt hat, kann aber vom Betreuer erhöht werden, | |
57 | falls die ABI des Symbols ohne Brechen der Rückwärtskompatibilität erweitert | |
58 | wurde. Es liegt in der Verwantwortung des Betreuers, diese Dateien aktuell | |
59 | zu halten, aber \fBdpkg\-gensymbols\fP hilft dabei. | |
60 | .P | |
61 | Wenn die erstellten Symboldateien sich von denen, die der Betreuer | |
62 | bereitgestellt hat, unterscheiden, wird \fBdpkg\-gensymbols\fP ein Diff zwischen | |
63 | den zwei Versionen anzeigen. Falls die Unterschiede desweiteren zu | |
64 | gravierend sind, wird es sogar fehlschlagen (Sie können einstellen, wie | |
65 | große Unterschiede Sie tolerieren können, sehen Sie hierzu die Option | |
66 | \fB\-c\fP). | |
67 | .SH "SYMBOLDATEIEN PFLEGEN" | |
68 | Die Symboldateien sind nur wirklich nützlich, falls sie die Entwicklung | |
69 | eines Paketes über mehrere Veröffentlichungen hinweg wiedergeben. Daher muss | |
70 | der Betreuer sie immer aktualisieren, wenn eine neues Symbol hinzugefügt | |
71 | wird, so dass die zugeordnete minimale Version der Realität entspricht. Die | |
72 | in den Bauprotokollen enthaltenen Diffs können als Startpunkt benutzt | |
73 | werden, aber zusätzlich hat der Betreuer sicherzustellen, dass sich das | |
74 | Verhalten dieser Symbole nicht derart geändert hat, dass irgendetwas, was | |
75 | diese Symbole verwendet und gegen die neue Version gelinkt ist, daran | |
76 | hindern würde, mit der alten Version zu funktionieren. Meistens kann der | |
77 | Diff direkt auf die Datei debian/\fIPaket\fP.symbols angewandt | |
78 | werden. Allerdings werden normalerweise weitere Anpassungen notwendig: es | |
79 | wird beispielsweise empfohlen, die Debian\-Revision von der minimalen Version | |
80 | zu entfernen, so dass Backports mit einer niedrigeren Versionsnummer aber | |
81 | der gleichen Version der Originalautoren immer noch die erstellten | |
82 | Abhängigkeiten erfüllen. Falls die Debian\-Revision nicht entfernt werden | |
83 | kann, da das Symbol wirklich von der Debian\-spezifischen Änderung | |
84 | hinzugefügt wurde, dann sollte der Version ‚\fB~\fP’ angehängt werden. | |
85 | .P | |
86 | Bevor irgendein Patch auf die Symboldatei angewendet wird, sollte der | |
87 | Betreuer zweimal prüfen, dass der Patch vernünftig ist. Öffentliche Symbole | |
88 | sollten nicht verschwinden, daher sollte der Patch idealerweise nur neue | |
89 | Zeilen hinzufügen. | |
90 | .P | |
91 | Beachten Sie, dass Sie in Symboldateien Kommentare einfügen können: jede | |
92 | Zeile, die mit ‚#’ als ersten Zeichen beginnt, ist ein Kommentar, falls sie | |
93 | nicht mit ‚#include’ beginnt (siehe Abschnitt \fBIncludes | |
94 | verwenden\fP). Zeilen, die mit ‚#MISSING:’ anfangen, sind besondere | |
95 | Kommentare, die verschwundene Symbole dokumentieren. | |
96 | .P | |
97 | Vergessen Sie nicht, zu überprüfen, ob alte Versionen aktualisiert werden | |
98 | müssen. Es gibt für \fBdpkg\-gensymbols\fP keine Möglichkeit, hierzu eine | |
99 | Warnung auszugeben. Wird der Diff blind akzeptiert oder wird angenommen, | |
100 | dass nichts geändert werden muss, wenn es keinen Diff gibt, ohne auf | |
101 | Änderungen zu prüfen, kann dies dazu führen, dass lockere Abhängigkeiten | |
102 | erzeugt werden, laut deren mit älteren Versionen gearbeitet werden kann, | |
103 | obwohl dies nicht möglich ist. Dies wird zu schwer zu findenden Fehlern bei | |
104 | (teilweisen) Upgrades führen. | |
105 | .SS "Verwendung der #PACKAGE#\-Ersetzung" | |
106 | .P | |
107 | In einigen seltenen Fällen unterscheidet sich der Name der Bibliothek auf | |
108 | verschiedenen Architekturen. Um zu vermeiden, dass der Paketname in der | |
109 | Symboldatei fest kodiert wird, können Sie die Markierung \fI#PACKAGE#\fP | |
110 | verwenden. Während der Installation der Symboldatei wird sie durch den | |
111 | echten Paketnamen ersetzt. Anders als die Markierung \fI#MINVER#\fP wird | |
112 | \fI#PACKAGE#\fP nie in der Symboldatei innerhalb eines Binärpakets auftauchen. | |
113 | .SS "Verwendung von Symbolkennzeichnungen" | |
114 | .P | |
115 | Symbolkennzeichnungen sind nützlich, um Symbole zu markieren, die in | |
116 | irgendeiner Weise besonders sind. Jedes Symbol kann eine beliebige Anzahl | |
117 | zugeordneter Kennzeichnungen besitzen. Während alle Kennzeichnungen | |
118 | ausgewertet und gespeichert werden, werden nur einige von \fBdpkg\-gensymbols\fP | |
119 | verstanden und lösen eine Spezialbehandlung der Symbole aus. Lesen Sie den | |
120 | Unterabschnit \fBStandardsymbolkennzeichnungen\fP für eine Referenz dieser | |
121 | Kennzeichnungen. | |
122 | .P | |
123 | Kennzeichnungsspezifikationen kommen direkt vor dem Symbolnamen (dazwischen | |
124 | sind keine Leerraumzeichen erlaubt). Sie beginnen immer mit einer öffnenden | |
125 | Klammer \fB(\fP, enden mit einer schließenden Klammer \fB)\fP und müssen | |
126 | mindestens eine Kennzeichnung enthalten. Mehrere Kennzeichnungen werden | |
127 | durch das Zeichen \fB|\fP getrennt. Jede Kennzeichnungen kann optional einen | |
128 | Wert enthalten, der von der Kennzeichnung durch das Zeichen \fB=\fP getrennt | |
129 | wird. Kennzeichennamen und \-werte können beliebige Zeichenketten sein, sie | |
130 | dürfen allerdings keine der der besonderen Zeichen \fB)\fP \fB|\fP \fB=\fP | |
131 | enthalten. Symbolnamen, die einer Kennzeichnungsspezifikation folgen, können | |
132 | optional mit den Zeichen \fB'\fP oder \fB"\fP zitiert werden, um Leerraumzeichen | |
133 | darin zu erlauben. Falls keine Kennzeichnungen für das Symbol spezifiziert | |
134 | sind, werden Zitatzeichen als Teil des Symbolnamens behandelt, der bis zum | |
135 | ersten Leerzeichen geht. | |
136 | .P | |
137 | (Kennz1=bin markiert|Name mit Leerraum)"zitiertes gekennz Symbol"@Base 1.0 | |
138 | (optional)gekennzeichnet_unzitiertes_Symbol@Base 1.0 1 | |
139 | ungekennzeichnetes_Symbol@Base 1.0 | |
140 | .P | |
141 | Das erste Symbol im Beispiel heißt \fIzitiertes gekennz Symbol\fP und hat zwei | |
142 | Kennzeichnungen: \fIKennz1\fP mit dem Wert \fIbin markiert\fP und \fIName mit | |
143 | Leerraum\fP ohne Wert. Das zweite Symbol heißt | |
144 | \fIgekennzeichnet_unzitiertes_Symbol\fP und ist nur mit dem Kennzeichen namens | |
145 | \fIoptional\fP gekennzeichnet. Das letzte Symbol ist ein Beispiel eines | |
146 | normalen, nicht gekennzeichneten Symbols. | |
147 | .P | |
148 | Da Symbolkennzeichnungen eine Erweiterung des Formats \fBdeb\-symbols(5)\fP | |
149 | sind, können sie nur Teil der in Quellpaketen verwandten Symboldateien sein | |
150 | (diese Dateien sollten dann als Vorlagen zum Bau der Symboldateien, die in | |
151 | Binärpakete eingebettet werden, gesehen werden). Wenn \fBdpkg\-gensymbols\fP | |
152 | ohne die Option \fB\-t\fP aufgerufen wird, wird es alle Symbole ausgeben, die | |
153 | zum Format \fBdeb\-symbols\fP(5) kompatibel sind: Es verarbeitet die Symbole | |
154 | entsprechend der Anforderungen ihrer Standardkennzeichnungen und entfernt | |
155 | alle Kennzeichnungen aus der Ausgabe. Im Gegensatz dazu werden alle Symbole | |
156 | und ihre Kennzeichnungen (sowohl die Standardkennzeichnungen als auch die | |
157 | unbekannten) im Vorlagenmodus (\fB\-t\fP) in der Ausgabe beibehalten und in | |
158 | ihrer Originalform wie sie geladen wurden auch geschrieben. | |
159 | .SS Standard\-Symbolkennzeichnungen | |
160 | .TP | |
161 | \fBoptional\fP | |
162 | Ein als »optional« gekennzeichnetes Symbol kann jederzeit von der Bibliothek | |
163 | verschwinden und wird nie zum Fehlschlag von \fBdpkg\-gensymbols\fP | |
164 | führen. Verschwundene optionale Symbole werden kontinuierlich als MISSING | |
165 | (Fehlend) in dem Diff in jeder neuen Paketversion auftauchen. Dieses | |
166 | Verhalten dient als Erinnerung für den Betreuer, dass so ein Symbol aus der | |
167 | Symboldatei entfernt oder wieder der Bibliothek hinzugefügt werden | |
168 | muss. Wenn das optionale Symbol, dass bisher als MISSING bezeichnet gewesen | |
169 | war, plötzlich in der nächsten Version wieder auftaucht, wird es wieder auf | |
170 | den Status „existing“ (existierend) gebracht, wobei die minimale Version | |
171 | unverändert bleibt. | |
172 | ||
173 | Diese Markierung ist für private Symbole nützlich, deren Verschwinden keinen | |
174 | ABI\-Bruch auslöst. Beispielsweise fallen die meisten | |
175 | C++\-Template\-Instanziierungen in diese Kategorie. Wie jede andere Markierung | |
176 | kann auch diese einen beliebigen Wert haben: sie könnte angeben, warum | |
177 | dieses Symbol als optional betrachtet wird. | |
178 | .TP | |
179 | \fBarch=\fP\fIArchitekturliste\fP | |
180 | .TQ | |
181 | \fBarch\-bits=\fP\fIArchitektur\-Bits\fP | |
182 | .TQ | |
183 | \fBarch\-endian=\fP\fIArchitektur\-Endianness\fP | |
184 | Diese Markierungen erlauben es, den Satz an Architekturen einzugrenzen, auf | |
185 | denen das Symbol existieren sollte. Die Markierungen \fBarch\-bits\fP und | |
186 | \fBarch\-endian\fP werden seit Dpkg 1.18.0 unterstützt. Wenn die Symbolliste mit | |
187 | den in der Bibliothek entdeckten Symbolen aktualisiert wird, werden alle | |
188 | architekturspezifischen Symbole, die nicht auf die aktuelle Host\-Architektur | |
189 | passen, so behandelt, als ob sie nicht existierten. Falls ein | |
190 | architekturspezifisches Symbol, das auf die aktuelle Host\-Architektur passt, | |
191 | in der Bibliothek nicht existiert, werden die normalen Regeln für fehlende | |
192 | Symbole angewandt und \fBdpkg\-gensymbols\fP könnte dadurch fehlschlagen. Auf | |
193 | der anderen Seite, falls das architekturspezifische Symbol gefunden wurde, | |
194 | wenn es nicht existieren sollte (da die aktuelle Host\-Architektur nicht in | |
195 | der Markierung aufgeführt ist oder nicht auf die Endianess und Bits passt), | |
196 | wird sie architekturneutral gemacht (d.h. die Architektur\-, | |
197 | Architektur\-Bits\- und Architektur\-Endianessmarkierungen werden entfernt und | |
198 | das Symbol wird im Diff aufgrund dieser Änderung auftauchen), aber es wird | |
199 | nicht als neu betrachtet. | |
200 | ||
201 | Beim Betrieb im standardmäßigen nicht\-Vorlagen\-Modus werden unter den | |
202 | architekturspezifischen Symbolen nur die in die Symboldatei geschrieben, die | |
203 | auf die aktuelle Host\-Architektur passen. Auf der anderen Seite werden beim | |
204 | Betrieb im Vorlagenmodus alle architekturspezifischen Symbole (darunter auch | |
205 | die von fremden Architekturen) immer in die Symboldatei geschrieben. | |
206 | ||
207 | Das Format der \fIArchitekturliste\fP ist das gleiche wie das des Feldes | |
208 | \fBBuild\-Depends\fP in \fIdebian/control\fP (außer den einschließenden eckigen | |
209 | Klammern []). Beispielsweise wird das erste Symbol aus der folgenden Liste | |
210 | nur auf den Architekturen Alpha, Any\-amd64 und Ia64 betrachtet, das zweite | |
211 | nur Linux\-Architekturen, während das dritte überall außer auf Armel | |
212 | betrachtet wird. | |
213 | ||
214 | (arch=alpha any\-amd64 ia64)64bit_specific_symbol@Base 1.0 | |
215 | (arch=linux\-any)linux_specific_symbol@Base 1.0 | |
216 | (arch=!armel)symbol_armel_does_not_have@Base 1.0 | |
217 | ||
218 | \fIarchitecture\-bits\fP ist entweder \fB32\fP oder \fB64\fP. | |
219 | ||
220 | (arch\-bits=32)32bit_specific_symbol@Base 1.0 | |
221 | (arch\-bits=64)64bit_specific_symbol@Base 1.0 | |
222 | ||
223 | \fIarchitecture\-endianness\fP ist entweder \fBlittle\fP oder \fBbig\fP. | |
224 | ||
225 | (arch\-endian=little)little_endian_specific_symbol@Base 1.0 | |
226 | (arch\-endian=big)big_endian_specific_symbol@Base 1.0 | |
227 | ||
228 | Mehrere Einschränkungen können aneinandergehängt werden. | |
229 | ||
230 | (arch\-bits=32|arch\-endian=little)32bit_le_symbol@Base 1.0 | |
231 | .TP | |
232 | \fBignore\-blacklist\fP | |
233 | dpkg\-gensymbols verfügt über eine interne Ausschußliste (»blacklist«) von | |
234 | Symbolen, die nicht in Symboldateien auftauchen sollten, da sie | |
235 | normalerweise nur Seiteneffekte von Implementierungsdetails in der | |
236 | Werkzeugkette darstellen. Falls Sie aus irgendeinem Grund wollen, dass diese | |
237 | Symbole in der Symboldatei aufgenommen werden, sollten Sie das Symbol mit | |
238 | \fBignore\-blacklist\fP kennzeichnen. Dies kann für einige grundlegende | |
239 | Bibliotheken der Werkzeugkette wie libgcc notwendig sein. | |
240 | .TP | |
241 | \fBc++\fP | |
242 | Gibt \fIc++\fP\-Symbolmuster an. Lesen Sie den Unterabschnitt \fBVerwendung von | |
243 | Symbolmuster\fP unten. | |
244 | .TP | |
245 | \fBsymver\fP | |
246 | Gibt \fIsymver\fP (Symbolversion)\-Symbolmuster an. Lesen Sie den Unterabschnitt | |
247 | \fBVerwendung von Symbolmuster\fP unten. | |
248 | .TP | |
249 | \fBregex\fP | |
250 | Gibt \fIregex\fP\-Symbolmuster an. Lesen Sie den Unterabschnitt \fBVerwendung von | |
251 | Symbolmuster\fP unten. | |
252 | .SS "Verwendung von Symbolmustern" | |
253 | .P | |
254 | Anders als die Standardsymbolspezifikation kann ein Muster mehrere reale | |
255 | Symbole aus der Bibliothek abdecken. \fBdpkg\-gensymbols\fP wird versuchen, | |
256 | jedes Muster auf jedes reale Symbol, für das \fIkein\fP spezifisches | |
257 | Symbolgegenstück in der Symboldatei definiert ist, zu passen. Wann immer das | |
258 | erste passende Muster gefunden wurde, werden alle Kennzeichnungen und | |
259 | Eigenschaften als Basisspezifikation des Symbols verwandt. Falls keines der | |
260 | Muster passt, wird das Symbol als neu betrachtet. | |
261 | ||
262 | Ein Muster wird als verloren betrachtet, falls es auf kein Symbol in der | |
263 | Bibliothek passt. Standardmäßig wird dies ein Versagen von | |
264 | \fBdpkg\-gensymbols\fP in der Stufe \fB\-c1\fP oder höher auslösen. Falls der | |
265 | Fehlschlag allerdings unerwünscht ist, kann das Muster mit der Kennzeichnung | |
266 | \fIoptional\fP markiert werden. Falls das Muster dann auf nichts passt wird es | |
267 | im Diff nur als MISSING (fehlend) auftauchen. Desweiteren kann das Muster | |
268 | wie jedes Symbol auf die spezielle Architektur mit der Kennzeichnung \fIarch\fP | |
269 | beschränkt werden. Bitte lesen Sie den Unterabschnitt \fBStandard | |
270 | Symbolkennzeichnungen\fP oben für weitere Informationen. | |
271 | ||
272 | Muster sind eine Erweiterung des Formats \fBdeb\-symbols\fP(5); sie sind daher | |
273 | nur in Symboldatei\-Vorlagen gültig. Die Musterspezifikationssyntax | |
274 | unterscheidet sich nicht von der eines spezifischen Symbols. Allerdings | |
275 | dient der Symbolnamenteil der Spezifikation als Ausdruck, der gegen | |
276 | \fIName@Version\fP eines realen Symbols gepasst wird. Um zwischen den | |
277 | verschiedenen Mustertypen zu unterscheiden, wird es typischerweise mit einer | |
278 | speziellen Kennzeichnung gekennzeichnet. | |
279 | ||
280 | Derzeit unterstützt \fBdpkg\-gensymbols\fP drei grundlegene Mustertypen: | |
281 | .TP 3 | |
282 | \fBc++\fP | |
283 | Dieses Muster wird durch die Kennzeichnung \fIc++\fP verzeichnet. Es passt nur | |
284 | auf die entworrenen (»demangled«) Symbolnamen (wie sie vom Hilfswerkzeug | |
285 | \fBc++filt\fP(1) ausgegeben werden). Dieses Muster ist sehr hilfreich um auf | |
286 | Symbole zu passen, bei dem die verworrenen (»mangled«) Namen sich auf | |
287 | verschiedenen Architekturen unterscheiden während die entworrenen die | |
288 | gleichen bleiben. Eine Gruppe solcher Symbole ist \fInon\-virtual thunks\fP, die | |
289 | einen architekturspezifischen Versatz in ihren verworrenen Namen eingebettet | |
290 | haben. Eine häufige Instanz dieses Falles ist ein virtueller Destruktur, der | |
291 | unter rautenförmiger Vererbung ein nicht\-virtuelles Thunk\-Symbol | |
292 | benötigt. Selbst wenn beispielsweise _ZThn8_N3NSB6ClassDD1Ev@Base auf 32 | |
293 | Bit\-Architekturen _ZThn16_N3NSB6ClassDD1Ev@Base auf 64 Bit\-Architekturen | |
294 | ist, kann es mit einem einzigen \fIc++\fP\-Muster gepasst werden: | |
295 | ||
296 | libdummy.so.1 libdummy1 #MINVER# | |
297 | […] | |
298 | (c++)"non\-virtual thunk to NSB::ClassD::~ClassD()@Base" 1.0 | |
299 | […] | |
300 | ||
301 | Der entworrene Name oben kann durch Ausführung folgenden Befehls erhalten | |
302 | werden: | |
303 | ||
304 | $ echo '_ZThn8_N3NSB6ClassDD1Ev@Base' | c++filt | |
305 | ||
306 | Bitte beachten Sie, dass per Definition zwar der verworrene Name in der | |
307 | Bibliothek eindeutig ist, die aber nicht notwendigerweise für die | |
308 | entworrenen Namen zutrifft. Ein Satz von unterschiedlichen realen Symbolen | |
309 | können den gleichen entworrenen Namen haben. Beispielsweise ist das der Fall | |
310 | bei nicht\-virtuellen Thunk\-Symbolen in komplexen Vererbungskonfigurationen | |
311 | oder bei den meisten Konstruktoren und Destruktoren (da g++ typischerweise | |
312 | zwei reale Symbole für sie generiert). Da diese Kollisionen aber auf dem | |
313 | ABI\-Niveau passieren, sollten sie nicht die Qualität der Symboldatei | |
314 | reduzieren. | |
315 | .TP | |
316 | \fBsymver\fP | |
317 | Dieses Muster wird durch die Kennzeichnung \fIsymver\fP verzeichnet. Gut | |
318 | betreute Bibliotheken verfügen über versionierte Symbole, wobei jede Version | |
319 | zu der Version der Originalautoren passt, in der dieses Symbol hinzugefügt | |
320 | wurde. Falls das der Fall ist, können SIe ein \fIsymver\fP\-Muster verwenden, um | |
321 | auf jedes zu einer spezifizierten Version zugeordnete Symbol zu | |
322 | passen. Beispiel: | |
323 | ||
324 | libc.so.6 libc6 #MINVER# | |
325 | (symver)GLIBC_2.0 2.0 | |
326 | […] | |
327 | (symver)GLIBC_2.7 2.7 | |
328 | access@GLIBC_2.0 2.2 | |
329 | ||
330 | Alle Version GLIBC_2.0 und GLIBC_2.7 zugeordneten Symbole werden zu einer | |
331 | minimalen Version 2.0 bzw. 2.7 führen, wobei das Symbol access@GLIBC_2.0 die | |
332 | Ausnahme darstellt. Es wird zu einer minimalen Abhängigkeit auf libc6 | |
333 | Version 2.2 führen, obwohl es im Geltungsbereich des Musters | |
334 | »(symver)GLIBC_2.0« passt, da spezielle Symbole vor Mustern Vorrang haben. | |
335 | ||
336 | Bitte beachten Sie, dass Platzhaltermuster im alten Format (angezeigt durch | |
337 | »*@version« im Symbolnamenfeld) zwar noch unterstützt werden, sie aber durch | |
338 | die Syntax im neuen Format »(symver|optional)version« abgelöst | |
339 | wurden. Beispielsweise sollte »*@GLIBC_2.0 2.0« als | |
340 | »(symver|optional)GLIBC_2.0 2.0« geschrieben werden, falls das gleiche | |
341 | Verhalten benötigt wird. | |
342 | .TP | |
343 | \fBregex\fP | |
344 | Muster mit regulären Ausdrücken werden durch die Kennzeichnung \fIregex\fP | |
345 | verzeichnet. Sie passen auf den regulären Ausdruck von Perl, der im | |
346 | Symbolnamenfeld angegeben ist. Ein regulärer Ausdruck wird wie er ist | |
347 | gepasst. Denken Sie daher daran, ihn mit dem Zeichen \fI^\fP zu beginnen, da er | |
348 | ansonsten auf jeden Teil der Zeichenkette des realen Symbols \fIname@version\fP | |
349 | passt. Beispiel: | |
350 | ||
351 | libdummy.so.1 libdummy1 #MINVER# | |
352 | (regex)"^mystack_.*@Base$" 1.0 | |
353 | (regex|optional)"private" 1.0 | |
354 | ||
355 | Symbole wie »mystack_new@Base«, »mystack_push@Base«, »mystack_pop@Base« | |
356 | usw. werden vom ersten Muster gepasst, während dies z.B. für | |
357 | »ng_mystack_new@Base« nicht der Fall ist. Das zweite Muster wird auf alle | |
358 | Symbole, die die Zeichenkette »private« in ihren Namen enthalten, passen und | |
359 | die gepassten Symbole erben die Kennzeichnung \fIoptional\fP vom Muster. | |
360 | .P | |
361 | Die oben aufgeführten grundlegenden Muster können \- wo es Sinn ergibt \- | |
362 | kombiniert werden. In diesem Fall werden sie in der Reihenfolge verarbeitet, | |
363 | in der die Kennzeichnungen angegeben sind. Im Beispiel | |
364 | ||
365 | (c++|regex)"^NSA::ClassA::Private::privmethod\ed\e(int\e)@Base" 1.0 | |
366 | (regex|c++)N3NSA6ClassA7Private11privmethod\edEi@Base 1.0 | |
367 | ||
368 | werden die Symbole »_ZN3NSA6ClassA7Private11privmethod1Ei@Base« und | |
369 | »_ZN3NSA6ClassA7Private11privmethod2Ei@Base« gepasst. Beim Passen der ersten | |
370 | Musters wird das rohe Symbol erst als C++\-Symbol entworren, dann wird der | |
371 | entworrende Name gegen den regulären Ausdruck gepasst. Auf der anderen Seite | |
372 | wird beim Passen des zweiten Musters der reguläre Ausdruck gegen den rohen | |
373 | Symbolnamen gepasst, dann wird das Symbol überprüft, ob es ein C++\-Symbol | |
374 | ist, indem das Entwirren versucht wird. Ein Fehlschlag eines einfachen | |
375 | Musters wird zum Fehlschlag des gesamten Musters führen. Daher wird | |
376 | beispielsweise »__N3NSA6ClassA7Private11privmethod\edEi@Base« keines der | |
377 | Muster passen, da es kein gültiges C++\-Symbol ist. | |
378 | ||
379 | Im Allgemeinen werden die Muster in zwei Kategorien eingeteilt: Aliase | |
380 | (grundlegende \fIc++\fP\- und \fIsymver\fP\-Muster) und generische Muster (\fIregex\fP | |
381 | und alle Kombinationen grundlegender Muster). Passen von grundlegenden | |
382 | alias\-basierenden Mustern ist schnell (O(1)), während generische Muster O(N) | |
383 | (wobei N die Anzahl der generischen Muster ist) für jedes Symbol ist. Daher | |
384 | wird empfohlen, generische Muster nicht zu viel zu verwenden. | |
385 | ||
386 | Wenn mehrere Muster auf das gleiche Symbol passen, werden Aliase (zuerst | |
387 | \fIc++\fP, dann \fIsymver\fP) gegenüber den generischen Mustern | |
388 | bevorzugt. Generische Muster werden in der Reihenfolge, in der sie in der | |
389 | Symboldateivorlage gefunden werden, gepasst, bis zum ersten Erfolg. Beachten | |
390 | Sie aber, dass das manuelle Anordnen der Vorlagendateieinträge nicht | |
391 | empfohlen wird, da \fBdpkg\-gensymbols\fP Diffs basierend auf der | |
392 | alphanumerischen Reihenfolge ihrer Namen erstellt. | |
393 | .SS "Includes verwenden" | |
394 | .P | |
395 | Wenn der Satz der exportierten Symbolen sich zwischen Architekturen | |
396 | unterscheidet, kann es ineffizient werden, eine einzige Symboldatei zu | |
397 | verwenden. In diesen Fällen kann sich eine Include\-Direktive in einer Reihe | |
398 | von Arten als nützlich erweisen: | |
399 | .IP • 4 | |
400 | Sie können den gemeinsamen Teil in eine externe Datei auslagern und diese | |
401 | Datei dann in Ihre \fIPaket\fP.symbols.\fIArch\fP\-Datei mit einer | |
402 | include\-Direktive wie folgt einbinden: | |
403 | ||
404 | #include "\fIPakete\fP.symbols.common" | |
405 | .IP • | |
406 | Die Include\-Direktive kann auch wie jedes Symbol gekennzeichnet werden: | |
407 | ||
408 | (Kennzeichen|…|KennzeichenN)#include "einzubindende\-Datei" | |
409 | ||
410 | Als Ergebnis werden alle Symbole aus \fIeinzubindende\-Datei\fP standardmäßig | |
411 | als mit \fIKennzeichen\fP … \fIKennzeichenN\fP gekennzeichnet betrachtet. Sie | |
412 | können diese Funktionalität benutzen, um eine gemeinsame Datei | |
413 | \fIPaket\fP.symbols zu erstellen, die architekturspezifische Symboldateien | |
414 | einbindet: | |
415 | ||
416 | common_symbol1@Base 1.0 | |
417 | (arch=amd64 ia64 alpha)#include "Paket.symbols.64bit" | |
418 | (arch=!amd64 !ia64 !alpha)#include "Paket.symbols.32bit" | |
419 | common_symbol2@Base 1.0 | |
420 | .P | |
421 | Die Symboldateien werden Zeile für Zeile gelesen und include\-Direktiven | |
422 | werden bearbeitet, sobald sie erkannt werden. Das bedeutet, dass der Inhalt | |
423 | der Include\-Datei jeden Inhalt überschreiben kann, der vor der | |
424 | Include\-Direktive aufgetaucht ist und Inhalt nach der Direktive alles aus | |
425 | der Include\-Datei überschreiben kann. Jedes Symbol (oder sogar weitere | |
426 | #include\-Direktiven) in der Include\-Datei kann zusätzliche Kennzeichnungen | |
427 | spezifizieren oder Werte der vererbtgen Kennzeichnungen in ihrer | |
428 | Kennzeichnungsspezifikation überschreiben. Allerdings gibt es keine | |
429 | Möglichkeit für ein Symbol, die ererbten Kennzeichnungen zu überschreiben. | |
430 | .P | |
431 | Eine eingebundene Datei kann die Kopfzeile wiederholen, die den SONAME der | |
432 | Bibliothek enthält. In diesem Fall überschreibt sie jede vorher gelesene | |
433 | Kopfzeile. Allerdings ist es im Allgemeinen am Besten, die Wiederholung von | |
434 | Kopfzeilen zu vermeiden. Ein Weg dies zu erreichen, ist wie folgt: | |
435 | .PP | |
436 | #include "libirgendwas1.symbols.common" | |
437 | arch_spezifisches_Symbol@Base 1.0 | |
438 | .SS "Gute Bibliotheksverwaltung" | |
439 | .P | |
440 | Eine gut verwaltete Bibliothek hat die folgenden Eigenschaften: | |
441 | .IP • 4 | |
442 | seine API ist stabil (öffentliche Symbole entfallen nie, nur neue | |
443 | öffentliche Symbole werden hinzugefügt) und inkompatible Änderungen erfolgen | |
444 | nur, wenn sich der SONAME ändert, | |
445 | .IP • 4 | |
446 | idealerweise verwendet sie Symbolversionierung, um ABI\-Stabilität trotz | |
447 | interner Änderungen und API\-Erweiterungen zu erreichen, | |
448 | .IP • 4 | |
449 | sie exportiert nie private Symbole (als Hilfslösung können diese als | |
450 | optional gekennzeichnet werden). | |
451 | .P | |
452 | Bei der Verwaltung der Symboldatei kann das Auftauchen und Verschwinden von | |
453 | Symbolen leicht bemerkt werden. Es ist aber schwieriger, inkompatbile API\- | |
454 | und ABI\-Änderungen zu bemerken. Daher sollte der Betreuer intensiv die | |
455 | Changelog\-Einträge durchschauen und nach Fällen suchen, in denen die Regeln | |
456 | der guten Bibliotheksverwaltung gebrochen wurden. Falls mögliche Probleme | |
457 | entdeckt wurden, sollten der Originalautor informiert werden, da eine | |
458 | Korrektur vom Originalautor immer besser als eine Debian\-spezifische | |
459 | Hilfslösung ist. | |
460 | .SH OPTIONEN | |
461 | .TP | |
462 | \fB\-P\fP\fIPaketbauverzeichnis\fP | |
463 | Suche nach \fIPaketbauverzeichnis\fP statt nach debian/tmp. | |
464 | .TP | |
465 | \fB\-p\fP\fIPaket\fP | |
466 | Definiert den Paketnamen. Benötigt, falls mehr als ein binäres Paket in | |
467 | debian/control aufgeführt ist (oder falls es keine Datei debian/control | |
468 | gibt). | |
469 | .TP | |
470 | \fB\-v\fP\fIVersion\fP | |
471 | Definiert die Paketversion. Standardmäßig wird die Version aus | |
472 | debian/changelog ausgelesen. Benötigt, falls der Aufruf außerhalb des | |
473 | Quellpaketbaums erfolgt. | |
474 | .TP | |
475 | \fB\-e\fP\fIBibliotheksdatei\fP | |
476 | Nur die explizit aufgeführten Bibliotheken untersuchen statt alle | |
477 | öffentlichen Bibliotheken zu finden. Sie können Shell\-Muster, die zur | |
478 | Expansion von Pfadnamen verwandt werden (siehe die Handbuchseite | |
479 | \fBFile::Glob\fP(3perl) für weitere Details) in \fIBibliotheksdatei\fP verwenden, | |
480 | um mehrere Bibliotheken mit einem einzelnen Argument zu passen (andernfalls | |
481 | benötigen Sie mehrere \fB\-e\fP). | |
482 | .TP | |
483 | \fB\-I\fP\fIDateiname\fP | |
484 | Verwende \fIDateiname\fP als Referenzdatei, um die Symboldatei zu erstellen, | |
485 | die dann im Paket selbst integriert wird. | |
486 | .TP | |
487 | \fB\-O\fP[\fIDateiname\fP] | |
488 | Die erstellte Symbols\-Datei auf die Standardausgabe oder nach \fIDateiname\fP, | |
489 | falls angegeben, ausgeben statt in \fBdebian/tmp/DEBIAN/symbols\fP (oder | |
490 | \fIPaket\-Bauverzeichnis\fP\fB/DEBIAN/symbols\fP falls \fB\-P\fP verwandt wurde). Falls | |
491 | \fIDateiname\fP bereits existiert, wird deren Inhalt als Grundlage für die | |
492 | erstellte Symboldatei verwandt. Sie können diese Funktionalität benutzen, um | |
493 | eine Symboldatei zu aktualisieren, so dass sie zu einer neueren Version der | |
494 | Originalautoren Ihrer Bibliothek passt. | |
495 | .TP | |
496 | \fB\-t\fP | |
497 | Schreibe die Symboldatei im Vorlagenmodus statt im zu \fBdeb\-symbols\fP(5) | |
498 | kompatiblen Format. Der Hauptunterschied besteht darin, dass im | |
499 | Vorlagenmodus die Symbolnamen und Kennzeichnungen in ihrer Originalform | |
500 | geschrieben werden, im Gegensatz zu den verarbeiteten Symbolnamen mit | |
501 | entfernen Kennzeichnungen im Kompatibilitätsmodus. Desweiteren könnten | |
502 | einige Symbole beim Schreiben einer Standard \fBdeb\-symbols\fP(5)\-Datei | |
503 | entfernt werden (gemäß der Verarbeitungsregeln für Kennzeichen), während in | |
504 | der Symboldateivorlage immer alle Symbole geschrieben werden. | |
505 | .TP | |
506 | \fB\-c\fP\fI[0\-4]\fP | |
507 | Definiert die Prüfungen, die beim Vergleich der erstellten Symboldatei mit | |
508 | der Vorlagendatei als Startpunkt erfolgen sollen. Standardstufe ist | |
509 | 1. Zunehmende Stufen führen mehr Prüfungen durch und enthalten alle | |
510 | Prüfungen der niedrigeren Stufen. Stufe 0 schlägt nie fehl. Stufe 1 schlägt | |
511 | fehl, wenn einige Symbole verschwunden sind. Stufe 2 schlägt fehlt, falls | |
512 | einige neue Symbole eingeführt wurden. Stufe 3 schlägt fehl, falls einige | |
513 | Bibliotheken verschwunden sind. Stufe 4 schlägt fehl, falls einige | |
514 | Bibliotheken hinzugekommen sind. | |
515 | ||
516 | Dieser Wert kann von der Umgebungsvariablen \fBDPKG_GENSYMBOLS_CHECK_LEVEL\fP | |
517 | außer Kraft gesetzt werden. | |
518 | .TP | |
519 | \fB\-q\fP | |
520 | Ruhig verhalten und nie einen Diff zwischen der erstellten Symboldatei und | |
521 | der als Startpunkt verwandten Vorlagendatei erstellen oder keine Warnungen | |
522 | bezüglich neuer/verlorender Bibliotheken oder neuer/verlorender Symbole | |
523 | ausgeben. Diese Option deaktiviert nur die informative Ausgabe aber nicht | |
524 | die Prüfungen selbst (sehen Sie hierzu die Option \fB\-c\fP). | |
525 | .TP | |
526 | \fB\-a\fP\fIArchitektur\fP | |
527 | Nehme \fIArch\fP als Host\-Architektur beim Verarbeiten der Symboldateien | |
528 | an. Verwenden Sie diese Option, um Symboldateien oder Diffs für beliebige | |
529 | Architekturen zu erstellen, vorausgesetzt, die Binärprogramme sind bereits | |
530 | verfügbar. | |
531 | .TP | |
532 | \fB\-d\fP | |
533 | Debug\-Modus aktivieren. Eine Vielzahl von Nachrichten wird angezeigt, um zu | |
534 | erklären, was \fBdpkg\-gensymbols\fP durchführt. | |
535 | .TP | |
536 | \fB\-V\fP | |
537 | Ausführlichen Modus aktivieren. Die erstellte Symboldatei enthält veraltete | |
538 | Symbole als Kommentare. Im Vorlagenmodus werden Mustersymbole desweiteren | |
539 | von Kommentaren gefolgt, die die echten Symbole aufführen, die auf dieses | |
540 | Muster passen. | |
541 | .TP | |
542 | \fB\-?\fP, \fB\-\-help\fP | |
543 | Zeige den Bedienungshinweis und beende. | |
544 | .TP | |
545 | \fB\-\-version\fP | |
546 | Gebe die Version aus und beende sich. | |
547 | . | |
548 | .SH UMGEBUNG | |
549 | .TP | |
550 | \fBDPKG_GENSYMBOLS_CHECK_LEVEL\fP | |
551 | Setzt die Befehlsüberprüfungsstufe außer Kraft, selbst wenn das | |
552 | Befehlszeilenargument \fB\-c\fP übergeben wurde (beachten Sie, dass dies der | |
553 | üblichen Konvention widerspricht, demnach Befehlszeilenargumente Vorrang | |
554 | über Umgebungsvariablen haben). | |
555 | .SH "SIEHE AUCH" | |
556 | \fBhttps://people.redhat.com/drepper/symbol\-versioning\fP | |
557 | .br | |
558 | \fBhttps://people.redhat.com/drepper/goodpractice.pdf\fP | |
559 | .br | |
560 | \fBhttps://people.redhat.com/drepper/dsohowto.pdf\fP | |
561 | .br | |
562 | \fBdeb\-symbols\fP(5), \fBdpkg\-shlibdeps\fP(1). | |
563 | .SH ÜBERSETZUNG | |
564 | Die deutsche Übersetzung wurde 2004, 2006-2017 von Helge Kreutzmann | |
565 | <debian@helgefjell.de>, 2007 von Florian Rehnisch <eixman@gmx.de> und | |
566 | 2008 von Sven Joachim <svenjoac@gmx.de> | |
567 | angefertigt. Diese Übersetzung ist Freie Dokumentation; lesen Sie die | |
568 | GNU General Public License Version 2 oder neuer für die Kopierbedingungen. | |
569 | Es gibt KEINE HAFTUNG. |