Provided by: dpkg-dev_1.17.5ubuntu5.8_all 
NAMN
dpkg-gensymbols - generera symbolfiler (information om delade bibliotek)
SYNOPS
dpkg-gensymbols [flagga...]
BESKRIVNING
dpkg-gensymbols söker genom en temporärt byggträd (som standard debian/tmp) efter
bibliotek och skapar en symbols-fil som beskriver dem. Denna fil kommer sedan, såvida den
inte är tom, att installeras i DEBIAN-underkatalogen i byggträdet så att den hamnar i
styrinformationen i paketet.
När dessa filer skapas, används ett par symbolfiler från paketansvariga som indata.
Programmet söker efter följande filer (och använder den första det finner):
• debian/paket.symbols.arkitektur
• debian/symbols.arkitektur
• debian/paket.symbols
• debian/symbols
The main interest of those files is to provide the minimal version associated to each
symbol provided by the libraries. Usually it corresponds to the first version of that
package that provided the symbol, but it can be manually incremented by the maintainer if
the ABI of the symbol is extended without breaking backwards compatibility. It's the
responsibility of the maintainer to keep those files up-to-date and accurate, but
dpkg-gensymbols helps with that.
När den genererade symbolfilen skiljer sig mot den version som tillhandahållits av de
paketansvariga kommer dpkg-gensymbols att skriva ut en differens mellan de två
versionerna. Om ändringarna är för stora kommer programmet dessutom att misslyckas (du kan
justera hur stora ändringar du kan tolerera, se flaggan -c).
UNDERHÅLLA SYMBOLFILER
The symbols files are really useful only if they reflect the evolution of the package
through several releases. Thus the maintainer has to update them every time that a new
symbol is added so that its associated minimal version matches reality. To do this
properly the diffs contained in the build logs can be used. In most cases, the diff
applies directly to the debian/package.symbols file. That said, further tweaks are usually
needed: it's recommended for example to drop the Debian revision from the minimal version
so that backports with a lower version number but the same upstream version still satisfy
the generated dependencies. If the Debian revision can't be dropped because the symbol
really got added by the Debian specific change, then one should suffix the version with
"~".
Innan man applicerar en patch på symbolfilen bör de ansvariga dubbelchecka att den är
korrekt. Publicerade symboler bör inte försvinna, så patchen bör ideellt sett bara lägga
till nya rader.
Obsevera att du kan skriva kommentarer i symbols-filer: 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"@Bas 1.0
(optional)taggad_ociterad_symbol@Bas 1.0 1
ociterad_symbol@Bas 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.
Since symbol tags are an extension of the deb-symbols(5) format, they can only be part of
the symbols files used in source packages (those files should then be seen as templates
used to build the symbols files that are embedded in binary packages). When
dpkg-gensymbols is called without the -t option, it will output symbols files compatible
to the deb-symbols(5) format: it fully processes symbols according to the requirements of
their standard tags and strips all tags from the output. On the contrary, in template mode
(-t) all symbols and their tags (both standard and unknown ones) are kept in the output
and are written in their original form as they were loaded.
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
Denna tag gör det möjligt att begränsa vilken uppsättning arkitekturer symbolen är
tänkt att finnas för. 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), görs 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-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 alpha, any-amd64 and
ia64 architectures, the second only on linux architectures, while the third one
anywhere except on armel.
(arch=alpha any-amd64 ia64)a_64bit_specific_symbol@Base 1.0
(arch=linux-any)linux_specific_symbol@Base 1.0
(arch=!armel)symbol_armel_does_not_have@Base 1.0
ignore-blacklist
dpkg-gensymbols har en intern svartlista över symboler som inte skall förekomma i
symbolfiler eftersom de oftast bara är sidoeffekter från implementationsdetaljer i
verktygskedjan. Om du, av någon orsak, verkligen vill att en av dessa symboler
skall tas med i symbolfilen måste du tagga symbolen med ignore-blacklist. Det kan
vara nödvändigt för lågnivå-verktygskedjebibliotek som libgcc.
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. Please
refer to 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. In order 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
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 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 "paket.symbols.common"
• Inkluderingsdirektivet kan även taggas som alla andra symboler:
(tag|...|tagN)#include "fil-att-inkludera"
Alla symboler som inkluderas från fil-att-inkludera kommer att anses som standard vara
taggade med tag ... tagN. 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 SONAMNet 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
God hantering av bibliotek
Ett välunderhållet bibliotek har följande funktioner:
• dess API är stabilt (publika symboler tas aldrig bort, endast nya publika symboler
läggs till) och inkompatibla ändringar görs endast när SONAMNet ändras;
• ideellt använder det en versionhanterade symboler för att upprätthålla ABI-stabilitet
trots interna ändringar och API-utökningar;
• det exporterar inte privata symboler (sådana symboler kan taggas med "optional" för
att gå runt detta).
När man underhåller symbolfilen är det lätt att upptäcka symboler som dyker upp och
försvinner. Det är svårare att upptäcka inkompatibla API- och ABI-ändringar. Den
paketansvarige bör därför noggrant läsa igenom uppströmsändringsloggen för fall då
reglerna för god hantering av bibliotek bryts. Om ett möjligt fel upptäcks bör
uppströmsförfattaren meddelas, då det alltid är bättre att problemet rättas uppströms än
specifikt i Debian.
FLAGGOR
-Ppaketbyggkatalog
Sök paketbyggkatalog istället för debian/tmp.
-ppaket
Definiera paketnamnet. Krävs om mer än ett binärpaket listas i debian/control
(eller om det inte finns någon debian/control-fil).
-vversion
Definiera paketversion. Standardvärdet är versionen som hämtas från
debian/changelog. Krävs om programmet anropas utanför ett källkodspaketträd.
-ebiblioteksfil
Only analyze libraries explicitly listed instead of finding all public libraries.
You can use shell patterns used for pathname expansions (see the File::Glob(3perl)
manual page for details) in library-file to match multiple libraries with a single
argument (otherwise you need multiple -e).
-Ifilnamn
Använd filnamn som referensfil för att generera symbolfilen som integreras i själva
paketet.
-O[filename]
Print the generated symbols file to standard output or to filename if specified,
rather than to debian/tmp/DEBIAN/symbols (or package-build-dir/DEBIAN/symbols if -P
was used). If filename is pre-existing, its contents are used as basis for the
generated symbols file. You can use this feature to update a symbols file so that
it matches a newer upstream version of your library.
-t Write the symbol file in template mode rather than the format compatible with
deb-symbols(5). The main difference is that in the template mode symbol names and
tags are written in their original form contrary to the post-processed symbol names
with tags stripped in the compatibility mode. Moreover, some symbols might be
omitted when writing a standard deb-symbols(5) file (according to the tag
processing rules) while all symbols are always written to the symbol file template.
-c[0-4]
Definiera vilka kontroller som skall utföras när den genererade symbolfilen jämförs
med den mallfil som används som startpunkt. Som standard är nivån 1. Genom att öka
nivån utförs flera kontroller, inklusive alla kontroller på lägre nivå. Nivå 2
misslyckas om nya symboler har introducerats. Nivå 3 misslyckas om några bibliotek
har försvunnit. Nivå 4 misslyckas om några bibliotek har introducerats.
This value can be overridden by the environment variable
DPKG_GENSYMBOLS_CHECK_LEVEL.
-q Keep quiet and never generate a diff between generated symbols file and the
template file used as starting point or show any warnings about new/lost libraries
or new/lost symbols. This option only disables informational output but not the
checks themselves (see -c option).
-aarkitektur
Anta arkitektur som värdarkitektur vid hantering av symbolfiler. Använd den här
flaggan för att generera en symbolfil eller differens för valfri arkitektur så
länge dess binärer är tillgängliga.
-d Aktiverar felsökningsläge. Flera meddelanden visas för att förklara vad
dpkg-gensymbols gör.
-V Aktivera pratsamt läge. Den genererade symbolfilen innehåller ej längre
rekommenderade symboler som kommentarer. I mall-läge följs dessutom mönstersymboler
av kommentarer som visar vilka verkliga symboler som har träffats av mönstret.
-?, --help
Visar hjälpskärm och avslutar.
--version
Visar version och avslutar.
SE ÄVEN
https://people.redhat.com/drepper/symbol-versioning
https://people.redhat.com/drepper/goodpractice.pdf
https://people.redhat.com/drepper/dsohowto.pdf
deb-symbols(5), dpkg-shlibdeps(1).
ÖVERSÄTTNING
Peter Krefting och Daniel Nylander.