Provided by: dpkg-dev_1.19.7ubuntu2_all bug

NAAM

       dpkg-gensymbols - genereer symbolenbestanden (informatie over afhankelijkheidsrelaties met
       gedeelde bibliotheken)

OVERZICHT

       dpkg-gensymbols [optie...]

BESCHRIJVING

       dpkg-gensymbols doorzoekt een tijdelijke bouwboom (standaard is dat  debian/tmp)  op  zoek
       naar  bibliotheken  en  genereert een symbols-bestand dat ze beschrijft. Dit bestand wordt
       dan als het niet leeg is, geïnstalleerd in een onderliggende map van de  bouwboom  met  de
       naam  DEBIAN,  zodat  het uiteindelijk opgenomen geraakt in de controle-informatie van het
       pakket.

       Bij het genereren van deze bestanden gebruikt het als  invoer  bepaalde  symbolenbestanden
       die  door  de  onderhouder  aangeleverd  worden.  Het zoekt naar de volgende bestanden (en
       gebruikt het eerste dat gevonden wordt):

       ·   debian/pakket.symbols.arch

       ·   debian/symbols.arch

       ·   debian/pakket.symbols

       ·   debian/symbols

       Het hoofddoel van deze bestanden is aan te geven welke de minimale versie is  die  behoort
       bij  elk  van de symbolen die door de bibliotheken aangeleverd worden. Gewoonlijk komt dit
       overeen met de eerste versie van het pakket dat in dat symbool voorzag, maar dit kan  door
       de  onderhouder  manueel  verhoogd  worden  indien  de ABI van het symbool uitgebreid werd
       zonder  dat  daardoor  de  neerwaartse  compatibiliteit  verbroken  wordt.   Het   is   de
       verantwoordelijkheid  van  de  onderhouder  om  deze  bestanden  up-to-date en accuraat te
       houden, maar dpkg-gensymbols helpt hierbij.

       Indien  het  gegenereerde  symbolenbestand  verschilt  van  datgene  wat  de   onderhouder
       aanlevert,   zal   dpkg-gensymbols   de  verschillen  tussen  de  twee  versies  tonen  in
       diff-formaat. Bovendien kan dit zelfs tot een mislukking  leiden  als  de  verschillen  te
       significant zijn (u kunt aanpassen hoeveel verschil u kunt tolereren; zie de optie -c).

HET ONDERHOUD VAN SYMBOLENBESTANDEN

       De  symbolenbestanden  zijn  pas echt nuttig als ze de evolutie van het pakket reflecteren
       doorheen verschillende releases. De onderhouder moet ze dus iedere keer bijwerken  wanneer
       een  nieuw  symbool  toegevoegd wordt, zodat de minimale versie die eraan gekoppeld wordt,
       overeenkomt met de realiteit. De diffs (weergave van de verschillen) die in de bouwlogs te
       vinden  zijn,  kunnen  als  startpunt genomen worden, maar daarbovenop moet de onderhouder
       erop letten dat het gedrag van deze symbolen niet zodanig veranderd werd, dat iets dat van
       deze  symbolen  gebruik  maakt en linkt met de nieuwe versie, niet stopt met werken met de
       oude versie. In de meeste gevallen kan  de  diff  rechtstreeks  toegepast  worden  op  het
       bestand  debian/pakket.symbols.  Dit  gezegd zijnde, zijn verdere aanpassingen meestal wel
       nodig: het wordt bijvoorbeeld aanbevolen om het Debian revisienummer weg te laten  uit  de
       minimale  versie,  zodat  backports (nieuwere programmaversies die geschikt gemaakt worden
       voor een vroegere release) met een lager versienummer  maar  eenzelfde  toeleveraarsversie
       (upstream version) nog steeds voldoen aan de gegenereerde afhankelijkheidsrelaties. Indien
       het Debian revisienummer niet weggelaten  kan  worden  omdat  het  symbool  echt  via  een
       Debian-specifieke   aanpassing   toegevoegd  werd,  moet  men  aan  het  versienummer  het
       achtervoegsel ‘~’ toevoegen.

       Vooraleer een patch toe te passen op een  symbolenbestand,  moet  de  onderhouder  grondig
       controleren  of  dat  wel  correct  is.  Publieke  symbolen  worden  verondersteld niet te
       verdwijnen. Een patch zou dus idealiter enkel nieuwe regels mogen toevoegen.

       Merk op dat u commentaar kunt opnemen in symbolenbestanden: elke regel met ‘#’ als  eerste
       teken  is  een  commentaarregel,  behalve  als  die  regel  begint met ‘#include’ (zie het
       onderdeel over Het gebruik van includes). Regels die beginnen  met  ‘#MISSING:’  zijn  een
       bijzondere vorm van commentaar waarin symbolen die verdwenen zijn, gedocumenteerd worden.

       Vergeet  niet  na te gaan of oudere symboolversies niet verhoogd moeten worden. Er bestaat
       geen manier voor dpkg-gensymbols om in dit  verband  waarschuwingen  te  geven.  Een  diff
       (weergave  van  de verschillen) blindweg toepassen of ervan uitgaan dat er niets aangepast
       moet worden als er geen diff is zonder zelf op eventuele wijzigingen te  controleren,  kan
       leiden   tot   pakketten   met  verslapte  afhankelijkheidsrelaties  die  onterecht  laten
       veronderstellen  dat  ze  met  oudere  pakketten   kunnen   samenwerken.   Dit   kan   bij
       (gedeeltelijke) opwaarderingen leiden tot moeilijk te vinden bugs.

   Substitutie van #PACKAGE# gebruiken
       In   enkele  zeldzame  gevallen  verschilt  de  naam  van  de  bibliotheek  naargelang  de
       architectuur. Om de naam van het pakket niet rechtstreeks in het symbolenbestand te moeten
       inschrijven,  kunt u gebruik maken van de marker #PACKAGE#. Die zal tijdens de installatie
       van de symbolenbestanden vervangen worden door de echte pakketnaam. In  tegenstelling  tot
       de marker #MINVER#, zal #PACKAGE# nooit te vinden zijn in een symbolenbestand binnenin een
       binair pakket.

   Symbooltags gebruiken
       Het gebruik van symbooltags is nuttig om symbolen te markeren die op een of andere  manier
       bijzonder  zijn.  Aan  elk  symbool kan een arbitrair aantal tags gekoppeld worden. Hoewel
       alle tags ontleed en opgeslagen worden, worden  slechts  een  aantal  ervan  herkend  door
       dpkg-gensymbols. Ze lokken een speciale behandeling van de symbolen uit. Zie het onderdeel
       Standaard symbooltags voor een voorstelling van deze tags.

       Tags worden vlak voor de symboolnaam opgegeven (tussenin mag er geen witruimte zijn).  Een
       opgave begint steeds met het openen van een haakje ( en eindigt met het sluiten ervan ) en
       moet minstens één tag  bevatten.  Meerdere  tags  worden  onderling  gescheiden  door  een
       |-teken. Elke tag kan een facultatieve waarde hebben die van de naam van de tag gescheiden
       wordt door het teken =. Namen van tags en waarden  kunnen  arbitraire  tekenreeksen  zijn,
       behalve  dat  zij  niet de speciale tekens ) | = mogen bevatten. De symboolnaam die na een
       tagopgave komt kan facultatief tussen aanhalingstekens geplaatst worden, ofwel  met  '  of
       met  ", waardoor hij witruimte mag bevatten. Evenwel, indien er voor het symbool geen tags
       opgegeven werden, zullen de aanhalingstekens behandeld worden als onderdeel  van  de  naam
       van het symbool die eindigt bij de eerste spatie.

        (tag1=ik werd gemarkeerd|tagnaam met spatie)"getagd en aangehaald symbool"@Base 1.0
        (optional)getagd_niet-aangehaald_symbool@Base 1.0 1
        niet-getagd_symbool@Base 1.0

       Het  eerste  symbool  in  het voorbeeld werd getagd en aangehaald symbool genoemd en heeft
       twee tags: tag1 met als waarde ik werd gemarkeerd en tagnaam met spatie  die  geen  waarde
       heeft.   Het  tweede  symbool  met  als  naam  getagd_niet-aangehaald_symbool  werd  enkel
       gemarkeerd met de tag die optional als naam heeft. Het laatste symbool  is  een  voorbeeld
       van een normaal niet-gemarkeerd symbool.

       Aangezien  symbooltags  een  uitbreiding  zijn  van het deb-symbols(5)-systeem, kunnen zij
       enkel deel uitmaken van de symbolenbestanden die in broncodepakketten gebruikt worden (die
       bestanden   moeten   dan   gezien   worden   als  sjablonen  die  gebruikt  worden  om  de
       symbolenbestanden te bouwen die in de binaire pakketten  zitten).  Indien  dpkg-gensymbols
       aangeroepen  wordt  zonder de optie -t zal het symbolenbestanden produceren die compatibel
       zijn met het deb-symbols(5)-systeem: er gebeurt een volledige verwerking van  de  symbolen
       in  overeenstemming met de vereisten van hun standaardtags en de uitvoer wordt ontdaan van
       alle tags. In sjabloonmodus (-t) daarentegen blijven in de uitvoer alle  symbolen  en  hun
       tags  (zowel  de standaardtags als de niet-gekende) behouden en worden ze in hun originele
       vorm neergeschreven zoals ze geladen werden.

   Standaard symbooltags
       optional
              Een symbool dat als optional (facultatief) gemarkeerd is, kan om het  even  wanneer
              uit   de   bibliotheek  verdwijnen  en  dat  feit  zal  nooit  een  mislukking  van
              dpkg-gensymbols tot gevolg hebben. Nochtans zullen verdwenen facultatieve  symbolen
              permanent  als  MISSING  (ontbrekend) aangegeven worden in de diff (weergave van de
              veranderingen)  bij  elke  nieuwe  pakketrevisie.  Dit   gedrag   dient   als   een
              geheugensteuntje  voor  de  onderhouder  dat  een dergelijk symbool verwijderd moet
              worden uit het symbolenbestand of terug toegevoegd aan de bibliotheek.  Indien  een
              facultatief symbool dat eerder als MISSING opgetekend stond in een volgende revisie
              plots opnieuw terug opduikt, zal het terug  opgewaardeerd  worden  naar  de  status
              “existing” (bestaand) zonder wijziging van zijn minimumversie.

              Deze  tag  is  nuttig  voor  private symbolen waarvan de verdwijning geen ABI-breuk
              veroorzaakt. De meeste van de C++-sjabloon-instantiaties vallen bijvoorbeeld  onder
              deze  categorie.  Zoals  elke andere tag kan ook deze een arbitraire waarde hebben:
              die kan gebruikt worden  om  aan  te  geven  waarom  het  symbool  als  facultatief
              beschouwd wordt.

       arch=architectuurlijst
       arch-bits=architectuur-bits
       arch-endian=architectuur-endianness
              Deze   tags  laten  iemand  toe  om  de  set  architecturen  waarvoor  het  symbool
              verondersteld wordt te bestaan, te  beperken.  De  tags  arch-bits  en  arch-endian
              worden  sinds dpkg 1.18.0 ondersteund. Als de symbolenlijst bijgewerkt wordt met de
              symbolen die in de bibliotheek gevonden worden, worden alle  architectuurspecifieke
              symbolen die van geen belang zijn voor de huidige hostarchitectuur, behandeld alsof
              ze niet bestaan. Indien een architectuurspecifiek symbool dat betrekking  heeft  op
              de   huidige  hostarchitectuur,  ontbreekt  in  de  bibliotheek,  zijn  de  normale
              procedures die gelden voor ontbrekende symbolen, van  toepassing  en  dit  kan  het
              mislukken   van   dpkg-gensymbols   tot   gevolg  hebben.  Anderzijds,  indien  het
              architectuurspecifieke symbool aangetroffen wordt als  het  er  niet  verondersteld
              wordt  te  zijn  (omdat de huidige hostarchitectuur niet vermeld wordt in de tag of
              niet overeenkomt met de endianness of de bits), dan wordt het  architectuurneutraal
              gemaakt (d.w.z. dat de tags arch, arch-bits en arch-endian weggelaten worden en het
              symbool omwille van deze verandering in de diff  (weergave  van  de  veranderingen)
              opgenomen zal worden), maar het wordt niet als nieuw beschouwd.

              Als  in  de  standaardmodus  (niet-sjabloonmodus)  gewerkt  wordt,  worden  van  de
              architectuurspecifieke symbolen enkel die in het symbolenbestand  opgeschreven  die
              overeenkomen  met  de huidige hostarchitectuur. Als daarentegen in de sjabloonmodus
              gewerkt wordt, worden steeds alle architectuurspecifieke  symbolen  (ook  die  voor
              vreemde architecturen) opgeschreven in het symbolenbestand.

              De indeling voor de architectuurlijst is dezelfde als die welke gebruikt wordt voor
              het veld Build-Depends van debian/control (behalve de omsluitende vierkante haakjes
              []).  Met  het  eerste  symbool  uit  de  onderstaande lijst zal bijvoorbeeld enkel
              rekening gehouden worden bij de architecturen alpha, any-amd64  en  ia64,  met  het
              tweede enkel op linux-architecturen en met het derde overal behalve op armel.

               (arch=alpha any-amd64 ia64)een_64bits_specifiek_symbool@Base 1.0
               (arch=linux-any)linux_specifiek_symbool@Base 1.0
               (arch=!armel)symbool_dat_armel_niet_heeft@Base 1.0

              De waarde van architectuur-bits is ofwel 32 of 64.

               (arch-bits=32)32bits_specifiek_symbool@Base 1.0
               (arch-bits=64)64bits_specifiek_symbool@Base 1.0

              De waarde van architectuur-endianness is ofwel little of big.

               (arch-endian=little)little_endian_specifiek_symbool@Base 1.0
               (arch-endian=big)big_endian_specifiek_symbool@Base 1.0

              Meerdere beperkingen kunnen aaneengeregen worden.

               (arch-bits=32|arch-endian=little)32bits_le_symbool@Base 1.0

       ignore-blacklist
              dpkg-gensymbols  hanteert  een  interne  zwarte  lijst van symbolen die niet zouden
              mogen voorkomen in symbolenbestanden omdat ze gewoonlijk  slechts  een  neveneffect
              zijn van details in de wijze waarop de gereedschapskist (toolchain) geïmplementeerd
              wordt. Indien u om een of  andere  reden  echt  wilt  dat  een  van  deze  symbolen
              opgenomen  wordt  in  het  symbolenbestand,  moet u het symbool markeren met de tag
              ignore-blacklist. Dit kan nodig zijn voor sommige gereedschapskistbibliotheken  van
              lagere orde zoals libgcc

       c++    Geeft  een  c++-symboolpatroon  aan.  Zie  hierna  in  de subsectie Het gebruik van
              symboolpatronen.

       symver Geeft een symver (symboolversie) symboolpatroon aan. Zie hierna in de subsectie Het
              gebruik van symboolpatronen.

       regex  Geeft  een  regex-symboolpatroon  aan.  Zie  hierna in de subsectie Het gebruik van
              symboolpatronen.

   Het gebruik van symboolpatronen
       Anders dan een standaardbeschrijving van een  symbool,  kan  een  patroon  meerdere  echte
       symbolen  uit  de  bibliotheek  dekken.  dpkg-gensymbols  zal  proberen  om elk patroon te
       vergelijken  met  elk  reëel  symbool  waarvoor  in  het  symbolenbestand  geen  specifiek
       symboolpendant  gedefinieerd werd. Telkens wanneer een eerste overeenkomst met een patroon
       gevonden wordt, worden alle tags en eigenschappen  ervan  gebruikt  als  basisspecificatie
       voor  het  symbool.  Indien er met geen enkel patroon een overeenkomst gevonden wordt, zal
       het symbool als nieuw beschouwd worden.

       Een patroon wordt als verloren beschouwd als het met geen enkel symbool uit de bibliotheek
       overeenkomt.  Standaard  zal  dit  onder  -c1  of  een  hoger  niveau  een  mislukking van
       dpkg-gensymbols uitlokken. Indien een dergelijke mislukking echter onwenselijk is, kan het
       patroon  gemarkeerd  worden  met  de  tag  optional.  Als  het  patroon  in dat geval geen
       overeenkomst oplevert, zal het enkel in de diff (weergave van de wijzigingen) als  MISSING
       (ontbrekend)  vermeld  worden.  Zoals elk ander symbool kan ook een patroon beperkt worden
       tot  specifieke  architecturen  met  de  tag  arch.  Raadpleeg  het  onderdeel   Standaard
       symbooltags hierboven voor meer informatie.

       Patronen vormen een uitbreiding van het deb-symbols(5)-systeem en zijn daarom enkel geldig
       in symbolenbestandsjablonen. De syntaxis voor het opgeven van patronen verschilt niet  van
       die  voor  een  specifiek  symbool. Het onderdeel symboolnaam van de specificatie fungeert
       echter als een expressie die vergeleken wordt met naam@versie van het  echte  symbool.  Om
       het  onderscheid te maken tussen verschillende types patronen, wordt een patroon doorgaans
       gemarkeerd met een speciale tag

       Op dit ogenblik ondersteunt dpkg-gensymbols drie fundamentele patroontypes:

       c++
          Dit patroon wordt met de tag c++  aangeduid.  Het  zoekt  enkel  een  overeenkomst  met
          C++-symbolen   aan  de  hand  van  hun  ontwarde  (demangled)  symboolnaam  (zoals  die
          weergegeven wordt door het hulpprogramma c++filt(1)). Dit patroon  is  zeer  handig  om
          symbolen  te  vinden  waarvan de verhaspelde naam op verschillende architecturen anders
          kan zijn, terwijl hun ontwarde naam gelijk blijft. Een groep van dergelijke symbolen is
          non-virtual  thunks  die  architectuurspecifieke geheugenplaatsen ingebed hebben in hun
          verhaspelde naam. Een courant voorkomend voorbeeld hiervan is een  virtuele  destructor
          die   onder   een   diamantovererving  een  niet-virtueel  thunk-symbool  nodig  heeft.
          Bijvoorbeeld, zelfs als _ZThn8_N3NSB6ClassDD1Ev@Base op 32-bits-architecturen  wellicht
          _ZThn16_N3NSB6ClassDD1Ev@Base  zal  zijn  op  64-bits-architecturen, kunnen zij met één
          enkel c++-patroon aangeduid worden:

          libdummy.so.1 libdummy1 #MINVER#
           [...]
           (c++)"non-virtual thunk to NSB::ClassD::~ClassD()@Base" 1.0
           [...]

          De bovenstaande ontwarde naam kan verkregen worden door het volgende  commando  uit  te
          voeren:

           $ echo '_ZThn8_N3NSB6ClassDD1Ev@Base' | c++filt

          Merk op dat een verhaspelde naam per definitie uniek is in de bibliotheek, maar dat dit
          niet noodzakelijk het geval is voor ontwarde  namen.  Een  aantal  verschillende  echte
          symbolen  kan  dezelfde  ontwarde  naam  hebben.  Dat  is  bijvoorbeeld  het  geval met
          niet-virtuele thunk-symbolen in complexe  overervingsconfiguraties  of  met  de  meeste
          constructors  en  destructors  (vermits  g++  voor  hen  doorgaans  twee echte symbolen
          genereert). Vermits deze collisies zich op het  ABI-niveau  voordoen,  verminderen  zij
          evenwel niet de kwaliteit van het symbolenbestand.

       symver
          Dit  patroon  wordt door de tag symver aangegeven. Goed onderhouden bibliotheken hebben
          symbolen met versienummers, waarbij elke versie overeenkomt met  de  toeleveraarsversie
          waar  het  symbool  toegevoegd werd. Indien dat het geval is, kunt u een symver-patroon
          gebruiken om eventuele symbolen aan te duiden die  gekoppeld  zijn  aan  de  specifieke
          versie. Bijvoorbeeld:

          libc.so.6 libc6 #MINVER#
           (symver)GLIBC_2.0 2.0
           [...]
           (symver)GLIBC_2.7 2.7
           access@GLIBC_2.0 2.2

          Alle  symbolen  die horen bij de versies GLIBC_2.0 en GLIBC_2.7 zullen resulteren in de
          respectieve  minimale  versies  2.0  en  2.7,  met   uitzondering   van   het   symbool
          access@GLIBC_2.0.  Dit laatste zal resulteren in een minimale vereiste van libc6 versie
          2.2 en  dit  ondanks  het  feit  dat  het  valt  binnen  het  bereik  van  het  patroon
          "(symver)GLIBC_2.0".  De  reden  hiervoor is dat specifieke symbolen voorrang hebben op
          patronen.

          Merk op dat hoewel patronen  met  jokertekens  volgens  de  oude  stijl  (in  het  veld
          symboolnaam  aangegeven  door "*@version") nog steeds ondersteund worden, zij vervangen
          werden door een  syntaxis  volgens  de  nieuwe  stijl  "(symver|optional)version".  Als
          hetzelfde  effect  gewenst  wordt moet bijvoorbeeld "*@GLIBC_2.0 2.0" geschreven worden
          als "(symver|optional)GLIBC_2.0 2.0".

       regex
          Patronen in de vorm van reguliere expressies worden aangegeven met de  tag  regex.  Zij
          zoeken  naar  een  overeenkomst  met de in het veld symboolnaam vermelde perl reguliere
          expressie. Een reguliere expressie wordt als zodanig  vergeleken.  Daarom  mag  u  niet
          vergeten ze te laten beginnen met het teken ^. Anders kan ze een overeenkomst opleveren
          met om het even welk  deel  van  de  tekenreeks  naam@versie  van  het  echte  symbool.
          Bijvoorbeeld:

          libdummy.so.1 libdummy1 #MINVER#
           (regex)"^mystack_.*@Base$" 1.0
           (regex|optional)"private" 1.0

          Symbolen  zoals "mystack_new@Base", "mystack_push@Base", "mystack_pop@Base" enz. zullen
          door het eerste patroon gevonden  worden,  terwijl  "ng_mystack_new@Base"  bijvoorbeeld
          niet.  Het  tweede  patroon zal een overeenkomst opleveren met alle symbolen die in hun
          naam de tekenreeks "private" hebben en de gevonden  symbolen  zullen  de  tag  optional
          overerven van het patroon.

       De  hierboven  vermelde basispatronen kunnen met elkaar gecombineerd worden als dat zinvol
       is. In dat geval worden zij verwerkt in de  volgorde  waarin  de  tags  opgegeven  werden.
       Bijvoorbeeld beide onderstaande patronen

        (c++|regex)"^NSA::ClassA::Private::privmethod\d\(int\)@Base" 1.0
        (regex|c++)N3NSA6ClassA7Private11privmethod\dEi@Base 1.0

       zullen       de       symbolen       "_ZN3NSA6ClassA7Private11privmethod1Ei@Base"       en
       "_ZN3NSA6ClassA7Private11privmethod2Ei@Base" vinden. Bij het vergelijken  met  het  eerste
       patroon  wordt  het rauwe symbool eerst ontward als een C++-symbool en vervolgens wordt de
       ontwarde naam vergeleken met de reguliere expressie. Bij het vergelijken  met  het  tweede
       patroon  daarentegen,  wordt de reguliere expressie vergeleken met de rauwe symboolnaam en
       vervolgens wordt nagegaan of het een C++-symbool is door het te  proberen  ontwarren.  Als
       een basispatroon een mislukking oplevert, betekent dit het mislukken van het hele patroon.
       Om die reden zal "__N3NSA6ClassA7Private11privmethod\dEi@Base" bijvoorbeeld met  geen  van
       beide patronen een overeenkomst opleveren, aangezien het geen geldig C++-symbool is.

       Over  het  algemeen  genomen  kunnen  alle  patronen in twee groepen onderverdeeld worden:
       aliassen (basale c++- en symver-patronen) en generieke patronen (regex,  alle  combinaties
       van  meerdere  basale  patronen).  Het  vergelijken met basale patronen van het alias-type
       verloopt snel (O(1)), terwijl dat bij generieke patronen voor elk symbool O(N) is (waarbij
       N  het aantal generieke patronen is). Daarom wordt aangeraden om geen overdadig gebruik te
       maken van generieke patronen.

       Indien meerdere patronen een overeenkomst opleveren met hetzelfde echte  symbool,  krijgen
       aliassen  (eerst c++, dan symver) de voorkeur boven generieke patronen. Generieke patronen
       worden   vergeleken   in   de   volgorde   waarin   zij   aangetroffen   worden   in   het
       symbolenbestandsjabloon  tot  er een eerste succes volgt. Merk nochtans op dat het manueel
       herordenen  van  items  uit  het  sjabloonbestand   niet   aangeraden   wordt,   aangezien
       dpkg-gensymbols   diffs  (weergave  van  de  veranderingen)  genereert  op  basis  van  de
       alfanumerieke volgorde van hun namen.

   Het gebruik van includes
       Als  de  set  van  geëxporteerde  symbolen  onderling   verschilt   tussen   verschillende
       architecturen,  kan  het  inefficiënt worden om één enkel symbolenbestand te gebruiken. In
       die gevallen kan een include-opdracht op een aantal wijzen nuttig blijken:

       ·   U kunt het gemeenschappelijke gedeelte afsplitsen in een extern bestand en dat bestand
           opnemen  in  uw  bestand pakket.symbols.arch met behulp van een include-opdracht op de
           volgende manier:

           #include "pakketten.symbols.common"

       ·   Net zoals om het even welk symbool kan ook een include-opdracht tags krijgen:

           (tag|...|tagN)#include "in-te-voegen-bestand"

           Als gevolg daarvan zal er standaard van uitgegaan worden dat  alle  symbolen  die  uit
           in-te-voegen-bestand  opgenomen  worden,  gemarkeerd zijn met tag ... tagN. U kunt van
           deze functionaliteit gebruik maken om een gemeenschappelijk bestand pakket.symbols  te
           maken waarin architectuurspecifieke symbolenbestanden opgenomen worden:

             gemeenschappelijk_symbool1@Base 1.0
            (arch=amd64 ia64 alpha)#include "pakket.symbolen.64bits"
            (arch=!amd64 !ia64 !alpha)#include "pakket.symbolen.32bits"
             gemeenschappelijk_symbool2@Base 1.0

       De  symbolenbestanden worden regel per regel gelezen en include-opdrachten worden verwerkt
       van zodra ze tegengekomen worden. Dit betekent dat de inhoud van  het  ingevoegde  bestand
       eventueel  zaken kan vervangen die voor de include-opdracht stonden en dat zaken die na de
       opdracht komen, eventueel inhoud uit het ingevoegde bestand kunnen vervangen. Elk  symbool
       (of  zelfs  een  andere  #include-opdracht) uit het ingevoegde bestand kan bijkomende tags
       opgeven of via zijn tag-vermeldingen waarden van de overgeërfde tags vervangen. Er bestaat
       nochtans geen manier waarop een symbool eventueel overgeërfde tags zou kunnen verwijderen.

       Een ingevoegd bestand kan de kopregel die de SONAME van de bibliotheek bevat, herhalen. In
       dat geval vervangt het een eventueel eerder ingelezen kopregel. Het is over  het  algemeen
       nochtans  best  om het dupliceren van kopregels te vermijden. Een manier om dat te doen is
       de volgende:

       #include "libding1.symbols.common"
        arch_specifiek_symbool@Base 1.0

   Goed beheer van bibliotheken
       Een goed onderhouden bibliotheek heeft de volgende functionaliteit:

       ·   haar API is stabiel (publieke symbolen worden nooit verwijderd,  enkel  worden  nieuwe
           publieke  symbolen  toegevoegd)  en  zij  ondergaat  enkel op een incompatibele manier
           veranderingen als de SONAME verandert;

       ·   idealiter gebruikt  zij  symboolversienummering  om  ondanks  interne  wijzigingen  en
           API-uitbreidingen ABI-stabiliteit te bekomen;

       ·   zij  exporteert  geen  private  symbolen  (dergelijke  symbolen kunnen de tag optional
           krijgen om dat te omzeilen).

       Bij het onderhoud van een  symbolenbestand  is  het  gemakkelijk  om  het  verschijnen  en
       verdwijnen  van  symbolen  op  te  merken. Maar het is moeilijker om incompatibele API- en
       ABI-wijzigingen op te merken. Daarom moet de  onderhouder  het  changelog-bestand  van  de
       toeleveraar  grondig  nakijken  op  situaties waarbij de regels van goed bibliotheekbeheer
       geschonden worden. Indien mogelijke problemen ontdekt worden, zou de  toeleverende  auteur
       erover  ingelicht  moeten worden, aangezien een reparatie op het niveau van de toeleveraar
       altijd te verkiezen valt boven een Debian-specifieke tijdelijke oplossing.

OPTIES

       -Ppakketbouwmap
              Zoek in pakketbouwmap in plaats van in debian/tmp.

       -ppakket
              Definieer de pakketnaam. Is vereist als meer dan één binair pakket vermeld wordt in
              debian/control (of indien er geen bestand debian/control is).

       -vversie
              Definieer  de  pakketversie.  Standaard  is  dat de versie die uit debian/changelog
              gehaald wordt. Is vereist indien het aanroepen gebeurt van buiten de boom  van  het
              broncodepakket.

       -ebibliotheekbestand
              Analyseer  enkel  de  expliciet  vermelde  bibliotheken in plaats van alle publieke
              bibliotheken  te  zoeken.  U  kunt  in   bibliotheekbestand   gebruik   maken   van
              shell-patronen  met het oog op padnaamexpansie (zie de man-pagina File::Glob(3perl)
              voor details) om met één enkel argument meerdere bibliotheken aan te duiden (anders
              heeft u meerdere malen -e nodig).

       -lmap  Voeg  map  vooraan  toe  aan  de  lijst  van  mappen  waarin  naar private gedeelde
              bibliotheken gezocht moet worden (sinds dpkg  1.19.1).  Deze  optie  kan  meermaals
              gebruikt worden.

              Opmerking:  gebruik  deze optie in de plaats van het instellen van LD_LIBRARY_PATH,
              aangezien die omgevingsvariabele gebruikt wordt om de runtime linker aan te sturen.
              Daarvan  misbruik maken om de paden van gedeelde bibliotheken in te stellen tijdens
              het bouwen  van  het  programma,  kan  problematisch  zijn,  bijvoorbeeld  bij  het
              cross-compileren.

       -Ibestandsnaam
              Gebruik  bestandsnaam als referentiebestand om het symbolenbestand te genereren dat
              in het pakket zelf geïntegreerd wordt.

       -O[bestandsnaam]
              Geef het gegenereerde symbolenbestand uit weer op de  standaarduitvoer  of  schrijf
              het    naar    bestandsnaam    als    dat   opgegeven   werd,   eerder   dan   naar
              debian/tmp/DEBIAN/symbols  (of  pakketbouwmap/DEBIAN/symbols  indien  -P   gebruikt
              werd).  Indien bestandsnaam reeds bestond, wordt de inhoud ervan gebruikt als basis
              voor het gegenereerde symbolenbestand. U  kunt  van  deze  functionaliteit  gebruik
              maken  om een symbolenbestand bij te werken zodat het in overeenstemming is met een
              nieuwere toeleveraarsversie van uw bibliotheek.

       -t     Schrijf het  symbolenbestand  in  sjabloonmodus  eerder  dan  in  de  indeling  die
              compatibel  is met deb-symbols(5). Het grootste verschil is dat in de sjabloonmodus
              symboolnamen en tags geschreven worden in hun originele vorm in  tegenstelling  tot
              in  de  compatibele  modus  waarin  de  verwerkte symboolnamen ontdaan van hun tags
              gebruikt  worden.  Daarenboven  kunnen  bij  het  schrijven   van   een   standaard
              deb-symbols(5)-bestand sommige symbolen weggelaten worden (overeenkomstig de regels
              voor het verwerken van tags), terwijl in een  symbolenbestandsjabloon  steeds  alle
              symbolen neergeschreven worden.

       -c[0-4]
              Definieer de controles die moeten gebeuren bij het vergelijken van het gegenereerde
              symbolenbestand  met  het  sjabloonbestand  dat  als  vertrekpunt  gebruikt   werd.
              Standaard  is  dat  volgens  niveau  1.  Het verhogen van het niveau leidt tot meer
              controles, terwijl alle controles van lagere niveaus  behouden  blijven.  Niveau  0
              leidt  nooit  tot  een mislukking. Niveau 1 mislukt als er symbolen verdwenen zijn.
              Niveau 2 geeft een mislukking als nieuwe symbolen geïntroduceerd werden.  Niveau  3
              mislukt  als  er  bibliotheken  verdwenen  zijn.  Niveau 4 geeft een mislukking als
              nieuwe bibliotheken geïntroduceerd werden.

              Deze    waarde    kan    vervangen    worden     door     de     omgevingsvariabele
              DPKG_GENSYMBOLS_CHECK_LEVEL.

       -q     Gedraag  u  rustig  en  genereer  nooit een diff (een overzicht van de verschillen)
              tussen het gegenereerde symbolenbestand en het sjabloonbestand dat als  vertrekpunt
              gebruikt  werd  en  toon  geen  enkele  waarschuwing in verband met nieuwe/verloren
              bibliotheken of nieuwe/verloren symbolen. Deze optie schakelt enkel de informatieve
              uitvoer uit, maar niet de controles zelf (zie de optie -c).

       -aarch Ga  uit  van  arch  als  hostarchitectuur  bij het verwerken van symbolenbestanden.
              Gebruik  deze  optie  om  een  symbolenbestand  of  een  diff  (overzicht  van   de
              verschillen)  voor  een willekeurige architectuur te genereren op voorwaarde dat de
              binaire bestanden ervan reeds voorhanden zijn.

       -d     Zet debug-modus aan. Talrijke berichten worden dan getoond om toe  te  lichten  wat
              dpkg-gensymbols doet.

       -V     Schakel  de  breedsprakige  modus  in.  Het  gegenereerde symbolenbestand bevat dan
              verouderde symbolen in de vorm van commentaar. In sjabloonmodus worden  daarenboven
              patroonsymbolen  gevolgd  door  commentaar  met  daarin  een opsomming van de echte
              symbolen die met het patroon overeenkwamen.

       -?, --help
              Toon info over het gebruik en sluit af.

       --version
              Toon de versie en sluit af.

OMGEVING

       DPKG_GENSYMBOLS_CHECK_LEVEL
              Overschrijft het controleniveau  van  het  commando,  zelfs  als  het  argument  -c
              opgegeven  werd  aan  de  commandoregel  (merk  op dat dit ingaat tegen de algemeen
              geldende    afspraak    dat    commandoregel-argumenten    voorrang    hebben    op
              omgevingsvariabelen).

       DPKG_COLORS
              Stelt  de  kleurmodus  in (sinds dpkg 1.18.5). Waarden die momenteel gebruikt mogen
              worden zijn: auto (standaard), always en never.

       DPKG_NLS
              Indien dit ingesteld is, zal het gebruikt worden om te beslissen over het activeren
              van  moedertaalondersteuning, ook gekend als internationaliseringsondersteuning (of
              i18n) (sinds dpkg 1.19.0). Geldige waarden zijn: 0 and 1 (standaard).

ZIE OOK

       https://people.redhat.com/drepper/symbol-versioning
       https://people.redhat.com/drepper/goodpractice.pdf
       https://people.redhat.com/drepper/dsohowto.pdf
       deb-symbols(5), dpkg-shlibdeps(1).