Provided by: dpkg-dev_1.22.18ubuntu3_all 
NAMN
deb-src-symbols - Debians utökade mallfil för delade bibliotek
SYNOPS
debian/paket.symbols.ark, debian/symbols.ark, debian/paket.symbols, debian/symbols
BESKRIVNING
Symbolfilmallar medföljer Debiankällkodspaket och dess format är en övermängd av symbols-filen som sänds
med Debianbinärpaket, se deb-symbols(5).
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 #PACKAGE#-substituering
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 markören #PACKAGE#. Den ersätts av det faktiska
paketnamnet när symbolfilen installeras. Till skillnad från #MINVER#-markören kommer #PACKAGE# aldrig att
dyka upp i en symbolfil i ett binärpaket.
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
Dessaa taggar gör det möjligt att begränsa vilken uppsättning arkitekturer symbolen är tänkt att
finnas för. Taggarna arch-bits och arch-endian stöds sedan dpkg 1.18.0. När symbollistan uppdateras
med symboler som upptäcks i biblioteket behandlas alla arkitekturspecifika symboler som inte gäller
den aktuella värdarkitekturen som om de inte fanns. Om en arkitekturspecifik symbol som motsvarar den
aktuella värdarkitekturen inte existerar i biblioteket gäller de vanliga reglerna för saknade
symboler, och kan få dpkg-gensymbols att misslyckas. Å andra sidan, om en arkitekturspecifik symbol
hittas där den inte var menad att finnas (då den aktuella värdarkitekturen inte är listad i taggen
eller inte motsvarar byteordningen eller antal bitar), görs den arkitekturneutral (dvs. taggarna
arch, arch-bits och arch-endgian tas bort och symbolen kommer finnas med i differensen på grund av
denna ändring), men den anses inte som ny.
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.
The format of architecture-list is the same as the one used in the Build-Depends field of
debian/control (except the enclosing square brackets []). For example, the first symbol from the list
below will be considered only on arm64, any-amd64 and riscv64 architectures, the second only on linux
architectures, while the third one anywhere except on armel.
(arch=arm64 any-amd64 riscv64)arch_specific_symbol@Base 1.0
(arch=linux-any)linux_specific_symbol@Base 1.0
(arch=!armel)symbol_armel_does_not_have@Base 1.0
architecture-bits är antingen 32 eller 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
allow-internal
dpkg-gensymbols har en intern svartlista över symboler som inte ska förekomma i symbolfiler eftersom
de oftast bara är sidoeffekter från implementationsdetaljer i verktygskedjan (sedan dpkg 1.20.1). Om
du, av någon orsak, verkligen vill att en av dessa symboler ska tas med i symbolfilen måste du tagga
symbolen med allow-internal. Det kan vara nödvändigt för lågnivå-verktygskedjebibliotek som ”libgcc”.
ignore-blacklist
Ett alias för allow-internal som avråds från (sedan dpkg 1.20.1, stöds sedan dpkg 1.15.3).
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.
Ett mönster anses som tappat om det inte motsvarar några symboler i biblioteket. Som standard kommer
detta få dpkg-genchanges att misslyckas om -c1 eller högre anges. Om ett sådant misslyckande inte är
önskvärt kan mönstret dock märkas med taggen optional. Om mönstret då inte motsvarar någonting kommer det
bara dyka upp i differensen som saknas (MISSING). Mönstret kan dessutom, precis som andra symboler,
begränsas till specifika arkitekturer med hjälp av arch-taggen. Se stycket "Standardsymboltaggar" ovan
för mer information.
Mönster är en utökning av deb-symbols(5)-formatet och är därför endast tillåtna i symbolfilmallar. Syntax
för angivelse av mönster skiljer sig inte från den för en specifik symbol. Symbolnamnsdelen av
specifikationen fungerar dock som ett uttryck som ska jämföras mot namn@version för den faktiska
symbolen. För att skilja mellan olika sorters mönster, taggas mönster normalt med en speciell tagg.
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
Observera att även om det manglade namnet per definition är unikt i biblioteket gäller inte detta för
avmanglade namn. Flera distinkta verkliga symboler kan ha samma avmanglade namn. Det gäller till
exempel för icke-virtuella ”thunk”-symboler i konfigurationer med komplexa arv eller för de flesta
konstruktörer och destruktörer (eftersom g++ normalt genererar två symboler för dem). Eftersom dessa
kollisioner sker på ABI-nivån bör de dock inte sänka kvaliteten på symbolfilen.
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.
Observera att även om den gamla sortens jokerteckenmönster (anges med "*@version" i symbolnamnfältet)
fortfarande stöds så rekommenderas de inte längre i och med den nya sortens syntax
"(symver|optional)version". Till exempel bör "*@GLIBC_2.0 2.0" skrivas som
"(symver|optional)GLIBC_2.0 2.0" om samma beteende behövs.
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.
När flera mönster träffar samma verkliga symbol föredras alias (först c++, sedan symver) framför
generella mönster. Generella mönster träffas i den ordning de upptäcktes i symbolfilmallen fram till den
första lyckade träffen. Observera dock att manuell omsortering av poster i mallfilen inte rekommenderas
då dpkg-gensymbols genererar differensfiler baserad på den alfanumeriska sorteringsordningen av dess
namn.
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:
common_symbol1@Base 1.0
(arch-bits=64)#include "package.symbols.64-bit"
(arch-bits=32)#include "package.symbols.32-bit"
common_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).
ÖVERSÄTTNING
Peter Krefting och Daniel Nylander.
1.22.18 2025-04-28 deb-src-symbols(5)