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.

           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 alpha,
           valfri-amd64, ia64, den andra bara på linux-arkitekturer medan den tredje tas med
           överallt förutom på armel.

             (arch=alpha any-amd64 ia64)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

       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 t.ex "ng_mystack_new@Base" inte gör det. Det andra mönstret motsvarar alla symbolen 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:

             gemensam_symbol1@Base 1.0
            (arch=amd64 ia64 alpha)#include "paket.symbols.64bit"
            (arch=!amd64 !ia64 !alpha)#include "paket.symbols.32bit"
             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).

ÖVERSÄTTNING

       Peter Krefting och Daniel Nylander.