Provided by:
dpkg-dev_1.15.8.4ubuntu3_all 
NAMN
dpkg-gensymbols - generera symbolfiler (information om delade
bibliotek)
SYNOPS
dpkg-gensymbols [flaggor]
BESKRIVNING
dpkg-gensymbols sker genom en temporrt byggtrd (som standard
debian/tmp) efter bibliotek och skapar en symbols-fil som beskriver
dem. Denna fil kommer sedan, svida den inte r tom, att installeras i
DEBIAN-underkatalogen i byggtrdet s att den hamnar i styrinformationen
i paketet.
Nr dessa filer skapas, anvnds ett par symbolfiler frn paketansvariga
som indata. Programmet sker efter fljande filer (och anvnder den frsta
det finner):
o debian/paket.symbols.arkitektur
o debian/symbols.arkitektur
o debian/paket.symbols
o debian/symbols
Dessa filer r i huvudsak intressanta fr att kunna tillhandahlla den
minimala version associerad med varje symbol i biblioteken. Detta
motsvarar normalt den frsta version av paketet som tillhandahll
symbolen, men det kan manuellt inkrementeras av de ansvariga om
symbolens ABI utkas med bibehllen baktkompatibilitet. Det r den
ansvarigas ansvar att hlla dessa filer jourfrda och korrekta, men
dpkg-gensymbols kan hjlpa till.
Nr den genererade symbolfilen skiljer sig mot den version som
tillhandahllits av de paketansvariga kommer dpkg-gensymbols att skriva
ut en differens mellan de tv versionerna. Om ndringarna r fr stora
kommer programmet dessutom att misslyckas (du kan justera hur stora
ndringar du kan tolerera, se flaggan -c).
UNDERHLLA SYMBOLFILER
Symbolfilerna r bara riktigt nyttiga om de motsvarar hur paketet har
utvecklats ver flera versioner. De paketansvariga mste drfr uppdatera
dem varje gng en ny symbol lggs till s att dess associerade minimala
version motsvarar verkligheten. Fr att gra detta p ett riktigt stt
finns det differensfiler i byggloggarna. I de flesta fall kan
differensfilen appliceras direkt p filen debian/paket. Med det i tanke
s behvs det oftast ytterligare justeringar: det rekommenderas att
skippa Debianrevisionen frn det minimala versionsnummer s att den
baktanpassningar med ett lgre versionsnummer, men frn samma
uppstrmsversion, fortfarande uppfyller de genererade beroendena. Om
Debianrevisionen inte kan tas bort p grund av att en symbol faktiskt
lades till av en Debianspecifik ndring s br ett "~" lggs till i slutet
av versionen.
Innan man applicerar en patch p symbolfilen br de ansvariga
dubbelchecka att den r korrekt. Publicerade symboler br inte frsvinna,
s patchen br ideellt sett bara lgga till nya rader.
Anvnda #PACKAGE#-substituering
I ngra sllsynta fall skiljer sig namnet p biblioteket mellan
arkitekturer. Fr att undvika att hrdkoda namnet p paketet i symbolfilen
kan du anvnda markren #PACKAGE#. Den erstts av det faktiska paketnamnet
nr symbolfilen installeras. Till skillnad frn #MINVER#-markren kommer
#PACKAGE# aldrig att dyka upp i en symbolfil i ett binrpaket.
Anvnda symboltaggar
Symboltaggning r nyttigt fr att markera symboler som r speciella p ngot
stt. 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
frsts av dpkg-gensymbols och som utlser specialhantering av symbolerna.
Se undersymbolen Standardsymboltaggar fr mer information om dessa
taggar.
Taggarna anges precis fre symbolnamnet (inga blanksteg tillts mellan).
Den brjar alltid med en vnsterparentes (, slutar med en hgerparentes ),
och mste innehlla minst en tagg. Ytterligare taggar avdelas med tecknet
|. En tagg kan ha ett vrde, vilket separeras frn taggnamnet med tecknet
=. Taggnamn och vrden kan vara godtyckliga strngar, frutom att de inte
kan innehlla de speciella tecknen ) | =. Symbolnamn som fljer en
taggangivelse kan, om s nskas, citeras med antingen ' eller " fr att
tillta blanksteg. Om inga taggar anges fr symbolen tolkas dock
citattecken som en del av symbolnamnet, vilket fortstter till det frsta
blanksteget.
(tag1=jag r markerad|taggnamn med blanksteg)"taggad citerad
symbol"@Bas 1.0
(optional)taggad_ociterad_symbol@Bas 1.0 1
ociterad_symbol@Bas 1.0
Den frsta symbolen i exemplet r heter taggad citerad symbol och har tv
taggar: tag1 med vrdet jag r markerad och taggnamn med blanksteg som
inte har ngot vrde. 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 utkning av formatet i deb-symbols(5) kan de
bara anvndas i symbolfiler i kllkodspaket (dessa filer r att anse som
mallar som anvnds fr att bygga symbolfilerna som finns i binrpaketen).
Nr 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 frn utdata. I mall-lge (-t) kommer dremot alla
symboler och deras taggar (bde standard och oknda) att behllas i utdata
och skrivas i sin originalform s som de lstes in.
Standardsymboltaggar
optional
En symbol markerad som valfri (optional) kan frsvinna frn
bibliotektet nr som helst och kommer aldrig gra s att
dpkg-gensymbols misslyckas. Frsvunna symboler kommer dock
fortfarande visas som saknade (MISSING) i differensen fr varje
ny paketversion. Detta beteende fungerar som en pminnelse fr de
paketansvariga om att symbolen mste tas bort frn symbolfilen
eller lggas tillbaka till biblioteket. Nr en valfri symbol som
tidigare markerats som saknad (MISSING) pltsligt dyker upp igen
i en senare version kommer den att uppgraderas tillbaka till
befintligstatus ("existing") med den minsta tillgngliga
versionen ofrndrad.
Taggen r anvndbar fr symboler som r privata och vars frsvinnande
inte gr att ABI:et gr snder. De flesta C++-mallinstansieringar
faller till exempel in under denna kategori. Som andra taggar
kan den hr ven ha ett godtyckligt vrde: det kan anvndas fr att
indikera varfr symbolen r att anse som valfri.
arch=arkitekturlista
Denna tag gr det mjligt att begrnsa vilken uppsttning
arkitekturer symbolen r tnkt att finnas fr. Nr symbollistan
uppdateras med symboler som upptcks i biblioteket behandlas alla
arkitekturspecifika symboler som inte gller den aktuella
vrdarkitekturen som om de inte fanns. Om en arkitekturspecifik
symbol som motsvarar den aktuella vrdarkitekturen inte existerar
i biblioteket gller de vanliga reglerna fr saknade symboler, och
kan f dpkg-gensymbols att misslyckas. andra sidan, om en
arkitekturspecifik symbol hittas dr den inte var menad att
finnas (d den aktuella vrdarkitekturen inte r listad i taggen),
grs den arkitekturneutral (dvs. "arch"-taggen 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-lget skrivs endast de
arkitekturspecifika symboler som motsvarar den aktuella
vrdarkitekturen till symbolfilen. andra sidan skrivs alla
arkitekturspecifika symboler (inklusive de frn andra
arkitekturer) till symbolfilen i mall-lget.
Formatet p arkitekturlista r detsamma som det som anvnds i
Build-Depends-fltet i debian/control (bortsett frn de omslutande
hakparenteserna []). Den frsta symbolen frn listan nedan, till
exempel, kommer endast att tas med p arkitekturerna alpha,
amd64, kfreebsd-amd64 och ia64, medan den andra tas med verallt
frutom p armel.
(arch=alpha amd64 kfreebsd-amd64
ia64)en_64bit-specifik_symbol@Base 1.0
(arch=!armel)symbol_armel_inte_har@Base 1.0
ignore-blacklist
dpkg-gensymbols har en intern svartlista ver symboler som inte
skall frekomma i symbolfiler eftersom de oftast bara r
sidoeffekter frn implementationsdetaljer i verktygskedjan. Om
du, av ngon orsak, verkligen vill att en av dessa symboler skall
tas med i symbolfilen mste du tagga symbolen med
ignore-blacklist. Det kan vara ndvndigt fr
lgniv-verktygskedjebibliotek som libgcc.
c++ Betecknar c++-symbolmnster. Se stycket Anvnda symbolmnster
nedan.
symver Anger symver (symbolversion)-symbolmnstret. Se stycket Anvnda
symbolmnster nedan.
regex Anger regex-symbolmnstret. Se stycket Anvnda symbolmnster nedan.
Anvnda symbolmnster
Till skillnad frn vanliga symbolspecifikationer kan ett mnster tcka
flera faktiska symboler frn biblioteket. dpkg-gensymbols kommer frska
matcha varje mnster mot varje faktisk symbol som inte har en
motsvarande specifik symbol definierad i symbolfilen. S fort det frsta
mnster som motsvarar symbolen hittas kommer alla dess taggar och
egenskaper att anvndas som en basspecifikation fr symbolen. Om inget
mnster motsvarar symbolen kommer den att tolkas som ny.
Ett mnster anses som tappat om det inte motsvarar ngra symboler i
biblioteket. Som standard kommer detta f dpkg-genchanges att misslyckas
om -c1 eller hgre anges. Om ett sdant misslyckande inte r nskvrt kan
mnstret dock mrkas med taggen optional. Om mnstret d inte motsvarar
ngonting kommer det bara dyka upp i differensen som saknas (MISSING).
Mnstret kan dessutom, precis som andra symboler, begrnsas till
specifika arkitekturer med hjlp av arch-taggen. Se stycket
Standardsymboltaggar ovan fr mer information.
Mnster r en utkning av deb-symbols(5)-formatet och r drfr endast
tilltna i symbolfilmallar. Syntax fr angivelse av mnster skiljer sig
inte frn den fr en specifik symbol. Symbolnamnsdelen av specifikationen
fungerar dock som ett uttryck som skall jmfras mot namn@version fr den
faktiska symbolen. Fr att skilja mellan olika sorters mnster, taggas
mnster normalt med en speciell tagg.
Fr nrvarande stder dpkg-gensymbols tre grundlggande mnstertyper:
c++
Detta mnster anges med taggen c++. Den matchar enbart C++-symboler
med deras avmanglade symbolnamn (som det skrivs ut av
c++filt(1)-verktyget). Det hr mnstret r vldigt nyttigt fr 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
offsetvrden inbyggda i sina manglade namn. En vanlig instans av
detta fall r en virtuell destruktr som under diamantarv behver en
icke-virtuell "thunk"-symbol. ven om till exempel
ZThn8_N3NSB6ClassDD1Ev@Base p 32-bitarsarkitekturer troligtvis r
_ZThn16_N3NSB6ClassDD1Ev@Base p64-bitarsarkitekturer, s kan de
matchas med ett enda c++-mnster:
libdummy.so.1 libdummy1 #MINVER#
[...]
(c++)"non-virtual thunk to NSB::ClassD::~ClassD()@Base" 1.0
[...]
Det avmanglade namnet ovan kan hmtas genom att utfra fljande
kommando:
$ echo '_ZThn8_N3NSB6ClassDD1Ev@Base' | c++filt
Observera att ven om det manglade namnet per definition r unikt i
biblioteket gller inte detta fr avmanglade namn. Flera distinkta
verkliga symboler kan ha samma avmanglade namn. Det gller till
exempel fr icke-virtuella "thunk"-symboler i konfigurationer med
komplexa arv eller fr de flesta konstruktrer och destruktrer
(eftersom g++ normalt genererar tv symboler fr dem). Eftersom dessa
kollisioner sker p ABI-nivn br de dock inte snka kvaliteten p
symbolfilen.
symver
Detta mnster anges med taggen symver. Vlunderhllna bibliotek har
versionshanterade symboler dr varje version motsvarar
uppstrmsversionen dr symbolen lades till. Om det r fallet kan du
anvnda ett symver-mster fr 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 sistnmnda kommer leda
till ett minsta beroende p libc6 version 2.2 trots att den motsvarar
mnstret "(symver)GLIBC_2.0"-mnstret, eftersom specifika symboler
gller fre mnster.
Observera att ven om den gamla sortens jokerteckenmnster (anges med
"*@version" i symbolnamnfltet) fortfarande stds s rekommenderas de
inte lngre i och med den nya sortens syntax
"(symver|optional)version". Till exempel br "*@GLIBC_2.0 2.0"
skrivas som "(symver|optional)GLIBC_2.0 2.0" om samma beteende
behvs.
regex
Mnster med reguljra uttryck anges med taggen regex. De matchar med
det reguljra uttrycket p perl-form som anges i symbolnamnsfltet. Ett
reguljrt uttryck matchar som det str, glm drfr inte att inleda det
med tecknet ^, annars kommer det matcha godtycklig del av den
verkliga symbolens namn@version-strng. 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 trffas av det frsta mnstret medan
t.ex "ng_mystack_new@Base" inte gr det. Det andra mnstret motsvarar
alla symbolen som innehller strngen "private" i sina namn och trffar
kommer att rva optional-taggen frn mnstret.
Grundlggande mnster som anges ovan kan kombineras dr det r vettigt. I s
fall behandlas de i den ordning taggarna anges. Till exempel kommer bde
(c++|regex)"^NSA::ClassA::Private::privmethod\d\(int\)@Base" 1.0
(regex|c++)N3NSA6ClassA7Private11privmethod\dEi@Base 1.0
att trffa symbolerna "_ZN3NSA6ClassA7Private11privmethod1Ei@Base" och
"_ZN3NSA6ClassA7Private11privmethod2Ei@Base". Nr det frsta mnstret
jmfrs avmanglas frst symbolen som en C++-symbol, varefter det
avmanglade namnet jmfrs med det reguljra uttrycket. Nr det andra
mnstret jmfrs,
andra sidan, jmfrs det reguljra uttrycket mot det ra symbolnamnet,
varefter symbolen testas fr att se om det r av C++-typ genom att frska
avmangla det. Om ett grundlggande mnster misslyckas kommer hela
uttrycket att misslyckas. Drfr kommer, till exempel
"__N3NSA6ClassA7Private11privmethod\dEi@Base" inte att trffas av ngot
av mnstrena eftersom det inte r en giltig C++-symbol.
I allmnhet delas alla mnster in i tv grupper. alias (grundlggande c++
och symver) och generella mnster (regex, samtliga kombinationer av
multipla grundlggande mnster). Det gr snabbt att trffa grundlggande
aliasbaserade mnster (O(1)) medan generella mnster r O(N) (N - antal
generella mnster) fr varje symbol. Det rekommenderas drfr inte att
anvnda fr mnga generella mnster.
Nr flera mnster trffar samma verkliga symbol fredras alias (frst c++,
sedan symver) framfr generella mnster. Generella mnster trffas i den
ordning de upptcktes i symbolfilmallen fram till den frsta lyckade
trffen. Observera dock att manuell omsortering av poster i mallfilen
inte rekommenderas d dpkg-gensymbols genererar differensfiler baserad p
den alfanumeriska sorteringsordningen av dess namn.
Anvnda inkluderingar
Nr uppsttningen av exporterade symboler skiljer sig mellan arkitekturer
kan det vara ineffektivt att anvnda en enda symbolfil. I dessa fall kan
ett inkluderingsdirektiv vara nyttigt p flera stt:
o Du kan faktorisera de gemensamma delarna i en extern fil och
inkludera den filen i din paket.symbols.arkitektur-fil genom att
anvnda ett inkluderingsdirektiv som detta:
#include "paket.symbols.common"
o Inkluderingsdirektivet kan ven taggas som alla andra symboler:
(tag|..|tagN)#include "fil_att_inkludera"
Alla symboler som inkluderas frn fil_att_inkludera kommer att anses
som standard vara taggade med tag .. tagN. Du kan anvnda denna
funktion fr 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 lses radvis, och inkluderingsdirektiv utfrs s fort de
upptcks. Det betyder att innehllet i den inkluderade filen kan verstyra
allt innehll som frekom fre inkluderingsdirektivet och att innehll
efter direktivet kan verstyra allt frn den inkluderade filen. Alla
symboler (ven andra #include-direktiv) i den inkluderade filen kan ange
ytterligare taggar eller verstyra vrden fr de rvda taggarna i sin
taggspecifikation. Det finns dock inte ngot stt fr en symbol att ta
bort ngon av sina rvda taggar.
En inkluderad fil kan repetera huvudraden som innehller SONAMNet fr
biblioteket. I s fall verstyr den en eventuell huvudrad som lsts in
tidigare. Det r vanligtvis dock bst att undvika att duplicera
huvudrader. Ett stt att gra det r som fljer:
#include "libngonting1.symbols.common"
arkitekturspecifik_symbol@Base 1.0
God hantering av bibliotek
Ett vlunderhllet bibliotek har fljande funktioner:
o dess API r stabilt (publika symboler tas aldrig bort, endast nya
publika symboler lggs till) och inkompatibla ndringar grs endast nr
SONAMNet ndras;
o ideellt anvnder det en versionhanterade symboler fr att upprtthlla
ABI-stabilitet trots interna ndringar och API-utkningar;
o det exporterar inte privata symboler (sdana symboler kan taggas med
"optional" fr att g runt detta).
Nr man underhller symbolfilen r det ltt att upptcka symboler som dyker
upp och frsvinner. Det r svrare att upptcka inkompatibla API- och
ABI-ndringar. Den paketansvarige br drfr noggrant lsa igenom
uppstrmsndringsloggen fr fall d reglerna fr god hantering av bibliotek
bryts. Om ett mjligt fel upptcks br uppstrmsfrfattaren meddelas, d det
alltid r bttre att problemet rttas uppstrms n specifikt i Debian.
FLAGGOR
-Ppaketbyggkatalog
Sk paketbyggkatalog istllet fr debian/tmp.
-ppaket
Definiera paketnamnet. Krvs om mer n ett binrpaket listas i
debian/control (eller om det inte finns ngon
debian/control-fil).
-vversion
Definiera paketversion. Standardvrdet r versionen som hmtas frn
debian/changelog. Krvs om programmet anropas utanfr ett
kllkodspakettrd.
-ebiblioteksfil
Analyserar endast bibliotek som listats explicit istllet fr att
hitta alla publika bibliotek. Du kan anvnda ett reguljrt uttryck
i biblioteksfil fr att trffa multipla bibliotek med ett enda
argument (annars behver du flera -e).
-Ifilnamn
Anvnd filnamn som referensfil fr att generera symbolfilen som
integreras i sjlva paketet.
-O Skriv den genererade symbolfilen p standard ut, i stllet fr att
lagra den i paketets byggtrd.
-Ofilnamn
Lagra den genererade symbolfilen som filnamn. Om filnamn redan
existerar kommer dess innehll att anvndas som bas fr den
genererade symbolfilen. Du kan anvnda den hr funktionen fr att
uppdatera en symbolfil s att den motsvarar en nyare
uppstrmsversion av ditt bibliotek.
-t Skriv symbolfilen i mall-lge istllet fr i formatet kompatibelt
med deb-symbols(5). Huvudskillnaden r att symbolnamn och taggar
skrivs i sin originalform i mall-lget, till skillnad frn de
efterbehandlade symbolnamnen med borttagna taggar som skrivs i
det kompatibla lget. Dessutom kan vissa symboler uteslutas nr en
vanlig deb-symbols(5)-fil skrivs (i enlighet med
tagghanteringsreglerna) medan alla symboler alltid skrivs till
symbolfilsmallen.
-c[0-4]
Definiera vilka kontroller som skall utfras nr den genererade
symbolfilen jmfrs med den mallfil som anvnds som startpunkt. Som
standard r nivn 1. Genom att ka nivn utfrs flera kontroller,
inklusive alla kontroller p lgre niv. Niv 2 misslyckas om nya
symboler har introducerats. Niv 3 misslyckas om ngra bibliotek
har frsvunnit. Niv 4 misslyckas om ngra bibliotek har
introducerats.
Vrdet kan verstyras med miljvariabeln
DPKG_GENSYMBOLS_CHECK_LEVEL.
-q Hll tyst och generera aldrig en differens mellan den genererade
symbolfilen och mallfilen som anvndes som startpunkt eller visa
varningar om nya/frlorade bibliotek eller nya/frlorade symboler.
Den hr flaggan tar endast bort informationsutdata, inte sjlva
kontrolleran (se flaggan -c).
-aarkitektur
Anta arkitektur som vrdarkitektur vid hantering av symbolfiler.
Anvnd den hr flaggan fr att generera en symbolfil eller
differens fr valfri arkitektur s lnge dess binrer r tillgngliga.
-d Aktiverar felskningslge. Flera meddelanden visas fr att frklara
vad dpkg-gensymbols gr.
-V Aktivera pratsamt lge. Den genererade symbolfilen innehller ej
lngre rekommenderade symboler som kommentarer. I mall-lge fljs
dessutom mnstersymboler av kommentarer som visar vilka verkliga
symboler som har trffats av mnstret.
-h, --help
Visar hjlpskrm och avslutar.
--version
Visar version och avslutar.
SE VEN
http://people.redhat.com/drepper/symbol-versioning
http://people.redhat.com/drepper/goodpractice.pdf
http://people.redhat.com/drepper/dsohowto.pdf
deb-symbols(5), dpkg-shlibdeps(1).
FRFATTARE
Upphovsrttsskyddat 2007-2009 Raphal Hertzog
Detta r fri programvara; se GNU General Public License version 2 eller
senare fr kopieringsvillkor. Det finns INGEN GARANTI.
VERSTTNING
Peter Krefting och Daniel Nylander.