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

       The base interchange format of the symbols file is described in deb-symbols(5), which is used by the
       symbols files included in binary packages. These are generated from template symbols files with a format
       based on the former, described in deb-src-symbols(5) and included in source packages.

       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
           Only analyze libraries explicitly listed instead of finding all public libraries. You can use shell
           patterns used for pathname expansions (see the File::Glob manual page for details) in library-file to
           match multiple libraries with a single argument (otherwise you need multiple -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  Write the symbol file in template mode rather than the format compatible with deb-symbols(5). The
           main difference is that in the template mode symbol names and tags are written in their original form
           contrary to the post-processed symbol names with tags stripped in the compatibility mode. Moreover,
           some symbols might be omitted when writing a standard deb-symbols(5) file (according to the tag
           processing rules) while all symbols are always written to the symbol file template.

       -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

       DEB_HOST_ARCH
           Sets the host architecture if the --arch option has not be specified.

       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>.