Kommentarer¶

Kommentarer stöds i symbolmallfilerna. Alla rader med ”#” som första tecken är kommentarer, såvida inte det börjar med ”#include” (se stycket "Använda inkluderingar"). Rader som börjar med ”#MISSING:” är speciella kommentarer som dokumenterar symboler som har försvunnit.

Använda metavariabelsubstituering¶

I vissa fall kan vi använda metavariabler istället för att hårdkoda en del variabel text. De ersätts antingen när symbols-filen som ska skeppas i det binära paketet genereras, eller när beroenden genereras.

Till skillnad från metavariabeln #MINVER# kommer följande metavariabler aldrig att dyka upp i en symbolfil i ett binärpaket.

Använda #PACKAGE#-metavariabeln

I några sällsynta fall skiljer sig namnet på biblioteket mellan arkitekturer. För att undvika att hårdkoda namnet på paketet i symbolfilen kan du använda metavariabeln #PACKAGE#. Den ersätts av det faktiska paketnamnet när symbolfilen installeras.

Använda metavariabeln #CURVER#

I några fall kan en symbol med ett instabilt ABI kräva ett strikt beroende på den aktuella paketversionen. För att undvika att hårdkoda den aktuella versionen i symbolfilen kan du använda metavariabeln #CURVER#. Den kommer att ersättas av en beroendeversionsrestriktion på formen ”(= binärversion)”, där detta vanlitgvis skulle användas i kombination med #PACKAGE#.

Stöds sedan dpkg 1.23.4.

Använda symboltaggar¶

Symboltaggning är nyttigt för att markera symboler som är speciella på något sätt. Alla symboler kan ha ett godtyckligt antal taggar associerade med sig. Medan alla taggar tolkas och lagras är det bara ett par av dem som förstås av dpkg-gensymbols och som utlöser specialhantering av symbolerna. Se undersymbolen "Standardsymboltaggar" för mer information om dessa taggar.

Taggarna anges precis före symbolnamnet (inga blanksteg tillåts mellan). Den börjar alltid med en vänsterparentes (, slutar med en högerparentes ), och måste innehålla minst en tagg. Ytterligare taggar avdelas med tecknet |. En tagg kan ha ett värde, vilket separeras från taggnamnet med tecknet =. Taggnamn och värden kan vara godtyckliga strängar, förutom att de inte kan innehålla de speciella tecknen ) | =. Symbolnamn som följer en taggangivelse kan, om så önskas, citeras med antingen ' eller " för att tillåta blanksteg. Om inga taggar anges för symbolen tolkas dock citattecken som en del av symbolnamnet, vilket fortsätter till det första blanksteget.

  (tag1=jag är markerad|taggnamn med blanksteg)"taggad citerad symbol"@Base 1.0
  (optional)taggad_ociterad_symbol@Base 1.0 1
  otaggad_symbol@Base 1.0

Den första symbolen i exemplet är heter taggad citerad symbol och har två taggar: tag1 med värdet jag är markerad och taggnamn med blanksteg som inte har något värde. Den andra symbolen heter taggad_ociterad_symbol och är bara taggad med taggen som heter optional. Den sista symbolen är ett exempel på en normal, otaggad symbol.

Eftersom symboltaggar er en utökning av formatet i deb-symbols(5) kan de bara användas i symbolfiler i källkodspaket (dessa filer är att anse som mallar som används för att bygga symbolfilerna som finns i binärpaketen). När dpkg-gensymbols anropas utan flaggan -t kommer det att mata ut symbolfiler kompatibla med deb-symbols(5)-formatet: det hanterar symboler helt beroende på vad som beskrivs av standardtaggarna och tar bort alla taggar från utdata. I mall-läge (-t) kommer däremot alla symboler och deras taggar (både standard och okända) att behållas i utdata och skrivas i sin originalform så som de lästes in.

Standardsymboltaggar¶

optional

En symbol markerad som valfri (optional) kan försvinna från bibliotektet när som helst och kommer aldrig göra så att dpkg-gensymbols misslyckas. Försvunna symboler kommer dock fortfarande visas som saknade (MISSING) i differensen för varje ny paketversion. Detta beteende fungerar som en påminnelse för de paketansvariga om att symbolen måste tas bort från symbolfilen eller läggas tillbaka till biblioteket. När en valfri symbol som tidigare markerats som saknad (MISSING) plötsligt dyker upp igen i en senare version kommer den att uppgraderas tillbaka till befintligstatus (”existing”) med den minsta tillgängliga versionen oförändrad.

Taggen är användbar för symboler som är privata och vars försvinnande inte gör att ABI:et går sönder. De flesta C++-mallinstansieringar faller till exempel in under denna kategori. Som andra taggar kan den här även ha ett godtyckligt värde: det kan användas för att indikera varför symbolen är att anse som valfri.

arch=arkitekturlista

arch-bits=arkitekturlista

arch-endian=arkitektur-byteordning

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.

I det vanliga icke-mall-läget skrivs endast de arkitekturspecifika symboler som motsvarar den aktuella värdarkitekturen till symbolfilen. Å andra sidan skrivs alla arkitekturspecifika symboler (inklusive de från andra arkitekturer) till symbolfilen i mall-läget.

Formatet på arkitekturlista är detsamma som det som används i Build-Depends-fältet i debian/control (bortsett från de omslutande hakparenteserna []). Den första symbolen från listan nedan, till exempel, kommer endast att tas med på arkitekturerna arm64, any-amd64 och riscv64, den andra bara på linux-arkitekturer medan den tredje tas med överallt förutom på armel.

  (arch=arm64 any-amd64 riscv64)64bitarsspecifik_symbol@Base 1.0
  (arch=linux-any)linuxspecifik_symbol@Base 1.0
  (arch=!armel)symbol_armel_inte_har@Base 1.0
I<architecture-bits> är antingen B<32> eller B<64>.
  (arch-bits=32)32bitarsspecifik_symbol@Base 1.0
  (arch-bits=64)64bitarsspecifik_symbol@Base 1.0
    

architecture-byteordning är antingen little eller big.

  (arch-endian=little)little_endianspecifik_symbol@Base 1.0
  (arch-endian=big)big_endianspecifik_symbol@Base 1.0
    

Flera begränsningar kan kedjas samman

  (arch-bits=32|arch-endian=little)32bitars_le_symbol@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”.

Stöds sedan dpkg 1.20.1.

c++

Betecknar c++-symbolmönster. Se stycket "Använda symbolmönster" nedan.

symver

Anger symver (symbolversion)-symbolmönstret. Se stycket "Använda symbolmönster" nedan.

regex

Anger regex-symbolmönstret. Se stycket "Använda symbolmönster" nedan.

Använda symbolmönster¶

Till skillnad från vanliga symbolspecifikationer kan ett mönster täcka flera faktiska symboler från biblioteket. dpkg-gensymbols kommer försöka matcha varje mönster mot varje faktisk symbol som inte har en motsvarande specifik symbol definierad i symbolfilen. Så fort det första mönster som motsvarar symbolen hittas kommer alla dess taggar och egenskaper att användas som en basspecifikation för symbolen. Om inget mönster motsvarar symbolen kommer den att tolkas som ny.

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.

För närvarande stöder dpkg-gensymbols tre grundläggande mönstertyper:

c++

Detta mönster anges med taggen c++. Den matchar enbart C++-symboler med deras avmanglade symbolnamn (som det skrivs ut av c++filt(1)-verktyget). Det här mönstret är väldigt nyttigt för att matcha symboler vars manglade namn kan skilja sig mellan olika arkitekturer, medan deras avmanglade namn är desamma. En grupp dylika symboler är icke-virtuella ”thunks” som har arkitekturspecifika offsetvärden inbyggda i sina manglade namn. En vanlig instans av detta fall är en virtuell destruktör som under diamantarv behöver en icke-virtuell ”thunk”-symbol. Även om till exempel ZThn8_N3NSB6ClassDD1Ev@Base på 32-bitarsarkitekturer troligtvis är _ZThn16_N3NSB6ClassDD1Ev@Base på 64-bitarsarkitekturer, så kan de matchas med ett enda c++-mönster:

 libdummy.so.1 libdummy1 #MINVER#
  [...]
  (c++)"non-virtual thunk to NSB::ClassD::~ClassD()@Base" 1.0
  [...]
Det avmanglade namnet ovan kan hämtas genom att utföra följande kommando:
  $ 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

Detta mönster anges med taggen symver. Välunderhållna bibliotek har versionshanterade symboler där varje version motsvarar uppströmsversionen där symbolen lades till. Om det är fallet kan du använda ett symver-möster för att matcha alla symboler som matchar den specifika versionen. Till exempel:

 libc.so.6 libc6 #MINVER#
  (symver)GLIBC_2.0 2.0
  [...]
  (symver)GLIBC_2.7 2.7
  access@GLIBC_2.0 2.2
Alla symboler associerade med versionerna GLIBC_2.0 och GLIBC_2.7 kommer leda till den minimal version 2.0 respektive 2.7, med undantag av symbolen access@GLIBC_2.0. Den sistnämnda kommer leda till ett minsta beroende på libc6 version 2.2 trots att den motsvarar mönstret "(symver)GLIBC_2.0"-mönstret, eftersom specifika symboler gäller före mönster.
    

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

Mönster med reguljära uttryck anges med taggen regex. De matchar med det reguljära uttrycket på perl-form som anges i symbolnamnsfältet. Ett reguljärt uttryck matchar som det står, glöm därför inte att inleda det med tecknet ^, annars kommer det matcha godtycklig del av den verkliga symbolens namn@version-sträng. Till exempel:

 libdummy.so.1 libdummy1 #MINVER#
  (regex)"^mystack_.*@Base$" 1.0
  (regex|optional)"private" 1.0
Symboler som "mystack_new@Base", "mystack_push@Base", "mystack_pop@Base" osv. kommer att träffas av det första mönstret medan "ng_mystack_new@Base" inte gör det. Det andra mönstret motsvarar alla symboler som innehåller strängen "private" i sina namn och träffar kommer att ärva I<optional>-taggen från mönstret.
    

Grundläggande mönster som anges ovan kan kombineras där det är vettigt. I så fall behandlas de i den ordning taggarna anges. Till exempel kommer både:

  (c++|regex)"^NSA::ClassA::Private::privmethod\d\(int\)@Base" 1.0
  (regex|c++)N3NSA6ClassA7Private11privmethod\dEi@Base 1.0
att träffa symbolerna "_ZN3NSA6ClassA7Private11privmethod1Ei@Base" och "_ZN3NSA6ClassA7Private11privmethod2Ei@Base". När det första mönstret jämförs avmanglas först symbolen som en C++-symbol, varefter det avmanglade namnet jämförs med det reguljära uttrycket. När det andra mönstret jämförs, å andra sidan, jämförs det reguljära uttrycket mot det råa symbolnamnet, varefter symbolen testas för att se om det är av C++-typ genom att försöka avmangla det. Om ett grundläggande mönster misslyckas kommer hela uttrycket att misslyckas. Därför kommer, till exempel "__N3NSA6ClassA7Private11privmethod\dEi@Base" inte att träffas av något av mönstrena eftersom det inte är en giltig C++-symbol.

I allmänhet delas alla mönster in i två grupper. alias (grundläggande c++ och symver) och generella mönster (regex, samtliga kombinationer av multipla grundläggande mönster). Det går snabbt att träffa grundläggande aliasbaserade mönster (O(1)) medan generella mönster är O(N) (N - antal generella mönster) för varje symbol. Det rekommenderas därför inte att använda för många generella mönster.

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.

Använda inkluderingar¶

När uppsättningen av exporterade symboler skiljer sig mellan arkitekturer kan det vara ineffektivt att använda en enda symbolfil. I dessa fall kan ett inkluderingsdirektiv vara nyttigt på flera sätt:

• Du kan faktorisera de gemensamma delarna i en extern fil och inkludera den filen i din paket.symbols.arkitektur-fil genom att använda ett inkluderingsdirektiv som detta:

   #include "I<paket>.symbols.common"
      

• Inkluderingsdirektivet kan även taggas som alla andra symboler:

   (tagg|...|taggN)#include "fil-att-inkludera"
      

  Alla symboler som inkluderas från fil-att-inkludera kommer att anses som standard vara taggade med tagg ... taggN. Du kan använda denna funktion för att skapa en gemensam paket.symbols-fil som inkluderar arkitekturspecifika filer:

    gemensam_symbol1@Base 1.0
   (arch-bits=64)#include "package.symbols.64-bit"
   (arch-bits=32)#include "package.symbols.32-bit"
    gemensam_symbol2@Base 1.0
      

Symbolfilerna läses radvis, och inkluderingsdirektiv utförs så fort de upptäcks. Det betyder att innehållet i den inkluderade filen kan överstyra allt innehåll som förekom före inkluderingsdirektivet och att innehåll efter direktivet kan överstyra allt från den inkluderade filen. Alla symboler (även andra #include-direktiv) i den inkluderade filen kan ange ytterligare taggar eller överstyra värden för de ärvda taggarna i sin taggspecifikation. Det finns dock inte något sätt för en symbol att ta bort någon av sina ärvda taggar.

En inkluderad fil kan repetera huvudraden som innehåller SONAME:t för biblioteket. I så fall överstyr den en eventuell huvudrad som lästs in tidigare. Det är vanligtvis dock bäst att undvika att duplicera huvudrader. Ett sätt att göra det är som följer:

 #include "libnågonting1.symbols.common"
  arkitekturspecifik_symbol@Base 1.0
=head1 SE ÄVEN

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