dpkg-gensymbols(1)

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

Dessa filer är i huvudsak intressanta för att kunna tillhandahålla den minimala version associerad med varje symbol i biblioteken. Detta motsvarar normalt den första version av paketet som tillhandahöll symbolen, men det kan manuellt inkrementeras av de ansvariga om symbolens ABI utökas med bibehållen bakåtkompatibilitet. Det är den ansvarigas ansvar att hålla dessa filer àjourförda och korrekta, men dpkg-gensymbols kan hjälpa till med detta.

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 base interchange format of the symbols file is described in deb-symbols(5), which is used by the symbols files included in binary packages. These are generated from template symbols files with a format based on the former, described in deb-src-symbols(5) and included in source packages.

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.

The diffs contained in the build logs can be used as a starting point, but the maintainer, additionally, has to make sure that the behaviour of those symbols has not changed in a way that would make anything using those symbols and linking against the new version, stop working with the old version.

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.

Note that you can put comments in symbols files.

Glöm inte att kontrollera om de gamla symbolversionerna måste ökas. Det finns inget sätt för dpkg-gensymbols att varna om detta. Att blint applicera diffen eller utgå från att inget har ändrats om diffen är tom, utan att se efter sådana ändringar, kan leda till att paket med lösa beroenden kan deklarera att de fungerar med äldre paket de inte kan fungera tillsammans med. Detta kommer introducera svårfunna problem vid (delvisa) uppgraderingar.{

  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
    Analyserar endast bibliotek som listats explicit istället för att hitta alla publika bibliotek. Du kan använda ett jokertecken för filnamn (se manualsidan File::Glob(3perl) för detaljer) i biblioteksfil för att träffa multipla bibliotek med ett enda argument (annars behöver du flera -e).

-lkatalog
    Prepend directory to the list of directories to search for private shared libraries (since dpkg 1.19.1). This option can be used multiple times. Observera: Använd den här flaggan istället för att sätta LD_LIBRARY_PATH, eftersom miljövariabeln används för att styra körtidslänkaren, och genom att utnyttja det för att ange sökvägen till delade bibliotek vid kompilering kan det uppstå problem, till exempel vid korskompilering.

-Ifilnamn
    Använd filnamn som referensfil för att generera symbolfilen som integreras i själva paketet.

-O[filnamn]
    Visa den genererade symbolfilen på standard ut eller spara som filnamn om det anges, istället för debian/tmp/DEBIAN/symbols (eller paketbyggkatalog/DEBIAN/symbols om -P användes). Om filnamn redan existerar kommer dess innehåll att användas som bas för den genererade symbolfilen. Du kan använda den här funktionen för att uppdatera en symbolfil så att den motsvarar en nyare uppströmsversion av ditt bibliotek.

-t  Skriv symbolfilen i mall-läge istället för i formatet kompatibelt med deb-symbols(5). Huvudskillnaden är att symbolnamn och taggar skrivs i sin originalform i mall-läget, till skillnad från de efterbehandlade symbolnamnen med borttagna taggar som skrivs i det kompatibla läget. Dessutom kan vissa symboler uteslutas när 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 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. Värdet kan överstyras med miljövariabeln DPKG_GENSYMBOLS_CHECK_LEVEL.

-q  Håll tyst och generera aldrig en differens mellan den genererade symbolfilen och mallfilen som användes som startpunkt eller visa varningar om nya/förlorade bibliotek eller nya/förlorade symboler. Den här flaggan tar endast bort informationsutdata, inte själva kontrolleran (se flaggan -c).

-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.

MILJÖVARIABLER

DPKG_GENSYMBOLS_CHECK_LEVEL
    Overrides the command check level, even if the -c command-line argument was given (note that this goes against the common convention of command-line arguments having precedence over environment variables).

DPKG_COLORS
    Sets the color mode (since dpkg 1.18.5). The currently accepted values are: auto (default), always and never.

DPKG_NLS
    If set, it will be used to decide whether to activate Native Language Support, also known as internationalization (or i18n) support (since dpkg 1.19.0). The accepted values are: 0 and 1 (default).

SE ÄVEN
https://people.redhat.com/drepper/symbol-versioning
https://people.redhat.com/drepper/goodpractice.pdf
https://people.redhat.com/drepper/dsohowto.pdf
deb-src-symbol(5), deb-symbols(5), dpkg-shlibdeps(1).

ÖVERSÄTTNING
Peter Krefting och Daniel Nylander.