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% "suite dpkg" | |
26 | .nh | |
27 | .SH NOM | |
28 | dpkg\-gensymbols \- création des fichiers de symboles (information destinée | |
29 | aux dépendances de bibliothèques partagées) | |
30 | . | |
31 | .SH SYNOPSIS | |
32 | \fBdpkg\-gensymbols\fP [\fIoption\fP...] | |
33 | . | |
34 | .SH DESCRIPTION | |
35 | \fBdpkg\-gensymbols\fP analyse un répertoire temporaire de construction (par | |
36 | défaut debian/tmp), y recherche les bibliothèques et crée un fichier | |
37 | \fIsymbols\fP qui les décrit. Si ce fichier n'est pas vide, il est installé | |
38 | dans le sous\-répertoire DEBIAN du répertoire de construction afin de pouvoir | |
39 | être inclus dans les informations de contrôle du paquet. | |
40 | .P | |
41 | Lors de la création de ces fichiers, il utilise en entrée certains fichiers | |
42 | de symboles fournis par le responsable. Il recherche les fichiers suivants | |
43 | (en utilisant le premier trouvé)\ : | |
44 | .IP • 4 | |
45 | debian/\fIpaquet\fP.symbols.\fIarch\fP | |
46 | .IP • 4 | |
47 | debian/symbols.\fIarch\fP | |
48 | .IP • 4 | |
49 | debian/\fIpaquet\fP.symbols | |
50 | .IP • 4 | |
51 | debian/symbols | |
52 | .P | |
53 | L'intérêt principal de ces fichiers est de fournir la version minimale | |
54 | associée à chaque symbole fourni par les bibliothèques. En général, cela | |
55 | correspond à la première version du paquet qui a fourni ce symbole, mais | |
56 | cette valeur peut être augmentée manuellement par le responsable si | |
57 | l'interface binaire applicative (ABI) du symbole est étendue sans casser la | |
58 | compatibilité avec les versions précédentes. La tenue à jour de ces fichiers | |
59 | est à la charge du responsable du paquet, avec l'aide de | |
60 | \fBdpkg\-gensymbols\fP. | |
61 | .P | |
62 | Quand les fichiers de symboles créés sont différents de ceux fournis par le | |
63 | responsable, \fBdpkg\-gensymbols\fP affichera les différences entre les deux | |
64 | fichiers. Si ces différences sont trop importantes, le programme peut même | |
65 | se terminer en échec (le nombre de différences tolérées peut être réglé avec | |
66 | l'option \fB\-c\fP). | |
67 | .SH "TENUE À JOUR DES FICHIERS SYMBOLES" | |
68 | The symbols files are really useful only if they reflect the evolution of | |
69 | the package through several releases. Thus the maintainer has to update them | |
70 | every time that a new symbol is added so that its associated minimal version | |
71 | matches reality. The diffs contained in the build logs can be used as a | |
72 | starting point, but the maintainer, additionally, has to make sure that the | |
73 | behaviour of those symbols has not changed in a way that would make anything | |
74 | using those symbols and linking against the new version, stop working with | |
75 | the old version. In most cases, the diff applies directly to the | |
76 | debian/\fIpackage\fP.symbols file. That said, further tweaks are usually | |
77 | needed: it's recommended for example to drop the Debian revision from the | |
78 | minimal version so that backports with a lower version number but the same | |
79 | upstream version still satisfy the generated dependencies. If the Debian | |
80 | revision can't be dropped because the symbol really got added by the Debian | |
81 | specific change, then one should suffix the version with ‘\fB~\fP’. | |
82 | .P | |
83 | Avant d'appliquer le correctif au fichier de symboles, le responsable doit | |
84 | contrôler qu'il est correct. Les symboles publics sont supposés ne jamais | |
85 | disparaître et le correctif ne devrait donc qu'ajouter des lignes. | |
86 | .P | |
87 | Note that you can put comments in symbols files: any line with ‘#’ as the | |
88 | first character is a comment except if it starts with ‘#include’ (see | |
89 | section \fBUsing includes\fP). Lines starting with ‘#MISSING:’ are special | |
90 | comments documenting symbols that have disappeared. | |
91 | .P | |
92 | N'oubliez pas de vérifier les anciennes versions des symboles ne doivent pas | |
93 | être incrémentées. Il n'y a pas de moyen pour que \fBdpkg\-gensymbols\fP | |
94 | prévienne de cela. Appliquer aveuglement le fichier de différences ou | |
95 | supposer qu'il n'y a rien à changer, s'il n'y a pas de fichier de | |
96 | différences, sans vérifier si il de telles modifications, ce qui peut faire | |
97 | que des paquets, avec des dépendances lâches, prétendent qu'ils peuvent | |
98 | fonctionner avec des paquets plus anciens avec lesquels ils ne peuvent | |
99 | fonctionner. Cela introduira des bogues difficiles à trouver avec des mises | |
100 | à jour (partielles). | |
101 | .SS "Utilisation du remplacement de #PACKAGE#" | |
102 | .P | |
103 | Dans de rares cas, le nom de la bibliothèque dépend de l'architecture. Afin | |
104 | d'éviter de coder le nom du paquet en dur dans le fichier de symboles, il | |
105 | est possible d'utiliser le marqueur \fI#PACKAGE#\fP. Il sera remplacé par le | |
106 | vrai nom du paquet lors de l'installation des fichiers de symboles. À la | |
107 | différence du marqueur \fI#MINVER#\fP, \fI#PACKAGE#\fP n'apparaîtra jamais dans le | |
108 | fichier de symboles d'un paquet binaire. | |
109 | .SS "Utilisation des étiquettes de symbole" | |
110 | .P | |
111 | L'étiquetage des symboles («\ symbol tagging\ ») est utile pour marquer des | |
112 | symboles qui sont particuliers d'une manière ou d'une autre. Tout symbole | |
113 | peut avoir un nombre quelconque d'étiquettes associées. Bien que toutes les | |
114 | étiquettes soient analysées et conservées, seules certaines d'entre elles | |
115 | sont comprises par \fBdpkg\-gensymbols\fP et déclenchent un traitement | |
116 | spécifique des symboles. Veuillez consulter la sous\-section \fBÉtiquettes | |
117 | standard de symbole\fP pour une référence complète à propos de ces étiquettes. | |
118 | .P | |
119 | L'indication de l'étiquette vient juste avant le nom du symbole (sans | |
120 | espace). Elle commence toujours par une parenthèse ouvrante \fB(\fP, se termine | |
121 | avec une parenthèse fermante \fB)\fP et doit contenir au moins une | |
122 | étiquette. Les étiquettes multiples doivent être séparées par le caractère | |
123 | \fB|\fP. Chaque étiquette peut comporter optionnellement une valeur, séparée du | |
124 | nom de l'étiquette par le caractère \fB=\fP. Les noms et valeurs des étiquettes | |
125 | sont des chaînes quelconques qui ne doivent pas comporter les caractères | |
126 | \fB)\fP \fB|\fP et \fB=\fP. Les noms de symbole qui suivent une étiquette peuvent | |
127 | optionnellement être mis entre guillemets avec les caractères \fB'\fP ou \fB"\fP | |
128 | afin d'y autoriser la présence d'espaces. Cependant, si aucune étiquette | |
129 | n'est utilisée, les guillemets sont alors traités comme une partie du nom du | |
130 | symbole, qui s'arrête alors au premier espace. | |
131 | .P | |
132 | (étiq1=je suis marqué|étiquette avec espace)"symbole comportant des espaces"@Base 1.0 | |
133 | (optional)symbole_non_protégé@Base 1.0 1 | |
134 | symbole_non_étiqueté@Base 1.0 | |
135 | .P | |
136 | Le premier symbole de cet exemple est appelé \fIsymbole comportant des | |
137 | espaces\fP et utilise deux étiquettes\ :\ \fIétiq1\fP avec la valeur \fIje suis | |
138 | marqué\fP et \fIétiquette avec espace\fP sans valeur. Le deuxième symbole, appelé | |
139 | \fIsymbole_non_protégé\fP ne comporte que l'étiquette \fIoptional\fP. Le dernier | |
140 | symbole est un exemple de symbole normal sans étiquette. | |
141 | .P | |
142 | Comme les étiquettes de symbole sont une extension du format de | |
143 | \fBdeb\-symbols(5)\fP, elles ne peuvent apparaître que dans les fichiers de | |
144 | symboles des paquets source (ces fichiers peuvent ensuite être vus comme des | |
145 | modèles permettant de construire les fichiers de symboles inclus dans les | |
146 | paquets binaires). Lorsque \fBdpkg\-gensymbols\fP est lancé sans l'option \fB\-t\fP, | |
147 | il affiche les fichiers de symboles compatibles avec le format | |
148 | \fBdeb\-symbols(5)\fP\ : il traite entièrement les symboles d'après les exigences | |
149 | des étiquettes standard et supprime les étiquettes dans sa sortie. Au | |
150 | contraire, dans le mode modèle («\ template\ », option \fB\-t\fP), tous les | |
151 | symboles et leurs étiquettes (standard et inconnues) sont conservés dans la | |
152 | sortie et écrits dans leur forme d'origine. | |
153 | .SS "Étiquettes standard de symbole" | |
154 | .TP | |
155 | \fBoptional\fP | |
156 | A symbol marked as optional can disappear from the library at any time and | |
157 | that will never cause \fBdpkg\-gensymbols\fP to fail. However, disappeared | |
158 | optional symbols will continuously appear as MISSING in the diff in each new | |
159 | package revision. This behaviour serves as a reminder for the maintainer | |
160 | that such a symbol needs to be removed from the symbol file or readded to | |
161 | the library. When the optional symbol, which was previously declared as | |
162 | MISSING, suddenly reappears in the next revision, it will be upgraded back | |
163 | to the “existing” status with its minimum version unchanged. | |
164 | ||
165 | Cette étiquette est utile pour les symboles qui sont privés car leur | |
166 | disparition ne provoque pas de changement d'interface applicative (ABI). Par | |
167 | exemple, la plupart des modèles d'instanciation C++ sont dans cette | |
168 | catégorie. Comme toute autre étiquette, celle\-ci peut comporter une valeur | |
169 | arbitraire qui peut servir à indiquer pour quelle raison le symbole est | |
170 | optionnel. | |
171 | .TP | |
172 | \fBarch=\fP\fIarchitecture\-list\fP | |
173 | .TQ | |
174 | \fBarch\-bits=\fP\fIarchitecture\-bits\fP | |
175 | .TQ | |
176 | \fBarch\-endian=\fP\fIarchitecture\-endianness\fP | |
177 | These tags allow one to restrict the set of architectures where the symbol | |
178 | is supposed to exist. The \fBarch\-bits\fP and \fBarch\-endian\fP tags are supported | |
179 | since dpkg 1.18.0. When the symbols list is updated with the symbols | |
180 | discovered in the library, all arch\-specific symbols which do not concern | |
181 | the current host architecture are treated as if they did not exist. If an | |
182 | arch\-specific symbol matching the current host architecture does not exist | |
183 | in the library, normal procedures for missing symbols apply and it may cause | |
184 | \fBdpkg\-gensymbols\fP to fail. On the other hand, if the arch\-specific symbol | |
185 | is found when it was not supposed to exist (because the current host | |
186 | architecture is not listed in the tag or does not match the endianness and | |
187 | bits), it is made arch neutral (i.e. the arch, arch\-bits and arch\-endian | |
188 | tags are dropped and the symbol will appear in the diff due to this change), | |
189 | but it is not considered as new. | |
190 | ||
191 | Dans le mode de fonctionnement par défaut (pas en mode «\ modèle\ »), seuls | |
192 | les symboles spécifiques de certaines architectures qui correspondent à | |
193 | l'architecture courante sont écrits dans le fichier de symboles. Au | |
194 | contraire, tous les symboles spécifiques d'architectures (y compris ceux des | |
195 | architectures différentes) seront écrits dans le fichier de symboles, dans | |
196 | le mode «\ modèle\ ». | |
197 | ||
198 | The format of \fIarchitecture\-list\fP is the same as the one used in the | |
199 | \fBBuild\-Depends\fP field of \fIdebian/control\fP (except the enclosing square | |
200 | brackets []). For example, the first symbol from the list below will be | |
201 | considered only on alpha, any\-amd64 and ia64 architectures, the second only | |
202 | on linux architectures, while the third one anywhere except on armel. | |
203 | ||
204 | (arch=alpha any\-amd64 ia64)un_symbole_spécifique_64bit@Base 1.0 | |
205 | (arch=linux\-any)un_symbole_spécifique_linux@Base 1.0 | |
206 | (arch=!armel)un_symbole_inexistant_sur_armel@Base 1.0 | |
207 | ||
208 | The \fIarchitecture\-bits\fP is either \fB32\fP or \fB64\fP. | |
209 | ||
210 | (arch\-bits=32)32bit_specific_symbol@Base 1.0 | |
211 | (arch\-bits=64)64bit_specific_symbol@Base 1.0 | |
212 | ||
213 | The \fIarchitecture\-endianness\fP is either \fBlittle\fP or \fBbig\fP. | |
214 | ||
215 | (arch\-endian=little)little_endian_specific_symbol@Base 1.0 | |
216 | (arch\-endian=big)big_endian_specific_symbol@Base 1.0 | |
217 | ||
218 | Multiple restrictions can be chained. | |
219 | ||
220 | (arch\-bits=32|arch\-endian=little)32bit_le_symbol@Base 1.0 | |
221 | .TP | |
222 | \fBignore\-blacklist\fP | |
223 | dpkg\-gensymbols comporte une liste interne de symboles ignorés qui ne | |
224 | devraient pas apparaître dans les fichiers de symboles car ils sont en | |
225 | général uniquement des effets de bord de détails de mise en œuvre de la | |
226 | chaîne d'outils de construction. Si, pour une raison précise, vous voulez | |
227 | vraiment inclure un de ces symboles dans le fichier, vous pouvez imposer | |
228 | qu'il soit ignoré, avec \fBignore\-blacklist\fP. Cela peut être utile pour | |
229 | certaines bibliothèques de bas niveau telles que libgcc. | |
230 | .TP | |
231 | \fBc++\fP | |
232 | Indique un motif de symbole \fIc++\fP. Voir la sous\-section \fBUtilisation de | |
233 | motifs de symbole\fP plus loin. | |
234 | .TP | |
235 | \fBsymver\fP | |
236 | Indique un motif de symbole \fIsymver\fP (version de symbole). Voir la | |
237 | sous\-section \fBUtilisation des motifs de symboles\fP plus loin. | |
238 | .TP | |
239 | \fBregex\fP | |
240 | Indique un motif de symbole basé sur des \fIexpressions rationnelles\fP. Voir | |
241 | la sous\-section \fBUtilisation des motifs de symboles\fP plus loin. | |
242 | .SS "Utilisation des motifs de symboles" | |
243 | .P | |
244 | Au contraire d'une indication normale de symbole, un motif permet de couvrir | |
245 | des symboles multiples de la bibliothèque. \fBdpkg\-gensymbols\fP essaie de | |
246 | faire correspondre chaque motif à chaque symbole qui n'est pas explicitement | |
247 | défini dans le fichier de symboles. Dès qu'un motif est trouvé qui | |
248 | correspond au symbole, l'ensemble de ses étiquettes et propriétés sont | |
249 | utilisées comme spécification de base du symbole. Si aucun des motifs ne | |
250 | correspond, le symbole sera considéré comme nouveau. | |
251 | ||
252 | Un motif est considéré comme perdu si aucun symbole ne lui correspond dans | |
253 | la bibliothèque. Par défaut, cela provoquera un échec de \fBdpkg\-gensymbols\fP | |
254 | s'il est utilisé avec l'option \fB\-c1\fP (ou une valeur plus | |
255 | élevée). Cependant, si l'échec n'est pas souhaité, le motif peut être marqué | |
256 | comme optionnel avec l'étiquette \fIoptional\fP. Dans ce cas, si le motif ne | |
257 | correspond à rien, il sera simplement mentionné dans le fichier de | |
258 | différences comme \fIMISSING\fP (manquant). De plus, comme pour tout autre | |
259 | symbole, le motif peut être limité à des architectures données avec | |
260 | l'étiquette \fIarch\fP. Veuillez consulter la sous\-section \fBÉtiquettes | |
261 | standard de symbole\fP pour plus d'informations. | |
262 | ||
263 | Les motifs sont une extension du format de \fBdeb\-symbols(5)\fP en ce sens | |
264 | qu'ils ne sont valables que dans les modèles de fichiers de | |
265 | symboles. Cependant, la partie comportant le nom de symbole est utilisée | |
266 | comme une expression à faire correspondre à \fIname@version\fP du symbole | |
267 | réel. Afin de faire la distinction entre les différents types de motifs, un | |
268 | motif sera usuellement marqué avec une étiquette spéciale. | |
269 | ||
270 | Actuellement, \fBdpkg\-gensymbols\fP gère trois types de base de motifs\ : | |
271 | .TP 3 | |
272 | \fBc++\fP | |
273 | Ce motif est repéré par l'étiquette \fIc++\fP. Il ne sera comparé qu'aux | |
274 | symboles C++ avec leur nom de symbole complet (demangled) tel qu'affiché | |
275 | avec l'utilitaire \fBc++filt\fP. Ce motif est très pratique pour faire | |
276 | correspondre les symboles dont les noms raccourcis (mangled) peuvent | |
277 | différer selon les architectures bien que leurs noms complets restent les | |
278 | mêmes. Un tel groupe de symboles sont les \fInon\-virtual thunks\fP pour | |
279 | lesquels les décalages (offsets) spécifiques d'architectures sont inclus | |
280 | dans leur nom court. Une manifestation usuelle de ce cas est le destructeur | |
281 | virtuel qui, dans le contexte d'un «\ problème du diamant\ », a besoin d'un | |
282 | symbole de transition spécial (ou «\ thunk\ ») non virtuel. Par exemple, même | |
283 | si _ZThn8_N3NSB6ClassDD1Ev@Base sur une architecture 32\ bits est identique à | |
284 | _ZThn16_N3NSB6ClassDD1Ev@Base sur une architecture 64\ bits, les deux peuvent | |
285 | être indiqués avec le même motif \fIc++\fP\ : | |
286 | ||
287 | libdummy.so.1 libdummy1 #MINVER# | |
288 | [...] | |
289 | (c++)"non\-virtual thunk to NSB::ClassD::~ClassD()@Base" 1.0 | |
290 | [...] | |
291 | ||
292 | Le nom complet ci\-dessus peut être obtenu avec la commande suivante\ : | |
293 | ||
294 | $ echo '_ZThn8_N3NSB6ClassDD1Ev@Base' | c++filt | |
295 | ||
296 | Veuillez noter que, bien que le nom complet soit unique dans la bibliothèque | |
297 | par définition, cela n'est pas forcément vrai pour le nom raccourci. Deux | |
298 | symboles réels différents peuvent avoir le même nom raccourci. C'est par | |
299 | exemple le cas avec les symboles «\ thunk\ » non virtuels dans des | |
300 | configurations d'héritage complexes ou avec la plupart des constructeurs et | |
301 | destructeurs (puisque g++ crée usuellement deux symboles réels pour | |
302 | eux). Cependant, comme ces collisions se produisent au niveau de l'interface | |
303 | applicative binaire (ABI), elles ne devraient pas dégrader la qualité du | |
304 | fichier de symboles. | |
305 | .TP | |
306 | \fBsymver\fP | |
307 | Ce motif est indiqué par l'étiquette \fIsymver\fP. Les bibliothèques bien | |
308 | gérées utilisent des symboles versionnés où chaque version correspond à la | |
309 | version amont à laquelle le symbole a été ajouté. Si c'est le cas, il est | |
310 | possible d'utiliser un motif \fIsymver\fP pour faire correspondre chaque | |
311 | symbole associé à la version spécifique. Par exemple\ : | |
312 | ||
313 | libc.so.6 libc6 #MINVER# | |
314 | (symver)GLIBC_2.0 2.0 | |
315 | [...] | |
316 | (symver)GLIBC_2.7 2.7 | |
317 | access@GLIBC_2.0 2.2 | |
318 | ||
319 | Tous les symboles associés avec les versions GLIBC_2.0 et GLIBC_2.7 | |
320 | conduiront respectivement à des versions minimales de 2.0 et 2.7, à | |
321 | l'exception du symbole access@GLIBC_2.0. Ce dernier amène à une dépendance | |
322 | minimale sur la version 2.2 de libc6 bien qu'il soit dans le scope de | |
323 | «\ (symvar)GLIBC_2.0\ ». Cela est dû au fait que les symboles spécifiques | |
324 | prennent le pas sur les motifs. | |
325 | ||
326 | Veuillez noter que les anciens motifs avec caractères génériques (indiqués | |
327 | sous la forme «\ *@version\ ») dans le champ de nom de symbole sont toujours | |
328 | gérés. La nouvelle syntaxe «\ (symver|optional)version\ » doit toutefois leur | |
329 | être préférée. Par exemple, «\ *@GLIBC_2.0 2.0\ » devrait être écrit sous la | |
330 | forme «\ (symver|optional)GLIBC_2.0 2.0\ » si un comportement analogue est | |
331 | recherché. | |
332 | .TP | |
333 | \fBregex\fP | |
334 | Les motifs d'expressions rationnelles sont indiqués par l'étiquette | |
335 | \fIregex\fP. La correspondance se fait avec une expression rationnelle Perl sur | |
336 | le champ de nom de symbole. La correspondance est faite telle quelle et il | |
337 | ne faut donc pas oublier le caractère \fI^\fP, sinon la correspondance est | |
338 | faite sur n'importe quelle partie du symbole réel \fIname@version\fP. Par | |
339 | exemple\ : | |
340 | ||
341 | libdummy.so.1 libdummy1 #MINVER# | |
342 | (regex)"^mystack_.*@Base$" 1.0 | |
343 | (regex|optional)"private" 1.0 | |
344 | ||
345 | Les symboles tels que «\ mystack_new@Base\ », «\ mystack_push@Base\ », | |
346 | «\ mystack_pop@Base\ », etc. seront en correspondance avec le premier motif | |
347 | alors que, par exemple, «\ ng_mystack_new@Base\ » ne le sera pas. Le deuxième | |
348 | motif correspondra pour tous les symboles qui comportent la chaîne | |
349 | «\ private\ » dans leur nom et les correspondances hériteront de l'étiquette | |
350 | \fIoptional\fP depuis le motif. | |
351 | .P | |
352 | Les motifs de base indiqués précédemment peuvent être combinés au | |
353 | besoin. Dans ce cas, ils sont traités dans l'ordre où les étiquettes sont | |
354 | indiquées. Par exemple, les deux motifs | |
355 | ||
356 | (c++|regex)"^NSA::ClassA::Private::privmethod\ed\e(int\e)@Base" 1.0 | |
357 | (regex|c++)N3NSA6ClassA7Private11privmethod\edEi@Base 1.0 | |
358 | ||
359 | Seront en correspondance avec les symboles | |
360 | «\ _ZN3NSA6ClassA7Private11privmethod1Ei@Base"\ » et | |
361 | «\ _ZN3NSA6ClassA7Private11privmethod2Ei@Base\ ». Lors de la correspondance | |
362 | avec le premier motif, le symbole complet est d'abord décodé en tant que | |
363 | symbole C++, puis comparé à l'expression rationnelle. D'un autre côté, lors | |
364 | de la correspondance avec le deuxième motif, l'expression rationnelle est | |
365 | comparée au nom de symbole brut, puis le symbole est testé en tant que | |
366 | symbole C++ en tentant de le décoder. L'échec de n'importe quel motif de | |
367 | base provoquera l'échec de l'ensemble du motif. Ainsi, par exemple, | |
368 | «\ __N3NSA6ClassA7Private11privmethod\edEi@Base\ » ne correspondra à aucun des | |
369 | motifs car ce n'est pas un symbole C++ valable (NdT\ :\ j'ai l'impression de | |
370 | traduire du Klingon\ !). | |
371 | ||
372 | En général, les motifs sont divisés en deux groupes\ :\ les alias (\fIc++\fP et | |
373 | \fIsymver\fP de base) et les motifs génériques (\fIregex\fP et toutes les | |
374 | combinaisons de motifs de base multiples). La correspondance de motifs basés | |
375 | sur des alias est rapide (O(1)) alors que les motifs génériques sont O(N) (N | |
376 | étant le nombre de motifs génériques) pour chaque symbole. En conséquence, | |
377 | il est déconseillé d'abuser des motifs génériques. | |
378 | ||
379 | Lorsque plusieurs motifs correspondent pour le même symbole réel, les alias | |
380 | (d'abord \fIc++\fP, puis \fIsymver\fP) sont privilégiés par rapport aux motifs | |
381 | génériques. Ceux\-ci sont essayés dans l'ordre où ils apparaissent dans le | |
382 | modèle de fichier de symboles, en s'arrêtant à la première | |
383 | correspondance. Veuillez noter, cependant, que la modification manuelle de | |
384 | l'ordre des entrées de fichiers n'est pas recommandée car \fBdpkg\-gensymbols\fP | |
385 | crée des fichiers de différences d'après l'ordre alphanumérique de leur nom. | |
386 | .SS "Utilisation des inclusions" | |
387 | .P | |
388 | Lorsqu'un jeu de symboles exportés varie selon les architectures, il est | |
389 | souvent peu efficace d'utiliser un seul fichier de symboles. Pour couvrir | |
390 | ces cas, une directive d'inclusion peut devenir utile dans certains cas\ : | |
391 | .IP • 4 | |
392 | Il est possible de factoriser la partie commune dans un fichier externe | |
393 | donné et l'inclure dans le fichier \fIpaquet\fP.symbols.\fIarch\fP avec une | |
394 | directive «\ include\ » utilisée de la manière suivante\ : | |
395 | ||
396 | #include "\fIpaquets\fP.symbols.common" | |
397 | .IP • | |
398 | La directive d'inclusion peut également être étiquetée comme tout autre | |
399 | symbole\ : | |
400 | ||
401 | (étiquette|...|étiquetteN)#include "fichier_à_inclure" | |
402 | ||
403 | Le résultat sera que tous les symboles inclus depuis \fIfichier_à_inclure\fP | |
404 | seront considérés comme étiquetés par défaut avec \fIetiq\fP ... \fIetiqN\fP. Cela | |
405 | permet de créer un fichier \fIpaquet\fP.symbols commun qui inclut les fichiers | |
406 | de symboles spécifiques des architectures\ : | |
407 | ||
408 | symbole_commun1@Base 1.0 | |
409 | (arch=amd64 ia64 alpha)#include "package.symbols.64bit" | |
410 | (arch=!amd64\ !ia64\ !alpha)#include "package.symbols.32bit" | |
411 | symbole_commun2@Base 1.0 | |
412 | .P | |
413 | Les fichiers de symboles sont lus ligne par ligne et les directives | |
414 | d'inclusion sont traitées dès qu'elles sont trouvées. En conséquence, le | |
415 | contenu du fichier d'inclusion peut remplacer une définition qui précède | |
416 | l'inclusion et ce qui suit l'inclusion peut remplacer une définition qu'elle | |
417 | ajoutait. Tout symbole (ou même une autre directive d'inclusion) dans le | |
418 | fichier inclus peut définir des étiquettes supplémentaires ou remplacer les | |
419 | valeurs d'étiquettes héritées, dans sa définition d'étiquettes. Cependant, | |
420 | pour un symbole donné, il n'existe pas de méthode permettant de remplacer | |
421 | une de ses étiquettes héritées. | |
422 | .P | |
423 | Un fichier inclus peut reprendre la ligne d'en\-tête qui contient le | |
424 | «\ SONAME\ » de la bibliothèque. Dans ce cas, cela remplace toute ligne | |
425 | d'en\-tête précédente. Il est cependant déconseillé de dupliquer les lignes | |
426 | d'en\-tête. Une façon de le faire est la méthode suivante\ : | |
427 | .PP | |
428 | #include "libmachin1.symbols.common" | |
429 | symboles_specifique_architecture@Base 1.0 | |
430 | .SS "Bonnes pratiques de gestion des bibliothèques" | |
431 | .P | |
432 | Une bibliothèque bien maintenue offre les possibilités suivantes\ : | |
433 | .IP • 4 | |
434 | son interface de programmation (API) est stable (les symboles publics ne | |
435 | sont jamais supprimés et les changements ne concernent que des ajouts de | |
436 | nouveaux symboles publics) et les modifications provoquant une | |
437 | incompatibilité doivent être combinés avec un changement de SONAME\ ; | |
438 | .IP • 4 | |
439 | idéalement, elle utilise le versionnement des symboles pour garantir la | |
440 | stabilité de l'interface applicative binaire (ABI) malgré ses modifications | |
441 | internes et l'extension de son API\ ; | |
442 | .IP • 4 | |
443 | elle n'exporte pas les symboles privés (afin de contourner cela, de tels | |
444 | symboles peuvent être étiquetés comme optionnels). | |
445 | .P | |
446 | En maintenant le fichier de symboles, il est facile d'en voir apparaître et | |
447 | disparaître. Cependant, il est plus difficile de contrôler la présence | |
448 | d'éventuelles modifications d'API ou ABI. En conséquence, le responsable | |
449 | doit contrôler soigneusement le journal des modifications amont, à la | |
450 | recherche de cas où une saine gestion des bibliothèques peut avoir été | |
451 | omise. Si des problèmes potentiels sont découverts, l'auteur amont doit être | |
452 | averti(e) car une correction en amont est meilleure qu'un travail spécifique | |
453 | au paquet Debian. | |
454 | .SH OPTIONS | |
455 | .TP | |
456 | \fB\-P\fP\fIrépertoire\-construction\-paquet\fP | |
457 | Analyse de \fIrépertoire\-construction\-paquet\fP, plutôt que debian/tmp. | |
458 | .TP | |
459 | \fB\-p\fP\fIpaquet\fP | |
460 | Définit le nom du paquet. Requis si plus d'un paquet binaire est indiqué | |
461 | dans debian/control (ou s'il n'y a pas de fichier debian/control). | |
462 | .TP | |
463 | \fB\-v\fP\fIversion\fP | |
464 | Définit la version du paquet. La valeur par défaut est la version extraite | |
465 | de debian/changelog. Ce paramètre est requis si le programme est lancé en | |
466 | dehors de l'arborescence source d'un paquet. | |
467 | .TP | |
468 | \fB\-e\fP\fIfichier\-bibliothèque\fP | |
469 | N'analyse que les bibliothèques explicitement mentionnées au lieu de | |
470 | rechercher toutes les bibliothèques publiques. Les motifs du shell peuvent | |
471 | être utilisés pour l'expansion des chemins d'accès (voir la page de manuel | |
472 | de \fBFile::Glob\fP(3perl) pour plus d'informations) dans | |
473 | \fIfichier\-bibliothèque\fP pour établir une correspondance avec plusieurs | |
474 | bibliothèques avec un seul paramètre (afin d'éviter d'utiliser plusieurs | |
475 | options \fB\-e\fP). | |
476 | .TP | |
477 | \fB\-I\fP\fInom\-de\-fichier\fP | |
478 | Utilise \fInom\-de\-fichier\fP comme fichier de référence pour créer le fichier | |
479 | de symboles à intégrer dans le paquet lui\-même. | |
480 | .TP | |
481 | \fB\-O\fP[\fInom\-de\-fichier\fP] | |
482 | Affiche le fichier de symboles créé sur la sortie standard ou dans le | |
483 | \fInom\-de\-fichier\fP, si spécifié, plutôt que dans \fBdebian/tmp/DEBIAN/symbols\fP | |
484 | (ou \fIrépertoire\-construction\-paquet\fP\fB/DEBIAN/symbols\fP si \fB\-P\fP est | |
485 | présent). Si \fInom\-de\-fichier\fP existe déjà, son contenu sera utilisé comme | |
486 | base pour le fichier créé. Cette fonctionnalité permet de mettre à jour le | |
487 | fichier de symboles pour qu'il corresponde à une nouvelle version amont de | |
488 | la bibliothèque. | |
489 | .TP | |
490 | \fB\-t\fP | |
491 | Écrit le fichier de symboles en mode modèle plutôt que dans un format | |
492 | compatible avec \fBdeb\-symbols(5)\fP. La différence majeure réside dans le fait | |
493 | que les noms de symboles et les étiquettes sont écrits dans leur forme | |
494 | d'origine au lieu d'être interprétés, avec réduction des étiquettes en mode | |
495 | de compatibilité. De plus, certains symboles peuvent être omis lors de | |
496 | l'écriture d'un fichier \fBdeb\-symbols(5)\fP standard (selon les règles de | |
497 | traitement des étiquettes) alors que tous les symboles sont écrits lors de | |
498 | la création d'un modèle de fichier de symboles. | |
499 | .TP | |
500 | \fB\-c\fP\fI[0\-4]\fP | |
501 | Définit les contrôles à effectuer lors de la comparaison des symboles créés | |
502 | en utilisant le fichier de modèle comme point de départ. Le niveau par | |
503 | défaut est 1. Plus le niveau est augmenté, plus le nombre de contrôles | |
504 | effectués est important. Chaque niveau de contrôle comporte les contrôles | |
505 | effectués pour les niveaux inférieurs. Le niveau 0 n'échoue jamais. Le | |
506 | niveau 1 échoue si certains symboles ont disparu. Le niveau 2 échoue si de | |
507 | nouveaux symboles ont été ajoutés. Le niveau 3 échoue si certaines | |
508 | bibliothèques ont disparu. Le niveau 4 échoue si des bibliothèques ont été | |
509 | ajoutées. | |
510 | ||
511 | Cette valeur peut être remplacée par la valeur de la variable | |
512 | d'environnement \fBDPKG_GENSYMBOLS_CHECK_LEVEL\fP. | |
513 | .TP | |
514 | \fB\-q\fP | |
515 | Fonctionne en mode silencieux et ne crée jamais de fichier de différences | |
516 | entre le fichier de symboles créé et le fichier modèle utilisé comme point | |
517 | de départ. N'affiche également aucun avertissement à propos de bibliothèques | |
518 | nouvelles ou disparues ou de symboles nouveaux ou disparus. Cette option ne | |
519 | désactive que l'affichage informatif, mais pas les contrôles eux\-mêmes (voir | |
520 | l'option \fB\-c\fP). | |
521 | .TP | |
522 | \fB\-a\fP\fIarch\fP | |
523 | Définit \fIarch\fP comme architecture lors du traitement des fichiers de | |
524 | symboles. Cette option permet de créer un fichier de symboles ou un fichier | |
525 | de différences pour n'importe quelle architecture, à condition que les | |
526 | fichiers binaires correspondants soient déjà disponibles. | |
527 | .TP | |
528 | \fB\-d\fP | |
529 | Active le mode bavard. De nombreux messages sont affichés pour expliquer ce | |
530 | que \fBdpkg\-gensymbols\fP fait. | |
531 | .TP | |
532 | \fB\-V\fP | |
533 | Active le mode bavard. Le fichier de symboles créé contiendra les symboles | |
534 | dépréciés sous forme de commentaires. De plus, en mode modèle, les motifs de | |
535 | symboles seront suivis de commentaires affichant les symboles réels qui | |
536 | correspondent au motif. | |
537 | .TP | |
538 | \fB\-?\fP, \fB\-\-help\fP | |
539 | Affiche un message d'aide puis quitte. | |
540 | .TP | |
541 | \fB\-\-version\fP | |
542 | Affiche le numéro de version puis quitte. | |
543 | . | |
544 | .SH ENVIRONNEMENT | |
545 | .TP | |
546 | \fBDPKG_GENSYMBOLS_CHECK_LEVEL\fP | |
547 | Overrides the command check level, even if the \fB\-c\fP command\-line argument | |
548 | was given (note that this goes against the common convention of command\-line | |
549 | arguments having precedence over environment variables). | |
550 | .SH "VOIR AUSSI" | |
551 | \fBhttps://people.redhat.com/drepper/symbol\-versioning\fP | |
552 | .br | |
553 | \fBhttps://people.redhat.com/drepper/goodpractice.pdf\fP | |
554 | .br | |
555 | \fBhttps://people.redhat.com/drepper/dsohowto.pdf\fP | |
556 | .br | |
557 | \fBdeb\-symbols\fP(5), \fBdpkg\-shlibdeps\fP(1). | |
558 | .SH TRADUCTION | |
559 | Ariel VARDI <ariel.vardi@freesbee.fr>, 2002. | |
560 | Philippe Batailler, 2006. | |
561 | Nicolas François, 2006. | |
562 | Veuillez signaler toute erreur à <debian\-l10n\-french@lists.debian.org>. |