Provided by: dpkg-dev_1.22.0ubuntu1.1_all 
NOM
dpkg-gensymbols - Création des fichiers de symboles (information de dépendances de
bibliothèques partagées)
SYNOPSIS
dpkg-gensymbols [option...]
DESCRIPTION
dpkg-gensymbols analyse un répertoire temporaire de construction (par défaut debian/tmp),
y recherche les bibliothèques et crée un fichier symbols 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.
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é) :
• debian/paquet.symbols.arch
• debian/symbols.arch
• debian/paquet.symbols
• debian/symbols
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 dpkg-gensymbols.
Quand les fichiers de symboles créés sont différents de ceux fournis par le responsable,
dpkg-gensymbols 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 -c).
This program was introduced in dpkg 1.14.8.
TENUE À JOUR DES FICHIERS SYMBOLES
Le format interchangeable de base du fichier de symboles est décrit dans deb-symbols(5) et
est utilisé par les fichiers de symboles inclus dans les paquets binaires. Ils sont
générés à partir des fichiers de symboles modèles avec un format basé sur le précédent
décrit dans deb-src-symbols(5) et inclus dans les paquets source.
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é, mais en plus, le mainteneur doit s'assurer que
le comportement de ces symboles n'a pas changé d'une manière qui pourrait faire que tout
ce qui utilise ces symboles et qui est lié à la nouvelle version cesse de fonctionner avec
l'ancienne version.
Dans la plupart des cas, ce fichier de différences peut être appliqué tel quel au fichier
debian/paquet.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 « ~ » au numéro de
version.
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.
Notez qu'il est possible d'introduire des commentaires dans les fichiers de symboles.
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 dpkg-gensymbols 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).
Bonnes pratiques de gestion des bibliothèques
Une bibliothèque bien maintenue offre les possibilités suivantes :
• 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ées
avec un changement de SONAME ;
• 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 ;
• elle n'exporte pas les symboles privés (afin de contourner cela, de tels symboles
peuvent être étiquetés comme optionnels).
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.
OPTIONS
-Prépertoire-construction-paquet
Analyse de répertoire-construction-paquet, plutôt que debian/tmp.
-ppaquet
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).
-vversion
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.
-efichier-bibliothèque
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 File::Glob(3perl) pour plus
d'informations) dans fichier-bibliothèque pour établir une correspondance avec
plusieurs bibliothèques avec un seul paramètre (afin d'éviter d'utiliser plusieurs
options -e).
-lrépertoire
Ajoute répertoire 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.
Note: Use this option instead of setting LD_LIBRARY_PATH, as that environment variable
is used to control the run-time linker and abusing it to set the shared library paths
at build-time can be problematic when cross-compiling for example.
-Inom-de-fichier
Utilise nom-de-fichier comme fichier de référence pour créer le fichier de symboles à
intégrer dans le paquet lui-même.
-O[nom-de-fichier]
Affiche le fichier de symboles créé sur la sortie standard ou dans le nom-de-fichier,
si spécifié, plutôt que dans debian/tmp/DEBIAN/symbols (ou
répertoire-construction-paquet/DEBIAN/symbols si -P est présent). Si nom-de-fichier
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.
-t Écrit le fichier de symboles en mode modèle plutôt que dans un format compatible avec
deb-symbols(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 deb-symbols(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.
-c[0-4]
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.
Niveau 0
Sans échec.
Niveau 1
Échoue si certains symboles ont disparu.
Niveau 2
Échoue si de nouveaux symboles ont été ajoutés.
Niveau 3
Échoue si certaines bibliothèques ont disparu.
Niveau 4
Échoue si des bibliothèques ont été ajoutées.
Cette valeur peut être remplacée par la valeur de la variable d'environnement
DPKG_GENSYMBOLS_CHECK_LEVEL.
-q 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 -c).
-aarch
Définit arch 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.
-d Active le mode bavard. De nombreux messages sont affichés pour expliquer ce que dpkg-
gensymbols fait.
-V 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.
-?, --help
Afficher un message d'aide puis quitter.
--version
Afficher le numéro de version puis quitter.
ENVIRONNEMENT
DPKG_GENSYMBOLS_CHECK_LEVEL
Remplace le niveau de vérification de commande, même si l'argument en ligne de
commande -c 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).
DPKG_COLORS
Définit le mode de couleur (depuis dpkg 1.18.5). Les valeurs actuellement acceptées
sont auto (par défaut), always et never.
DPKG_NLS
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 : 0 et 1 (par défaut).
VOIR AUSSI
<https://people.redhat.com/drepper/symbol-versioning>,
<https://people.redhat.com/drepper/goodpractice.pdf>,
<https://people.redhat.com/drepper/dsohowto.pdf>, deb-src-symbol(5), deb-symbols(5), dpkg-
shlibdeps(1).
TRADUCTION
Ariel VARDI <ariel.vardi@freesbee.fr>, 2002. Philippe Batailler, 2006. Nicolas François,
2006. Veuillez signaler toute erreur à <debian-l10n-french@lists.debian.org>.