NAAM

       deb-src-symbols - Uitgebreid sjabloonbestand van Debian voor gedeelde bibliotheken

OVERZICHT

       debian/pakket.symbols.arch, debian/symbols.arch, debian/pakket.symbols, debian/symbols

BESCHRIJVING

       De symboolbestand-sjablonen worden geleverd met Debian bronpakketten en de indeling ervan
       is een superverzameling van de symboolbestanden, geleverd in binaire pakketten, zie
       deb-symbols(5).

   Commentaar
       Commentaar wordt ondersteund in sjabloonsymboolbestanden. 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.

   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 symboolbestand te moeten
       inschrijven, kunt u gebruik maken van de marker #PACKAGE#. Die zal tijdens de installatie
       van de symboolbestanden vervangen worden door de echte pakketnaam. In tegenstelling tot de
       marker #MINVER#, zal #PACKAGE# nooit te vinden zijn in een symboolbestand 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 aangehaald symbool"@Base 1.0
        (optioneel)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 optioneel als naam heeft. Het laatste symbool is een voorbeeld
       van een normaal niet-getagd symbool.

       Aangezien symbooltags een uitbreiding zijn van het deb-symbols(5)-systeem, kunnen zij
       enkel deel uitmaken van de symboolbestanden die in broncodepakketten gebruikt worden (die
       bestanden moeten dan gezien worden als sjablonen die gebruikt worden om de
       symboolbestanden te bouwen die in de binaire pakketten zitten). Indien dpkg-gensymbols
       aangeroepen wordt zonder de optie -t zal het symboolbestanden 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
           pakketbeheerder dat een dergelijk symbool verwijderd moet worden uit het
           symboolbestand of terug toegevoegd aan de bibliotheek. Indien een facultatief symbool
           dat eerder als MISSING opgetekend stond in een volgende revisie plots opnieuw 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 symboolbestand 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 symboolbestand.

           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)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)32bit_le_symbool@Base 1.0

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

       ignore-blacklist
           Een verouderde alias voor allow-internal (sinds dpkg 1.20.1, ondersteund sinds dpkg
           1.15.3).

       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 symboolbestand geen specifiek
       symbooltegenhanger 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 symboolbestand-sjablonen. 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 symboolbestand.

       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 dat voor "ng_mystack_new@Base" niet
           het geval zou zijn. 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 symboolbestand-
       sjabloon 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 symboolbestand 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 "I<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 symboolbestanden opgenomen worden:

             gemeenschappelijk_symbool1@Base 1.0
            (arch=amd64 ia64 alpha)#include "package.symbols.64-bit"
            (arch=!amd64 !ia64 !alpha)#include "package.symbols.32-bit"
             gemeenschappelijk_symbool2@Base 1.0

       De symboolbestanden 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

ZIE OOK

       deb-symbols(5), dpkg-shlibdeps(1), dpkg-gensymbols(1).