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.

Substituties voor metavariabelen gebruiken¶

In sommige gevallen kunnen we, in plaats van variabele tekst hard te coderen, metavariabelen gebruiken die worden vervangen tijdens het genereren van het symbolenbestand dat in het binaire pakket wordt opgenomen, of tijdens het genereren van vereisten.

In tegenstelling tot de metavariabele #MINVER#, zullen de volgende metavariabelen nooit te vinden zijn in een symboolbestand binnenin een binair pakket.

De metavariabele #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 metavariabele #PACKAGE#. Die zal tijdens de installatie van de symboolbestanden vervangen worden door de echte pakketnaam.

De metavariabele #CURVER# gebruiken

In sommige gevallen vereist een symbool met een onstabiele ABI een strikte vereiste van de huidige pakketversie. Om te voorkomen dat de huidige versie hard gecodeerd wordt in het symbolenbestand, kunt u de metavariabele #CURVER# gebruiken. Deze wordt vervangen door een vereistenversiebeperking in de vorm van “(= binair-versie)”, waarbij dit over het algemeen wordt gebruikt in combinatie met #PACKAGE#.

Ondersteund sinds dpkg 1.23.4.

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

These tags allow one to restrict the set of architectures where the symbol is supposed to exist. When the symbols list is updated with the symbols discovered in the library, all arch-specific symbols which do not concern the current host architecture are treated as if they did not exist. If an arch-specific symbol matching the current host architecture does not exist in the library, normal procedures for missing symbols apply and it may cause dpkg-gensymbols to fail. On the other hand, if the arch-specific symbol is found when it was not supposed to exist (because the current host architecture is not listed in the tag or does not match the endianness and bits), it is made arch neutral (i.e. the arch, arch-bits and arch-endian tags are dropped and the symbol will appear in the diff due to this change), but it is not considered as new.

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 arm64, any-amd64 en riscv64, met het tweede enkel op linux-architecturen en met het derde overal behalve op armel.

  (arch=arm64 any-amd64 riscv64)arch_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
    

Support for tags arch-bits and arch-endian since dpkg 1.18.0.

allow-internal

dpkg-gensymbols has a list of internal symbols that should not appear in symbols files as they are usually only side-effects of implementation details of the toolchain. If for some reason, you really want one of those symbols to be included in the symbols file, you should tag the symbol with allow-internal. It can be necessary for some low level toolchain libraries like “libgcc”.

Ondersteund sinds dpkg 1.20.1.

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.

A pattern is considered lost if it does not match any symbol in the library. By default this will trigger a dpkg-gensymbols failure under -c1 or higher level. However, if the failure is undesired, the pattern may be marked with the optional tag. Then if the pattern does not match anything, it will only appear in the diff as MISSING. Moreover, like any symbol, the pattern may be limited to the specific architectures with the arch tag. See the "Standard symbol tags" subsection above for more information.

Patterns are an extension of the deb-symbols(5) format hence they are only valid in symbol file templates. Pattern specification syntax is not any different from the one of a specific symbol. However, symbol name part of the specification serves as an expression to be matched against name@version of the real symbol. To distinguish among different pattern types, a pattern will typically be tagged with a special 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
    

Note that while mangled name is unique in the library by definition, this is not necessarily true for demangled names. A couple of distinct real symbols may have the same demangled name. For example, that's the case with non-virtual thunk symbols in complex inheritance configurations or with most constructors and destructors (since g++ typically generates two real symbols for them). However, as these collisions happen on the ABI level, they should not degrade quality of the symbol file.

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.

Note that while old style wildcard patterns (denoted by "*@version" in the symbol name field) are still supported, they have been deprecated by new style syntax "(symver|optional)version". For example, "*@GLIBC_2.0 2.0" should be written as "(symver|optional)GLIBC_2.0 2.0" if the same behavior is needed.

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.

When multiple patterns match the same real symbol, aliases (first c++, then symver) are preferred over generic patterns. Generic patterns are matched in the order they are found in the symbol file template until the first success. Note, however, that manual reordering of template file entries is not recommended because dpkg-gensymbols generates diffs based on the alphanumerical order of their names.

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-bits=64)#invoegen van "pakket.symbolen.64-bit"
   (arch-bits=32)#invoegen van "pakket.symbolen.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