638 lines
39 KiB
HTML
638 lines
39 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of dpkg-gensymbols</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>dpkg-gensymbols</H1>
|
|
Section: suite dpkg (1)<BR>Updated: 2020-03-23<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NOM</H2>
|
|
|
|
dpkg-gensymbols - Création des fichiers de symboles (information de
|
|
dépendances de bibliothèques partagées)
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<B>dpkg-gensymbols</B> [<I>option</I>...]
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
<B>dpkg-gensymbols</B> analyse un répertoire temporaire de construction (par
|
|
défaut debian/tmp), y recherche les bibliothèques et crée un fichier
|
|
<I>symbols</I> qui les décrit. Si ce fichier n'est pas vide, il est installé
|
|
dans le sous-répertoire DEBIAN du répertoire de construction afin de pouvoir
|
|
être inclus dans les informations de contrôle du paquet.
|
|
<P>
|
|
|
|
Lors de la création de ces fichiers, il utilise en entrée certains fichiers
|
|
de symboles fournis par le responsable. Il recherche les fichiers suivants
|
|
(en utilisant le premier trouvé) :
|
|
<DL COMPACT>
|
|
<DT id="1">•<DD>
|
|
debian/<I>paquet</I>.symbols.<I>arch</I>
|
|
<DT id="2">•<DD>
|
|
debian/symbols.<I>arch</I>
|
|
<DT id="3">•<DD>
|
|
debian/<I>paquet</I>.symbols
|
|
<DT id="4">•<DD>
|
|
debian/symbols
|
|
</DL>
|
|
<P>
|
|
|
|
L'intérêt principal de ces fichiers est de fournir la version minimale
|
|
associée à chaque symbole fourni par les bibliothèques. En général, cela
|
|
correspond à la première version du paquet qui a fourni ce symbole, mais
|
|
cette valeur peut être augmentée manuellement par le responsable si
|
|
l'interface binaire applicative (ABI) du symbole est étendue sans casser la
|
|
compatibilité avec les versions précédentes. La tenue à jour de ces fichiers
|
|
est à la charge du responsable du paquet, avec l'aide de
|
|
<B>dpkg-gensymbols</B>.
|
|
<P>
|
|
|
|
Quand les fichiers de symboles créés sont différents de ceux fournis par le
|
|
responsable, <B>dpkg-gensymbols</B> affichera les différences entre les deux
|
|
versions. Si ces différences sont trop importantes, le programme peut même
|
|
se terminer en échec (le nombre de différences tolérées peut être réglé avec
|
|
l'option <B>-c</B>).
|
|
<A NAME="lbAE"> </A>
|
|
<H2>TENUE À JOUR DES FICHIERS SYMBOLES</H2>
|
|
|
|
Les fichiers de symboles deviennent réellement utiles lorsqu'ils permettent
|
|
de suivre l'évolution du paquet sur plusieurs versions. En conséquence, le
|
|
responsable doit les mettre à jour chaque fois qu'un nouveau symbole est
|
|
ajouté afin que la version minimale associée corresponde à la réalité. Pour
|
|
effectuer cette opération correctement, le fichier de différences indiqué
|
|
dans le journal de construction peut être utilisé. Dans la plupart des cas,
|
|
ce fichier de différences peut être appliqué tel quel au fichier
|
|
debian/<I>paquet</I>.symbols. Cela étant, quelques adaptations sont généralement
|
|
nécessaires : il est par exemple recommandé de retirer le numéro de révision
|
|
Debian de la version minimale afin que les paquets rétro-portés, de numéro
|
|
de version inférieur mais avec la même version amont continuent à répondre
|
|
aux pré-requis. Si le numéro de révision Debian ne peut vraiment pas être
|
|
retiré car le nouveau symbole est la conséquence d'une modification propre à
|
|
Debian, il est suggéré d'ajouter un suffixe « <B>~</B> » au numéro de version.
|
|
<P>
|
|
|
|
Avant d'appliquer le correctif au fichier de symboles, le responsable doit
|
|
contrôler qu'il est correct. Les symboles publics sont supposés ne jamais
|
|
disparaître et le correctif ne devrait donc qu'ajouter des lignes.
|
|
<P>
|
|
|
|
Veuillez noter qu'il est possible de placer des commentaires dans les
|
|
fichiers de symboles : toute ligne commençant par « # » est un commentaire
|
|
sauf si elle commence par « #include » (voir la section <B>utilisation des
|
|
inclusions</B>). Les lignes commençant par « #MISSING: » sont des commentaires
|
|
spéciaux qui indiquent les symboles qui peuvent avoir disparu.
|
|
<P>
|
|
|
|
N'oubliez pas de vérifier si les anciennes versions des symboles ne doivent
|
|
pas être incrémentées. Il n'y a pas de moyen pour que <B>dpkg-gensymbols</B>
|
|
prévienne de cela. Appliquer aveuglement le fichier de différences ou
|
|
supposer qu'il n'y a rien à changer, s'il n'y a pas de fichier de
|
|
différences, sans vérifier s'il y a ces modifications, peut faire que des
|
|
paquets, avec des dépendances lâches, prétendent qu'ils peuvent fonctionner
|
|
avec des paquets plus anciens avec lesquels ils ne peuvent fonctionner. Cela
|
|
introduira des bogues difficiles à trouver avec des mises à niveau
|
|
(partielles).
|
|
<A NAME="lbAF"> </A>
|
|
<H3>Utilisation du remplacement de #PACKAGE#</H3>
|
|
|
|
<P>
|
|
|
|
Dans de rares cas, le nom de la bibliothèque dépend de l'architecture. Afin
|
|
d'éviter de coder le nom du paquet en dur dans le fichier de symboles, il
|
|
est possible d'utiliser le marqueur <I>#PACKAGE#</I>. Il sera remplacé par le
|
|
vrai nom du paquet lors de l'installation des fichiers de symboles. À la
|
|
différence du marqueur <I>#MINVER#</I>, <I>#PACKAGE#</I> n'apparaîtra jamais dans le
|
|
fichier de symboles d'un paquet binaire.
|
|
<A NAME="lbAG"> </A>
|
|
<H3>Utilisation des étiquettes de symbole</H3>
|
|
|
|
<P>
|
|
|
|
L'étiquetage des symboles (« symbol tagging ») est utile pour marquer des
|
|
symboles qui sont particuliers d'une manière ou d'une autre. Tout symbole
|
|
peut avoir un nombre quelconque d'étiquettes associées. Bien que toutes les
|
|
étiquettes soient analysées et conservées, seules certaines d'entre elles
|
|
sont comprises par <B>dpkg-gensymbols</B> et déclenchent un traitement
|
|
spécifique des symboles. Veuillez consulter la sous-section <B>Étiquettes
|
|
standard de symbole</B> pour une référence complète à propos de ces étiquettes.
|
|
<P>
|
|
|
|
L'indication de l'étiquette vient juste avant le nom du symbole (sans
|
|
espace). Elle commence toujours par une parenthèse ouvrante <B>(</B>, se termine
|
|
avec une parenthèse fermante <B>)</B> et doit contenir au moins une
|
|
étiquette. Les étiquettes multiples doivent être séparées par le caractère
|
|
<B>|</B>. Chaque étiquette peut comporter optionnellement une valeur, séparée du
|
|
nom de l'étiquette par le caractère <B>=</B>. Les noms et valeurs des étiquettes
|
|
sont des chaînes quelconques qui ne doivent pas comporter les caractères
|
|
<B>)</B> <B>|</B> et <B>=</B>. Les noms de symbole qui suivent une étiquette peuvent
|
|
optionnellement être mis entre guillemets avec les caractères <B>'</B> ou <B>"</B>
|
|
afin d'y autoriser la présence d'espaces. Cependant, si aucune étiquette
|
|
n'est utilisée, les guillemets sont alors traités comme une partie du nom du
|
|
symbole, qui s'arrête alors au premier espace.
|
|
<P>
|
|
|
|
<BR> (étiq1=je suis marqué|étiquette avec espace)"symbole comportant des espaces"@Base 1.0
|
|
<BR> (optional)symbole_non_protégé@Base 1.0 1
|
|
<BR> symbole_non_étiqueté@Base 1.0
|
|
<P>
|
|
|
|
Le premier symbole de cet exemple est appelé <I>symbole comportant des
|
|
espaces</I> et utilise deux étiquettes : <I>étiq1</I> avec la valeur <I>je suis
|
|
marqué</I> et <I>étiquette avec espace</I> sans valeur. Le deuxième symbole, appelé
|
|
<I>symbole_non_protégé</I> ne comporte que l'étiquette <I>optional</I>. Le dernier
|
|
symbole est un exemple de symbole normal sans étiquette.
|
|
<P>
|
|
|
|
Comme les étiquettes de symbole sont une extension du format de
|
|
<B><A HREF="/cgi-bin/man/man2html?5+deb-symbols">deb-symbols</A>(5)</B>, elles ne peuvent apparaître que dans les fichiers de
|
|
symboles des paquets source (ces fichiers peuvent ensuite être vus comme des
|
|
modèles permettant de construire les fichiers de symboles inclus dans les
|
|
paquets binaires). Lorsque <B>dpkg-gensymbols</B> est lancé sans l'option <B>-t</B>,
|
|
il affiche les fichiers de symboles compatibles avec le format
|
|
<B><A HREF="/cgi-bin/man/man2html?5+deb-symbols">deb-symbols</A>(5)</B> : il traite entièrement les symboles d'après les exigences
|
|
des étiquettes standard et supprime les étiquettes dans sa sortie. Au
|
|
contraire, dans le mode modèle (« template », option <B>-t</B>), tous les
|
|
symboles et leurs étiquettes (standard et inconnues) sont conservés dans la
|
|
sortie et écrits dans leur forme d'origine.
|
|
<A NAME="lbAH"> </A>
|
|
<H3>Étiquettes standard de symbole</H3>
|
|
|
|
<DL COMPACT>
|
|
<DT id="5"><B>optional</B><DD>
|
|
Un symbole marqué comme optionnel peut disparaître de la bibliothèque à tout
|
|
moment et ne provoquera pas l'échec de <B>dpkg-gensymbols</B>. Cependant, les
|
|
symboles optionnels disparus apparaîtront en permanence comme manquants dans
|
|
le fichier de différences, à chaque nouvelle version du paquet. Ce
|
|
comportement sert de rappel au responsable qu'un tel symbole doit être
|
|
supprimé du fichier de symboles ou bien rajouté à la bibliothèque. Un tel
|
|
symbole optionnel, précédemment déclaré comme manquant (« MISSING »), peut
|
|
réapparaître soudainement dans la version suivante en étant remis à l'état
|
|
existant (« existing »), sans modification de sa version minimale.
|
|
<P>
|
|
Cette étiquette est utile pour les symboles qui sont privés car leur
|
|
disparition ne provoque pas de changement d'interface applicative (ABI). Par
|
|
exemple, la plupart des modèles d'instanciation C++ sont dans cette
|
|
catégorie. Comme toute autre étiquette, celle-ci peut comporter une valeur
|
|
arbitraire qui peut servir à indiquer pour quelle raison le symbole est
|
|
optionnel.
|
|
<DT id="6"><B>arch=</B><I>liste-d'architectures</I><DD>
|
|
|
|
<B>arch-bits=</B><I>octets-architecture</I>
|
|
|
|
<B>arch-endian=</B><I>boutisme-d'architecture</I>
|
|
Ces étiquettes permettent de restreindre la liste des architectures avec
|
|
lesquelles le symbole est censé exister. Les étiquettes <B>arch-bits</B> et
|
|
<B>arch-endian</B> sont prises en charge depuis dpkg 1.18.0. Lorsque la liste
|
|
des symboles est mise à jour avec ceux découverts dans la bibliothèque, tous
|
|
les symboles spécifiques d'architectures qui ne concernent pas
|
|
l'architecture en cours sont ignorés. Si un symbole propre à l'architecture
|
|
en cours n'existe pas dans la bibliothèque, les processus normaux pour des
|
|
symboles manquants s'appliquent jusqu'à éventuellement provoquer l'échec de
|
|
<B>dpkg-gensymbols</B>. D'un autre côté, si le symbole propre à une architecture
|
|
est trouvé alors qu'il n'est pas censé exister (parce que l'architecture
|
|
courante n'est pas mentionnée dans l'étiquette ou ne correspond pas au
|
|
boutisme et aux octets), il est rendu indépendant de l'architecture
|
|
(c'est-à-dire que les étiquettes d'architecture, d'octets de l'architecture
|
|
et de boutisme d'architecture sont abandonnées et le symbole apparaît dans
|
|
le fichier de différences) mais non considéré comme nouveau. (NdT : une
|
|
aspirine peut être nécessaire après la lecture de ce paragraphe)
|
|
<P>
|
|
Dans le mode de fonctionnement par défaut (pas en mode « modèle »), seuls
|
|
les symboles spécifiques de certaines architectures qui correspondent à
|
|
l'architecture courante sont écrits dans le fichier de symboles. Au
|
|
contraire, tous les symboles spécifiques d'architectures (y compris ceux des
|
|
architectures différentes) seront écrits dans le fichier de symboles, dans
|
|
le mode « modèle ».
|
|
<P>
|
|
Le format de <I>liste-d'architectures</I> est le même que le format utilisé dans
|
|
les champs <B>Build-Depends</B> des fichiers <I>debian/control</I> (à 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ème partout sauf sur armel.
|
|
<P>
|
|
<BR> (arch=alpha any-amd64 ia64)un_symbole_spé<A HREF="mailto:cifique_64bit@Base">cifique_64bit@Base</A> 1.0
|
|
<BR> (arch=linux-any)un_symbole_spé<A HREF="mailto:cifique_linux@Base">cifique_linux@Base</A> 1.0
|
|
<BR> (arch=!armel)<A HREF="mailto:un_symbole_inexistant_sur_armel@Base">un_symbole_inexistant_sur_armel@Base</A> 1.0
|
|
<P>
|
|
Les <I>octets-architecture</I> sont soit <B>32</B> soit <B>64</B>.
|
|
<P>
|
|
<BR> (arch-bits=32)<A HREF="mailto:32bit_specific_symbol@Base">32bit_specific_symbol@Base</A> 1.0
|
|
<BR> (arch-bits=64)<A HREF="mailto:64bit_specific_symbol@Base">64bit_specific_symbol@Base</A> 1.0
|
|
<P>
|
|
Le <I>boutisme-d'architecture</I> est soit <B>little</B> soit <B>big</B>.
|
|
<P>
|
|
<BR> (arch-endian=little)<A HREF="mailto:little_endian_specific_symbol@Base">little_endian_specific_symbol@Base</A> 1.0
|
|
<BR> (arch-endian=big)<A HREF="mailto:big_endian_specific_symbol@Base">big_endian_specific_symbol@Base</A> 1.0
|
|
<P>
|
|
Plusieurs restrictions peuvent être chaînées.
|
|
<P>
|
|
<BR> (arch-bits=32|arch-endian=little)<A HREF="mailto:32bit_le_symbol@Base">32bit_le_symbol@Base</A> 1.0
|
|
<DT id="7"><B>ignore-blacklist</B><DD>
|
|
<B>dpkg-gensymbols</B> comporte une liste interne de symboles ignorés qui ne
|
|
devraient pas apparaître dans les fichiers de symboles car ils sont en
|
|
général uniquement des effets de bord de détails de mise en œuvre de la
|
|
chaîne d'outils de construction. Si, pour une raison précise, vous voulez
|
|
vraiment inclure un de ces symboles dans le fichier, vous pouvez imposer
|
|
qu'il soit ignoré, avec <B>ignore-blacklist</B>. Cela peut être utile pour
|
|
certaines bibliothèques de bas niveau telles que libgcc.
|
|
<DT id="8"><B>c++</B><DD>
|
|
Indique un motif de symbole <I>c++</I>. Voir la sous-section <B>Utilisation de
|
|
motifs de symbole</B> plus loin.
|
|
<DT id="9"><B>symver</B><DD>
|
|
Indique un motif de symbole <I>symver</I> (version de symbole). Voir la
|
|
sous-section <B>Utilisation des motifs de symbole</B> plus loin.
|
|
<DT id="10"><B>regex</B><DD>
|
|
Indique un motif de symbole basé sur une <I>expression-rationnelle</I>. Voir la
|
|
sous-section <B>Utilisation des motifs de symbole</B> plus loin.
|
|
</DL>
|
|
<A NAME="lbAI"> </A>
|
|
<H3>Utilisation de motifs de symbole</H3>
|
|
|
|
<P>
|
|
|
|
Au contraire d'une indication normale de symbole, un motif permet de couvrir
|
|
des symboles multiples de la bibliothèque. <B>dpkg-gensymbols</B> essaie de
|
|
faire correspondre chaque motif à chaque symbole qui n'est pas explicitement
|
|
défini dans le fichier de symboles. Dès qu'un motif est trouvé qui
|
|
correspond au symbole, l'ensemble de ses étiquettes et propriétés sont
|
|
utilisées comme spécification de base du symbole. Si aucun des motifs ne
|
|
correspond, le symbole sera considéré comme nouveau.
|
|
<P>
|
|
Un motif est considéré comme perdu si aucun symbole ne lui correspond dans
|
|
la bibliothèque. Par défaut, cela provoquera un échec de <B>dpkg-gensymbols</B>
|
|
s'il est utilisé avec l'option <B>-c1</B> (ou une valeur plus
|
|
élevée). Cependant, si l'échec n'est pas souhaité, le motif peut être marqué
|
|
comme optionnel avec l'étiquette <I>optional</I>. Dans ce cas, si le motif ne
|
|
correspond à rien, il sera simplement mentionné dans le fichier de
|
|
différences comme <I>MISSING</I> (manquant). De plus, comme pour tout autre
|
|
symbole, le motif peut être limité à des architectures données avec
|
|
l'étiquette <I>arch</I>. Veuillez consulter la sous-section <B>Étiquettes
|
|
standard de symbole</B> pour plus d'informations.
|
|
<P>
|
|
Les motifs sont une extension du format de <B><A HREF="/cgi-bin/man/man2html?5+deb-symbols">deb-symbols</A>(5)</B> en ce sens
|
|
qu'ils ne sont valables que dans les modèles de fichiers de
|
|
symboles. Cependant, la partie comportant le nom de symbole est utilisée
|
|
comme une expression à faire correspondre à <I><A HREF="mailto:name@version">name@version</A></I> du symbole
|
|
réel. Afin de faire la distinction entre les différents types de motifs, un
|
|
motif sera usuellement marqué avec une étiquette spéciale.
|
|
<P>
|
|
Actuellement, <B>dpkg-gensymbols</B> gère trois types de base de motifs :
|
|
<DL COMPACT>
|
|
<DT id="11"><B>c++</B><DD>
|
|
Ce motif est repéré par l'étiquette <I>c++</I>. Il ne sera comparé qu'aux
|
|
symboles C++ avec leur nom de symbole rétabli (demangled) tel qu'affiché
|
|
avec l'utilitaire <B>c++filt</B>. Ce motif est très pratique pour faire
|
|
correspondre les symboles dont les noms décorés (mangled) peuvent différer
|
|
selon les architectures bien que leurs noms d'origine restent les mêmes. Un
|
|
tel groupe de symboles sont les <I>non-virtual thunks</I> pour lesquels les
|
|
décalages (offsets) spécifiques d'architectures sont inclus dans leur nom
|
|
décoré. Une manifestation usuelle de ce cas est le destructeur virtuel qui,
|
|
dans le contexte d'un « problème du diamant », a besoin d'un symbole de
|
|
transition spécial (ou « thunk ») non virtuel. Par exemple, même si
|
|
<A HREF="mailto:_ZThn8_N3NSB6ClassDD1Ev@Base">_ZThn8_N3NSB6ClassDD1Ev@Base</A> sur une architecture 32 bits est identique à
|
|
<A HREF="mailto:_ZThn16_N3NSB6ClassDD1Ev@Base">_ZThn16_N3NSB6ClassDD1Ev@Base</A> sur une architecture 64 bits, les deux peuvent
|
|
être indiqués avec le même motif <I>c++</I> :
|
|
<P>
|
|
libdummy.so.1 libdummy1 #MINVER#
|
|
<BR> [...]
|
|
<BR> (c++)"non-virtual thunk to NSB::ClassD::~ClassD()@Base" 1.0
|
|
<BR> [...]
|
|
<P>
|
|
Le nom non décoré ci-dessus peut être obtenu avec la commande suivante :
|
|
<P>
|
|
<BR> $ echo '<A HREF="mailto:_ZThn8_N3NSB6ClassDD1Ev@Base">_ZThn8_N3NSB6ClassDD1Ev@Base</A>' | c++filt
|
|
<P>
|
|
Veuillez noter que, bien que le nom décoré soit unique dans la bibliothèque
|
|
par définition, cela n'est pas forcément vrai pour le nom non décoré. Deux
|
|
symboles réels différents peuvent avoir le même nom non décoré. C'est par
|
|
exemple le cas avec les symboles « thunk » non virtuels dans des
|
|
configurations d'héritage complexes ou avec la plupart des constructeurs et
|
|
destructeurs (puisque g++ crée usuellement deux symboles réels pour
|
|
eux). Cependant, comme ces collisions se produisent au niveau de l'interface
|
|
applicative binaire (ABI), elles ne devraient pas dégrader la qualité du
|
|
fichier de symboles.
|
|
<DT id="12"><B>symver</B><DD>
|
|
Ce motif est indiqué par l'étiquette <I>symver</I>. Les bibliothèques bien
|
|
gérées utilisent des symboles versionnés où chaque version correspond à la
|
|
version amont à laquelle le symbole a été ajouté. Si c'est le cas, il est
|
|
possible d'utiliser un motif <I>symver</I> pour faire correspondre chaque
|
|
symbole associé à la version spécifique. Par exemple :
|
|
<P>
|
|
libc.so.6 libc6 #MINVER#
|
|
<BR> (symver)GLIBC_2.0 2.0
|
|
<BR> [...]
|
|
<BR> (symver)GLIBC_2.7 2.7
|
|
<BR> <A HREF="mailto:access@GLIBC_2.0">access@GLIBC_2.0</A> 2.2
|
|
<P>
|
|
Tous les symboles associés avec les versions GLIBC_2.0 et GLIBC_2.7
|
|
conduiront respectivement à des versions minimales de 2.0 et 2.7, à
|
|
l'exception du symbole <A HREF="mailto:access@GLIBC_2.0">access@GLIBC_2.0</A>. Ce dernier amène à une dépendance
|
|
minimale sur la version 2.2 de libc6 bien qu'il soit dans le scope de
|
|
« (symvar)GLIBC_2.0 ». Cela est dû au fait que les symboles spécifiques
|
|
prennent le pas sur les motifs.
|
|
<P>
|
|
Veuillez noter que les anciens motifs avec caractères génériques (indiqués
|
|
sous la forme « *@version ») dans le champ de nom de symbole sont toujours
|
|
gérés. La nouvelle syntaxe « (symver|optional)version » doit toutefois leur
|
|
être préférée. Par exemple, « *@GLIBC_2.0 2.0 » devrait être écrit sous la
|
|
forme « (symver|optional)GLIBC_2.0 2.0 » si un comportement analogue est
|
|
recherché.
|
|
<DT id="13"><B>regex</B><DD>
|
|
Les motifs d'expressions rationnelles sont indiqués par l'étiquette
|
|
<I>expression-rationnelle</I>. 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ère <I>^</I>, sinon la
|
|
correspondance est faite sur n'importe quelle partie du symbole réel
|
|
<I><A HREF="mailto:name@version">name@version</A></I>. Par exemple :
|
|
<P>
|
|
libdummy.so.1 libdummy1 #MINVER#
|
|
<BR> (regex)"^mystack_.*@Base$" 1.0
|
|
<BR> (regex|optional)"private" 1.0
|
|
<P>
|
|
Les symboles tels que « <A HREF="mailto:mystack_new@Base">mystack_new@Base</A> », « <A HREF="mailto:mystack_push@Base">mystack_push@Base</A> »,
|
|
« <A HREF="mailto:mystack_pop@Base">mystack_pop@Base</A> », etc., seront en correspondance avec le premier motif
|
|
alors que, par exemple, « <A HREF="mailto:ng_mystack_new@Base">ng_mystack_new@Base</A> » ne le sera pas. Le deuxième
|
|
motif correspondra pour tous les symboles qui comportent la chaîne
|
|
« private » dans leur nom et les correspondances hériteront de l'étiquette
|
|
<I>optional</I> depuis le motif.
|
|
</DL>
|
|
<P>
|
|
|
|
Les motifs de base indiqués précédemment peuvent être combinés au
|
|
besoin. Dans ce cas, ils sont traités dans l'ordre où les étiquettes sont
|
|
indiquées. Par exemple, les deux motifs
|
|
<P>
|
|
<BR> (c++|regex)"^NSA::ClassA::Private::privmethod\d\(int\)@Base" 1.0
|
|
<BR> (regex|c++)N3NSA6ClassA7Private11privmethod\<A HREF="mailto:dEi@Base">dEi@Base</A> 1.0
|
|
<P>
|
|
seront en correspondance avec les symboles
|
|
« <A HREF="mailto:_ZN3NSA6ClassA7Private11privmethod1Ei@Base">_ZN3NSA6ClassA7Private11privmethod1Ei@Base</A>" » et
|
|
« <A HREF="mailto:_ZN3NSA6ClassA7Private11privmethod2Ei@Base">_ZN3NSA6ClassA7Private11privmethod2Ei@Base</A> ». Lors de la correspondance
|
|
avec le premier motif, le symbole brut est d'abord rétabli d'origine en tant
|
|
que symbole C++, puis comparé à l'expression rationnelle. D'un autre côté,
|
|
lors de la correspondance avec le deuxième motif, l'expression rationnelle
|
|
est comparée au nom de symbole brut, puis le symbole est testé en tant que
|
|
symbole C++ en tentant de le rétablir d'origine. L'échec de n'importe quel
|
|
motif basique provoquera l'échec de l'ensemble du motif. Ainsi, par exemple,
|
|
« __N3NSA6ClassA7Private11privmethod\<A HREF="mailto:dEi@Base">dEi@Base</A> » ne correspondra à aucun des
|
|
motifs car ce n'est pas un symbole C++ valable (NdT : j'ai l'impression de
|
|
traduire du Klingon !).
|
|
<P>
|
|
En général, les motifs sont divisés en deux groupes : les alias (<I>c++</I> et
|
|
<I>symver</I> basique) et les motifs génériques (<I>expression-rationnelle</I> et
|
|
toutes les combinaisons de motifs basiques multiples). La correspondance de
|
|
motifs basés sur des alias est rapide (<A HREF="/cgi-bin/man/man2html?1+O">O</A>(1)) alors que les motifs génériques
|
|
sont O(N) (N étant le nombre de motifs génériques) pour chaque symbole. En
|
|
conséquence, il est déconseillé d'abuser des motifs génériques.
|
|
<P>
|
|
Lorsque plusieurs motifs correspondent pour le même symbole réel, les alias
|
|
(d'abord <I>c++</I>, puis <I>symver</I>) sont privilégiés par rapport aux motifs
|
|
génériques. Ceux-ci sont essayés dans l'ordre où ils apparaissent dans le
|
|
modèle de fichier de symboles, en s'arrêtant à la première
|
|
correspondance. Veuillez noter, cependant, que la modification manuelle de
|
|
l'ordre des entrées de fichiers n'est pas recommandée car <B>dpkg-gensymbols</B>
|
|
crée des fichiers de différences d'après l'ordre alphanumérique de leur nom.
|
|
<A NAME="lbAJ"> </A>
|
|
<H3>Utilisation des inclusions</H3>
|
|
|
|
<P>
|
|
|
|
Lorsqu'un jeu de symboles exportés 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 :
|
|
<DL COMPACT>
|
|
<DT id="14">•<DD>
|
|
Il est possible de factoriser la partie commune dans un fichier externe
|
|
donné et l'inclure dans le fichier <I>paquet</I>.symbols.<I>arch</I> avec une
|
|
directive « include » utilisée de la manière suivante :
|
|
<P>
|
|
#include "<I>paquets</I>.symbols.common"
|
|
<DT id="15">•<DD>
|
|
La directive d'inclusion peut également être étiquetée comme tout autre
|
|
symbole :
|
|
<P>
|
|
(étiquette|...|étiquetteN)#include "fichier_à_inclure"
|
|
<P>
|
|
Le résultat sera que tous les symboles inclus depuis <I>fichier_à_inclure</I>
|
|
seront considérés comme étiquetés par défaut avec <I>etiq</I> ... <I>etiqN</I>. Cela
|
|
permet de créer un fichier <I>paquet</I>.symbols commun qui inclut les fichiers
|
|
de symboles spécifiques des architectures :
|
|
<P>
|
|
<BR> <A HREF="mailto:symbole_commun1@Base">symbole_commun1@Base</A> 1.0
|
|
<BR> (arch=amd64 ia64 alpha)#include "package.symbols.64bit"
|
|
<BR> (arch=!amd64 !ia64 !alpha)#include "package.symbols.32bit"
|
|
<BR> <A HREF="mailto:symbole_commun2@Base">symbole_commun2@Base</A> 1.0
|
|
</DL>
|
|
<P>
|
|
|
|
Les fichiers de symboles sont lus ligne par ligne et les directives
|
|
d'inclusion sont traitées dès qu'elles sont trouvées. En conséquence, le
|
|
contenu du fichier d'inclusion peut remplacer une définition qui précède
|
|
l'inclusion et ce qui suit l'inclusion peut remplacer une définition qu'elle
|
|
ajoutait. Tout symbole (ou même une autre directive d'inclusion) dans le
|
|
fichier inclus peut définir des étiquettes supplémentaires ou remplacer les
|
|
valeurs d'étiquettes héritées, dans sa définition d'étiquettes. Cependant,
|
|
pour un symbole donné, il n'existe pas de méthode permettant de remplacer
|
|
une de ses étiquettes héritées.
|
|
<P>
|
|
|
|
Un fichier inclus peut reprendre la ligne d'en-tête qui contient le
|
|
« SONAME » de la bibliothèque. Dans ce cas, cela remplace toute ligne
|
|
d'en-tête précédente. Il est cependant déconseillé de dupliquer les lignes
|
|
d'en-tête. Une façon de le faire est la méthode suivante :
|
|
<P>
|
|
|
|
#include "libmachin1.symbols.common"
|
|
<BR> <A HREF="mailto:symboles_specifique_architecture@Base">symboles_specifique_architecture@Base</A> 1.0
|
|
<A NAME="lbAK"> </A>
|
|
<H3>Bonnes pratiques de gestion des bibliothèques</H3>
|
|
|
|
<P>
|
|
|
|
Une bibliothèque bien maintenue offre les possibilités suivantes :
|
|
<DL COMPACT>
|
|
<DT id="16">•<DD>
|
|
son interface de programmation (API) est stable (les symboles publics ne
|
|
sont jamais supprimés et les changements ne concernent que des ajouts de
|
|
nouveaux symboles publics) et les modifications provoquant une
|
|
incompatibilité doivent être combinés avec un changement de SONAME ;
|
|
<DT id="17">•<DD>
|
|
idéalement, elle utilise le versionnage des symboles pour garantir la
|
|
stabilité de l'interface applicative binaire (ABI) malgré ses modifications
|
|
internes et l'extension de son API ;
|
|
<DT id="18">•<DD>
|
|
elle n'exporte pas les symboles privés (afin de contourner cela, de tels
|
|
symboles peuvent être étiquetés comme optionnels).
|
|
</DL>
|
|
<P>
|
|
|
|
En maintenant le fichier de symboles, il est facile d'en voir apparaître et
|
|
disparaître. Cependant, il est plus difficile de contrôler la présence
|
|
d'éventuelles modifications d'API ou ABI. En conséquence, le responsable
|
|
doit contrôler soigneusement le journal des modifications amont, à la
|
|
recherche de cas où une saine gestion des bibliothèques peut avoir été
|
|
omise. Si des problèmes potentiels sont découverts, l'auteur amont doit être
|
|
averti(e) car une correction en amont est meilleure qu'un travail spécifique
|
|
au paquet Debian.
|
|
<A NAME="lbAL"> </A>
|
|
<H2>OPTIONS</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="19"><B>-P</B><I>répertoire-construction-paquet</I><DD>
|
|
Analyse de <I>répertoire-construction-paquet</I>, plutôt que debian/tmp.
|
|
<DT id="20"><B>-p</B><I>paquet</I><DD>
|
|
Définit le nom du paquet. Requis si plus d'un paquet binaire est indiqué
|
|
dans debian/control (ou s'il n'y a pas de fichier debian/control).
|
|
<DT id="21"><B>-v</B><I>version</I><DD>
|
|
Définit la version du paquet. La valeur par défaut est la version extraite
|
|
de debian/changelog. Ce paramètre est requis si le programme est lancé en
|
|
dehors de l'arborescence source d'un paquet.
|
|
<DT id="22"><B>-e</B><I>fichier-bibliothèque</I><DD>
|
|
N'analyse que les bibliothèques explicitement mentionnées au lieu de
|
|
rechercher toutes les bibliothèques publiques. Les motifs du shell peuvent
|
|
être utilisés pour l'expansion des chemins d'accès (voir la page de manuel
|
|
de <B>File::Glob</B>(3perl) pour plus d'informations) dans
|
|
<I>fichier-bibliothèque</I> pour établir une correspondance avec plusieurs
|
|
bibliothèques avec un seul paramètre (afin d'éviter d'utiliser plusieurs
|
|
options <B>-e</B>).
|
|
<DT id="23"><B>-l</B><I>répertoire</I><DD>
|
|
Ajoute <I>répertoire</I> au début de la liste des répertoires où chercher des
|
|
bibliothèques partagées privées (depuis dpkg 1.19.1). Cette option peut être
|
|
utilisée plusieurs fois.
|
|
<P>
|
|
Note : Utilisez cette option plutôt que le réglage de <B>LD_LIBRARY_PATH</B>,
|
|
parce que cette variable d'environnement est utilisée pour contrôler
|
|
l'éditeur de liens d'exécution et se servir d'elle pour définir les chemins
|
|
des bibliothèques partagées au moment de la construction peut être
|
|
problématique, par exemple, lors d'une compilation croisée.
|
|
<DT id="24"><B>-I</B><I>nom-de-fichier</I><DD>
|
|
Utilise <I>nom-de-fichier</I> comme fichier de référence pour créer le fichier
|
|
de symboles à intégrer dans le paquet lui-même.
|
|
<DT id="25"><B>-O</B>[<I>nom-de-fichier</I>]<DD>
|
|
Affiche le fichier de symboles créé sur la sortie standard ou dans le
|
|
<I>nom-de-fichier</I>, si spécifié, plutôt que dans <B>debian/tmp/DEBIAN/symbols</B>
|
|
(ou <I>répertoire-construction-paquet</I><B>/DEBIAN/symbols</B> si <B>-P</B> est
|
|
présent). Si <I>nom-de-fichier</I> existe déjà, son contenu sera utilisé comme
|
|
base pour le fichier créé. Cette fonctionnalité permet de mettre à jour le
|
|
fichier de symboles pour qu'il corresponde à une nouvelle version amont de
|
|
la bibliothèque.
|
|
<DT id="26"><B>-t</B><DD>
|
|
Écrit le fichier de symboles en mode modèle plutôt que dans un format
|
|
compatible avec <B><A HREF="/cgi-bin/man/man2html?5+deb-symbols">deb-symbols</A></B>(5). La différence majeure réside dans le fait
|
|
que les noms de symboles et les étiquettes sont écrits dans leur forme
|
|
d'origine au lieu d'être interprétés, avec réduction des étiquettes en mode
|
|
de compatibilité. De plus, certains symboles peuvent être omis lors de
|
|
l'écriture d'un fichier <B><A HREF="/cgi-bin/man/man2html?5+deb-symbols">deb-symbols</A></B>(5) standard (selon les règles de
|
|
traitement des étiquettes) alors que tous les symboles sont écrits lors de
|
|
la création d'un modèle de fichier de symboles.
|
|
<DT id="27"><B>-c</B><I>[0-4]</I><DD>
|
|
Définit les contrôles à effectuer lors de la comparaison du fichier de
|
|
symboles créé en utilisant le fichier de modèle comme point de départ. Le
|
|
niveau par défaut est 1. Plus le niveau est augmenté, plus le nombre de
|
|
contrôles effectués est important. Chaque niveau de contrôle comporte les
|
|
contrôles effectués pour les niveaux inférieurs. Le niveau 0 n'échoue
|
|
jamais. Le niveau 1 échoue si certains symboles ont disparu. Le niveau 2
|
|
échoue si de nouveaux symboles ont été ajoutés. Le niveau 3 échoue si
|
|
certaines bibliothèques ont disparu. Le niveau 4 échoue si des bibliothèques
|
|
ont été ajoutées.
|
|
<P>
|
|
Cette valeur peut être remplacée par la valeur de la variable
|
|
d'environnement <B>DPKG_GENSYMBOLS_CHECK_LEVEL</B>.
|
|
<DT id="28"><B>-q</B><DD>
|
|
Fonctionne en mode silencieux et ne crée jamais de fichier de différences
|
|
entre le fichier de symboles créé et le fichier modèle utilisé comme point
|
|
de départ. N'affiche également aucun avertissement à propos de bibliothèques
|
|
nouvelles ou disparues ou de symboles nouveaux ou disparus. Cette option ne
|
|
désactive que l'affichage informatif, mais pas les contrôles eux-mêmes (voir
|
|
l'option <B>-c</B>).
|
|
<DT id="29"><B>-a</B><I>arch</I><DD>
|
|
Définit <I>arch</I> comme architecture lors du traitement des fichiers de
|
|
symboles. Cette option permet de créer un fichier de symboles ou un fichier
|
|
de différences pour n'importe quelle architecture, à condition que les
|
|
fichiers binaires correspondants soient déjà disponibles.
|
|
<DT id="30"><B>-d</B><DD>
|
|
Active le mode bavard. De nombreux messages sont affichés pour expliquer ce
|
|
que <B>dpkg-gensymbols</B> fait.
|
|
<DT id="31"><B>-V</B><DD>
|
|
Active le mode bavard. Le fichier de symboles créé contiendra les symboles
|
|
dépréciés sous forme de commentaires. De plus, en mode modèle, les motifs de
|
|
symboles seront suivis de commentaires affichant les symboles réels qui
|
|
correspondent au motif.
|
|
<DT id="32"><B>-?</B>, <B>--help</B><DD>
|
|
Affiche un message d'aide puis quitte.
|
|
<DT id="33"><B>--version</B><DD>
|
|
Affiche le numéro de version puis quitte.
|
|
</DL>
|
|
<A NAME="lbAM"> </A>
|
|
<H2>ENVIRONNEMENT</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="34"><B>DPKG_GENSYMBOLS_CHECK_LEVEL</B><DD>
|
|
Remplace le niveau de vérification de commande, même si l'argument en ligne
|
|
de commande <B>-c</B> a été donné (notez que cela va à l'encontre de la
|
|
convention générale qui veut que les arguments en ligne de commande ont la
|
|
préséance sur les variables d'environnement).
|
|
<DT id="35"><B>DPKG_COLORS</B><DD>
|
|
Définit le mode de couleur (depuis dpkg 1.18.5). Les valeurs actuellement
|
|
acceptées sont <B>auto</B> (par défaut), <B>always</B> et <B>never</B>.
|
|
<DT id="36"><B>DPKG_NLS</B><DD>
|
|
Si cette variable est définie, elle sera utilisée pour décider l'activation
|
|
de la prise en charge des langues (NLS - Native Language Support), connu
|
|
aussi comme la gestion de l'internationalisation (ou i18n) (depuis
|
|
dpkg 1.19.0). Les valeurs permises sont : <B>0</B> et <B>1</B> (par défaut).
|
|
</DL>
|
|
<A NAME="lbAN"> </A>
|
|
<H2>VOIR AUSSI</H2>
|
|
|
|
<B><A HREF="https://people.redhat.com/drepper/symbol-versioning">https://people.redhat.com/drepper/symbol-versioning</A></B>
|
|
<BR>
|
|
|
|
<B><A HREF="https://people.redhat.com/drepper/goodpractice.pdf">https://people.redhat.com/drepper/goodpractice.pdf</A></B>
|
|
<BR>
|
|
|
|
<B><A HREF="https://people.redhat.com/drepper/dsohowto.pdf">https://people.redhat.com/drepper/dsohowto.pdf</A></B>
|
|
<BR>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?5+deb-symbols">deb-symbols</A></B>(5), <B><A HREF="/cgi-bin/man/man2html?1+dpkg-shlibdeps">dpkg-shlibdeps</A></B>(1).
|
|
<A NAME="lbAO"> </A>
|
|
<H2>TRADUCTION</H2>
|
|
|
|
Ariel VARDI <<A HREF="mailto:ariel.vardi@freesbee.fr">ariel.vardi@freesbee.fr</A>>, 2002.
|
|
Philippe Batailler, 2006.
|
|
Nicolas François, 2006.
|
|
Veuillez signaler toute erreur à <<A HREF="mailto:debian-l10n-french@lists.debian.org">debian-l10n-french@lists.debian.org</A>>.
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="37"><A HREF="#lbAB">NOM</A><DD>
|
|
<DT id="38"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="39"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="40"><A HREF="#lbAE">TENUE À JOUR DES FICHIERS SYMBOLES</A><DD>
|
|
<DL>
|
|
<DT id="41"><A HREF="#lbAF">Utilisation du remplacement de #PACKAGE#</A><DD>
|
|
<DT id="42"><A HREF="#lbAG">Utilisation des étiquettes de symbole</A><DD>
|
|
<DT id="43"><A HREF="#lbAH">Étiquettes standard de symbole</A><DD>
|
|
<DT id="44"><A HREF="#lbAI">Utilisation de motifs de symbole</A><DD>
|
|
<DT id="45"><A HREF="#lbAJ">Utilisation des inclusions</A><DD>
|
|
<DT id="46"><A HREF="#lbAK">Bonnes pratiques de gestion des bibliothèques</A><DD>
|
|
</DL>
|
|
<DT id="47"><A HREF="#lbAL">OPTIONS</A><DD>
|
|
<DT id="48"><A HREF="#lbAM">ENVIRONNEMENT</A><DD>
|
|
<DT id="49"><A HREF="#lbAN">VOIR AUSSI</A><DD>
|
|
<DT id="50"><A HREF="#lbAO">TRADUCTION</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:01 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|