.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "deb-src-symbols 5" .TH deb-src-symbols 5 2024-03-10 1.22.6 "dpkg suite" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NOM .IX Header "NOM" deb-src-symbols \- Fichier de mod\(`ele des biblioth\(`eques partag\('ees \('etendues de Debian .SH SYNOPSIS .IX Header "SYNOPSIS" \&\fBdebian/\fR\fIpaquet\fR\fB.symbols.\fR\fIarch\fR, \fBdebian/symbols.\fR\fIarch\fR, \fBdebian/\fR\fIpaquet\fR\fB.symbols\fR, \fBdebian/symbols\fR .SH DESCRIPTION .IX Header "DESCRIPTION" Les mod\(`eles de fichiers de symboles sont fournis dans les paquets source de Debian et leur format est un sous-ensemble des fichiers de symboles fournis dans les paquets binaires, voir \fBdeb\-symbols\fR\|(5). .SS Commentaires .IX Subsection "Commentaires" Comments are supported in template symbol files. Any line with \(oq#\(cq as the first character is a comment except if it starts with \(oq#include\(cq (see section "Using includes"). Lines starting with \(oq#MISSING:\(cq are special comments documenting symbols that have disappeared. .SS "Utilisation du remplacement de #PACKAGE#" .IX Subsection "Utilisation du remplacement de #PACKAGE#" Dans de rares cas, le nom de la biblioth\(`eque d\('epend de l'architecture. Afin d'\('eviter de coder le nom du paquet en dur dans le fichier de symboles, il est possible d'utiliser le marqueur \fI#PACKAGE#\fR. Il sera remplac\('e par le vrai nom du paquet lors de l'installation des fichiers de symboles. \(`A la diff\('erence du marqueur \fI#MINVER#\fR, \fI#PACKAGE#\fR n'appara\(^itra jamais dans le fichier de symboles d'un paquet binaire. .SS "Utilisation des \('etiquettes de symbole" .IX Subsection "Utilisation des \('etiquettes de symbole" Symbol tagging is useful for marking symbols that are special in some way. Any symbol can have an arbitrary number of tags associated with it. While all tags are parsed and stored, only some of them are understood by \fBdpkg-gensymbols\fR and trigger special handling of the symbols. See subsection "Standard symbol tags" for reference of these tags. .PP L'indication de l'\('etiquette vient juste avant le nom du symbole (sans espace). Elle commence toujours par une parenth\(`ese ouvrante \fB(\fR, se termine avec une parenth\(`ese fermante \fB)\fR et doit contenir au moins une \('etiquette. Les \('etiquettes multiples doivent \(^etre s\('epar\('ees par le caract\(`ere \fB|\fR. Chaque \('etiquette peut comporter optionnellement une valeur, s\('epar\('ee du nom de l'\('etiquette par le caract\(`ere \fB=\fR. Les noms et valeurs des \('etiquettes sont des cha\(^ines quelconques qui ne doivent pas comporter les caract\(`eres \fB)\fR \fB|\fR et \fB=\fR. Les noms de symbole qui suivent une \('etiquette peuvent optionnellement \(^etre mis entre guillemets avec les caract\(`eres \fB'\fR ou \fB"\fR afin d'y autoriser la pr\('esence d'espaces. Cependant, si aucune \('etiquette n'est utilis\('ee, les guillemets sont alors trait\('es comme une partie du nom du symbole, qui s'arr\(^ete alors au premier espace. .PP .Vb 3 \& (\('etiq1=je suis marqu\('e|\('etiquette avec espace)"symbole comportant des \& espaces"@Base 1.0 (optional) symbole_non_prot\('eg\('e@Base 1.0 1 \& symbole_non_\('etiquet\('e@Base 1.0 .Ve .PP Le premier symbole de cet exemple est appel\('e \fIsymbole comportant des espaces\fR et utilise deux \('etiquettes\ : \fI\('etiq1\fR avec la valeur \fIje suis marqu\('e\fR et \fI\('etiquette avec espace\fR sans valeur. Le deuxi\(`eme symbole, appel\('e \fIsymbole_non_prot\('eg\('e\fR ne comporte que l'\('etiquette \fIoptional\fR. Le dernier symbole est un exemple de symbole normal sans \('etiquette. .PP Since symbol tags are an extension of the \fBdeb\-symbols\fR\|(5) format, they can only be part of the symbols files used in source packages (those files should then be seen as templates used to build the symbols files that are embedded in binary packages). When \fBdpkg-gensymbols\fR is called without the \fB\-t\fR option, it will output symbols files compatible to the \fBdeb\-symbols\fR\|(5) format: it fully processes symbols according to the requirements of their standard tags and strips all tags from the output. On the contrary, in template mode (\fB\-t\fR) all symbols and their tags (both standard and unknown ones) are kept in the output and are written in their original form as they were loaded. .SS "\('Etiquettes standard de symbole" .IX Subsection "\('Etiquettes standard de symbole" .IP \fBoptional\fR 4 .IX Item "optional" A symbol marked as optional can disappear from the library at any time and that will never cause \fBdpkg-gensymbols\fR to fail. However, disappeared optional symbols will continuously appear as MISSING in the diff in each new package revision. This behavior serves as a reminder for the maintainer that such a symbol needs to be removed from the symbol file or readded to the library. When the optional symbol, which was previously declared as MISSING, suddenly reappears in the next revision, it will be upgraded back to the \(lqexisting\(rq status with its minimum version unchanged. .Sp Cette \('etiquette est utile pour les symboles qui sont priv\('es, car leur disparition ne provoque pas de changement d'interface applicative (ABI). Par exemple, la plupart des mod\(`eles d'instanciation C++ sont dans cette cat\('egorie. Comme toute autre \('etiquette, celle-ci peut comporter une valeur arbitraire qui peut servir \(`a indiquer pour quelle raison le symbole est optionnel. .IP \fBarch=\fR\fIliste-d'architectures\fR 4 .IX Item "arch=liste-d'architectures" .PD 0 .IP \fBarch\-bits=\fR\fIoctets-architecture\fR 4 .IX Item "arch-bits=octets-architecture" .IP \fBarch\-endian=\fR\fIboutisme-d'architecture\fR 4 .IX Item "arch-endian=boutisme-d'architecture" .PD Ces \('etiquettes permettent de restreindre la liste des architectures avec lesquelles le symbole est cens\('e exister. Les \('etiquettes \fBarch-bits\fR et \fBarch-endian\fR sont prises en charge depuis dpkg\ 1.18.0. Lorsque la liste des symboles est mise \(`a jour avec ceux d\('ecouverts dans la biblioth\(`eque, tous les symboles sp\('ecifiques d'architectures qui ne concernent pas l'architecture en cours sont ignor\('es. Si un symbole propre \(`a l'architecture en cours n'existe pas dans la biblioth\(`eque, les processus normaux pour des symboles manquants s'appliquent jusqu'\(`a \('eventuellement provoquer l'\('echec de \fBdpkg-gensymbols\fR. D'un autre c\(^ot\('e, si le symbole propre \(`a une architecture est trouv\('e alors qu'il n'est pas cens\('e exister (parce que l'architecture courante n'est pas mentionn\('ee dans l'\('etiquette ou ne correspond pas au boutisme et aux octets), il est rendu ind\('ependant de l'architecture (c'est\-\(`a\-dire que les \('etiquettes d'architecture, d'octets de l'architecture et de boutisme d'architecture sont abandonn\('ees et le symbole appara\(^it dans le fichier de diff\('erences) mais non consid\('er\('e comme nouveau. (NdT\ : une aspirine peut \(^etre n\('ecessaire apr\(`es la lecture de ce paragraphe) .Sp Dans le mode de fonctionnement par d\('efaut (pas en mode \(Fo\ mod\(`ele\ \(Fc), seuls les symboles sp\('ecifiques de certaines architectures qui correspondent \(`a l'architecture courante sont \('ecrits dans le fichier de symboles. Au contraire, tous les symboles sp\('ecifiques d'architectures (y compris ceux des architectures diff\('erentes) seront \('ecrits dans le fichier de symboles, dans le mode \(Fo\ mod\(`ele\ \(Fc. .Sp Le format de \fIliste-d'architectures\fR est le m\(^eme que le format utilis\('e dans les champs \fBBuild-Depends\fR des fichiers \fIdebian/control\fR (\(`a l'exception des crochets d'inclusion []). Par exemple, le premier symbole de la liste qui suit sera pris en compte sur les architectures alpha, n'importe quelle amd64 et ia64, le second uniquement sur les architectures linux et le troisi\(`eme partout sauf sur armel. .Sp .Vb 3 \& (arch=alpha any\-amd64 ia64)un_symbole_sp\('ecifique_64bit@Base 1.0 \& (arch=linux\-any)un_symbole_sp\('ecifique_linux@Base 1.0 \& (arch=!armel)un_symbole_inexistant_sur_armel@Base 1.0 .Ve .Sp Les \fIoctets-architecture\fR sont soit \fB32\fR soit \fB64\fR. .Sp .Vb 2 \& (arch\-bits=32)32bit_specific_symbol@Base 1.0 \& (arch\-bits=64)64bit_specific_symbol@Base 1.0 .Ve .Sp Le \fIboutisme-d'architecture\fR est soit \fBlittle\fR soit \fBbig\fR. .Sp .Vb 2 \& (arch\-endian=little)little_endian_specific_symbol@Base 1.0 \& (arch\-endian=big)big_endian_specific_symbol@Base 1.0 .Ve .Sp Plusieurs restrictions peuvent \(^etre cha\(^in\('ees. .Sp .Vb 1 \& (arch\-bits=32|arch\-endian=little)32bit_le_symbol@Base 1.0 .Ve .IP \fBallow-internal\fR 4 .IX Item "allow-internal" \&\fBdpkg-gensymbols\fR comporte une liste de symboles internes qui ne devraient pas appara\(^itre dans les fichiers de symboles, car ils sont en g\('en\('eral uniquement des effets de bord de d\('etails de mise en \(oeuvre de la cha\(^ine d'outils de construction (depuis dpkg\ 1.20.1). Si, pour une raison pr\('ecise, vous voulez vraiment inclure un de ces symboles dans le fichier, vous pouvez imposer qu'il soit ignor\('e, avec \fBallow-internal\fR. Cela peut \(^etre utile pour certaines biblioth\(`eques de bas niveau telles que \fBlibgcc\fR. .IP \fBignore-blacklist\fR 4 .IX Item "ignore-blacklist" Un alias obsol\(`ete pour \fBallow-internal\fR (depuis dpkg\ 1.20.1, pris en charge depuis dpkg\ 1.15.3). .IP \fBc++\fR 4 .IX Item "c++" Denotes \fIc++\fR symbol pattern. See "Using symbol patterns" subsection below. .IP \fBsymver\fR 4 .IX Item "symver" Denotes \fIsymver\fR (symbol version) symbol pattern. See "Using symbol patterns" subsection below. .IP \fBregex\fR 4 .IX Item "regex" Denotes \fIregex\fR symbol pattern. See "Using symbol patterns" subsection below. .SS "Utilisation de motifs de symbole" .IX Subsection "Utilisation de motifs de symbole" Au contraire d'une indication normale de symbole, un motif permet de couvrir des symboles multiples de la biblioth\(`eque. \fBdpkg-gensymbols\fR essaie de faire correspondre chaque motif \(`a chaque symbole qui n'est pas explicitement d\('efini dans le fichier de symboles. D\(`es qu'un motif est trouv\('e qui correspond au symbole, l'ensemble de ses \('etiquettes et propri\('et\('es sont utilis\('ees comme sp\('ecification de base du symbole. Si aucun des motifs ne correspond, le symbole sera consid\('er\('e comme nouveau. .PP A pattern is considered lost if it does not match any symbol in the library. By default this will trigger a \fBdpkg-gensymbols\fR failure under \fB\-c1\fR or higher level. However, if the failure is undesired, the pattern may be marked with the \fIoptional\fR tag. Then if the pattern does not match anything, it will only appear in the diff as MISSING. Moreover, like any symbol, the pattern may be limited to the specific architectures with the \fIarch\fR tag. Please refer to "Standard symbol tags" subsection above for more information. .PP Patterns are an extension of the \fBdeb\-symbols\fR\|(5) format hence they are only valid in symbol file templates. Pattern specification syntax is not any different from the one of a specific symbol. However, symbol name part of the specification serves as an expression to be matched against \fIname@version\fR of the real symbol. In order to distinguish among different pattern types, a pattern will typically be tagged with a special tag. .PP Actuellement, \fBdpkg-gensymbols\fR g\(`ere trois types de base de motifs\ : .IP \fBc++\fR 4 .IX Item "c++" This pattern is denoted by the \fIc++\fR tag. It matches only C++ symbols by their demangled symbol name (as emitted by c++\fBfilt\fR\|(1) utility). This pattern is very handy for matching symbols which mangled names might vary across different architectures while their demangled names remain the same. One group of such symbols is \fInon-virtual thunks\fR which have architecture specific offsets embedded in their mangled names. A common instance of this case is a virtual destructor which under diamond inheritance needs a non-virtual thunk symbol. For example, even if _ZThn8_N3NSB6ClassDD1Ev@Base on 32\-bit architectures will probably be _ZThn16_N3NSB6ClassDD1Ev@Base on 64\-bit ones, it can be matched with a single \fIc++\fR pattern: .Sp .Vb 4 \& libdummy.so.1 libdummy1 #MINVER# \& [...] \& (c++)"non\-virtual thunk to NSB::ClassD::~ClassD()@Base" 1.0 \& [...] .Ve .Sp Le nom non d\('ecor\('e ci-dessus peut \(^etre obtenu avec la commande suivante\ : .Sp .Vb 1 \& $ echo \*(Aq_ZThn8_N3NSB6ClassDD1Ev@Base\*(Aq | c++filt .Ve .Sp Veuillez noter que, bien que le nom d\('ecor\('e soit unique dans la biblioth\(`eque par d\('efinition, cela n'est pas forc\('ement vrai pour le nom non d\('ecor\('e. Deux symboles r\('eels diff\('erents peuvent avoir le m\(^eme nom non d\('ecor\('e. C'est par exemple le cas avec les symboles \(Fo\ thunk\ \(Fc non virtuels dans des configurations d'h\('eritage complexes ou avec la plupart des constructeurs et destructeurs (puisque g++ cr\('ee usuellement deux symboles r\('eels pour eux). Cependant, comme ces collisions se produisent au niveau de l'interface applicative binaire (ABI), elles ne devraient pas d\('egrader la qualit\('e du fichier de symboles. .IP \fBsymver\fR 4 .IX Item "symver" Ce motif est indiqu\('e par l'\('etiquette \fIsymver\fR. Les biblioth\(`eques bien g\('er\('ees utilisent des symboles versionn\('es o\(`u chaque version correspond \(`a la version amont \(`a laquelle le symbole a \('et\('e ajout\('e. Si c'est le cas, il est possible d'utiliser un motif \fIsymver\fR pour faire correspondre chaque symbole associ\('e \(`a la version sp\('ecifique. Par exemple\ : .Sp .Vb 5 \& libc.so.6 libc6 #MINVER# \& (symver)GLIBC_2.0 2.0 \& [...] \& (symver)GLIBC_2.7 2.7 \& access@GLIBC_2.0 2.2 .Ve .Sp Tous les symboles associ\('es avec les versions GLIBC_2.0 et GLIBC_2.7 conduiront respectivement \(`a des versions minimales de 2.0 et 2.7, \(`a l'exception du symbole access@GLIBC_2.0. Ce dernier am\(`ene \(`a une d\('ependance minimale sur la version\ 2.2 de libc6 bien qu'il soit dans le scope de \(Fo\ (symvar)GLIBC_2.0\ \(Fc. Cela est d\(^u au fait que les symboles sp\('ecifiques prennent le pas sur les motifs. .Sp Please note that while old style wildcard patterns (denoted by "*@version" in the symbol name field) are still supported, they have been deprecated by new style syntax "(symver|optional)version". For example, "*@GLIBC_2.0 2.0" should be written as "(symver|optional)GLIBC_2.0 2.0" if the same behavior is needed. .IP \fBregex\fR 4 .IX Item "regex" Les motifs d'expressions rationnelles sont indiqu\('es par l'\('etiquette \fIexpression-rationnelle\fR. La correspondance se fait avec une expression rationnelle Perl sur le champ de nom de symbole. La correspondance est faite telle quelle et il ne faut donc pas oublier le caract\(`ere \fI^\fR, sinon la correspondance est faite sur n'importe quelle partie du symbole r\('eel \fIname@version\fR. Par exemple\ : .Sp .Vb 3 \& libdummy.so.1 libdummy1 #MINVER# \& (regex)"^mystack_.*@Base$" 1.0 \& (regex|optional)"private" 1.0 .Ve .Sp Les symboles tels que \(Fo\ mystack_new@Base\ \(Fc, \(Fo\ mystack_push@Base\ \(Fc, \(Fo\ mystack_pop@Base\ \(Fc, etc., seront en correspondance avec le premier motif alors que \(Fo\ ng_mystack_new@Base\ \(Fc ne le sera pas. Le deuxi\(`eme motif correspondra pour tous les symboles qui comportent la cha\(^ine \(Fo\ private\ \(Fc dans leur nom et les correspondances h\('eriteront de l'\('etiquette \fIoptional\fR depuis le motif. .PP Les motifs de base indiqu\('es pr\('ec\('edemment peuvent \(^etre combin\('es au besoin. Dans ce cas, ils sont trait\('es dans l'ordre o\(`u les \('etiquettes sont indiqu\('ees. Par exemple, les deux motifs\ : .PP .Vb 2 \& (c++|regex)"^NSA::ClassA::Private::privmethod\ed\e(int\e)@Base" 1.0 \& (regex|c++)N3NSA6ClassA7Private11privmethod\edEi@Base 1.0 .Ve .PP seront en correspondance avec les symboles \(Fo\ _ZN3NSA6ClassA7Private11privmethod1Ei@Base"\ \(Fc et \(Fo\ _ZN3NSA6ClassA7Private11privmethod2Ei@Base\ \(Fc. Lors de la correspondance avec le premier motif, le symbole brut est d'abord r\('etabli d\(cqorigine en tant que symbole C++, puis compar\('e \(`a l'expression rationnelle. D'un autre c\(^ot\('e, lors de la correspondance avec le deuxi\(`eme motif, l'expression rationnelle est compar\('ee au nom de symbole brut, puis le symbole est test\('e en tant que symbole C++ en tentant de le r\('etablir d\(cqorigine. L'\('echec de n'importe quel motif basique provoquera l'\('echec de l'ensemble du motif. Ainsi, par exemple, \(Fo\ _\|_N3NSA6ClassA7Private11privmethod\edEi@Base\ \(Fc ne correspondra \(`a aucun des motifs, car ce n'est pas un symbole C++ valable (NdT\ : j'ai l'impression de traduire du Klingon !). .PP En g\('en\('eral, les motifs sont divis\('es en deux groupes\ : les alias (\fIc++\fR et \fIsymver\fR basique) et les motifs g\('en\('eriques (\fIexpression-rationnelle\fR et toutes les combinaisons de motifs basiques multiples). La correspondance de motifs bas\('es sur des alias est rapide (O(1)) alors que les motifs g\('en\('eriques sont O(N) (N \('etant le nombre de motifs g\('en\('eriques) pour chaque symbole. En cons\('equence, il est d\('econseill\('e d'abuser des motifs g\('en\('eriques. .PP Lorsque plusieurs motifs correspondent pour le m\(^eme symbole r\('eel, les alias (d'abord \fIc++\fR, puis \fIsymver\fR) sont privil\('egi\('es par rapport aux motifs g\('en\('eriques. Ceux-ci sont essay\('es dans l'ordre o\(`u ils apparaissent dans le mod\(`ele de fichier de symboles, en s'arr\(^etant \(`a la premi\(`ere correspondance. Veuillez noter, cependant, que la modification manuelle de l'ordre des entr\('ees de fichiers n'est pas recommand\('ee, car \fBdpkg-gensymbols\fR cr\('ee des fichiers de diff\('erences d'apr\(`es l'ordre alphanum\('erique de leur nom. .SS "Utilisation des inclusions" .IX Subsection "Utilisation des inclusions" Lorsqu'un jeu de symboles export\('es varie selon les architectures, il est souvent peu efficace d'utiliser un seul fichier de symboles. Pour couvrir ces cas, une directive d'inclusion peut devenir utile dans certains cas\ : .IP \(bu 4 Il est possible de factoriser la partie commune dans un fichier externe donn\('e et l'inclure dans le fichier \fIpaquet\fR.symbols.\fIarch\fR avec une directive \(Fo\ include\ \(Fc utilis\('ee de la mani\(`ere suivante\ : .Sp .Vb 2 \& #include "I.symbols.common" \&=item * .Ve .Sp La directive d'inclusion peut \('egalement \(^etre \('etiquet\('ee comme tout autre symbole\ : .Sp .Vb 2 \& (\('etiquette|...|\('etiquetteN)#include "fichier_\(`a_inclure" \&Le r\('esultat sera que tous les symboles inclus depuis I seront consid\('er\('es comme \('etiquet\('es par d\('efaut avec I ... I. Cela permet de cr\('eer un fichier I.symbols commun qui inclut les fichiers de symboles sp\('ecifiques des S \& \& common_symbol1@Base 1.0 \& (arch=amd64 ia64 alpha)#include "package.symbols.64\-bit" \& (arch=!amd64 !ia64 !alpha)#include "package.symbols.32\-bit" \& common_symbol2@Base 1.0 .Ve .PP Les fichiers de symboles sont lus ligne par ligne et les directives d'inclusion sont trait\('ees d\(`es qu'elles sont trouv\('ees. En cons\('equence, le contenu du fichier d'inclusion peut remplacer une d\('efinition qui pr\('ec\(`ede l'inclusion et ce qui suit l'inclusion peut remplacer une d\('efinition qu'elle ajoutait. Tout symbole (ou m\(^eme une autre directive d'inclusion) dans le fichier inclus peut d\('efinir des \('etiquettes suppl\('ementaires ou remplacer les valeurs d'\('etiquettes h\('erit\('ees, dans sa d\('efinition d'\('etiquettes. Cependant, pour un symbole donn\('e, il n'existe pas de m\('ethode permettant de remplacer une de ses \('etiquettes h\('erit\('ees. .PP Un fichier inclus peut reprendre la ligne d'en\-t\(^ete qui contient le \(Fo\ SONAME\ \(Fc de la biblioth\(`eque. Dans ce cas, cela remplace toute ligne d'en\-t\(^ete pr\('ec\('edente. Il est cependant d\('econseill\('e de dupliquer les lignes d'en\-t\(^ete. Une fa\(,con de le faire est la m\('ethode suivante\ : .PP .Vb 2 \& #include "libmachin1.symbols.common" \& symboles_specifique_architecture@Base 1.0 .Ve .SH "VOIR AUSSI" .IX Header "VOIR AUSSI" \&\fBdeb\-symbols\fR\|(5), \fBdpkg\-shlibdeps\fR\|(1), \fBdpkg\-gensymbols\fR\|(1). .SH TRADUCTION .IX Header "TRADUCTION" Ariel VARDI , 2002. Philippe Batailler, 2006. Nicolas Fran\(,cois, 2006. Veuillez signaler toute erreur \(`a .