dpkg-gensymbols(1) | dpkg suite | dpkg-gensymbols(1) |
dpkg-gensymbols - symboolbestanden genereren (informatie over afhankelijkheidsrelaties met gedeelde bibliotheken)
dpkg-gensymbols [optie...]
dpkg-gensymbols doorzoekt een tijdelijke bouwboom (standaard is dat debian/tmp) op zoek naar bibliotheken en genereert een symbols-bestand dat ze beschrijft. Dit bestand wordt dan als het niet leeg is, geïnstalleerd in een onderliggende map van de bouwboom met de naam DEBIAN, zodat het uiteindelijk opgenomen geraakt in de controle-informatie van het pakket.
Bij het genereren van deze bestanden gebruikt het als invoer bepaalde symboolbestanden die door de onderhouder aangeleverd worden. Het zoekt naar de volgende bestanden (en gebruikt het eerste dat gevonden wordt):
Het hoofddoel van deze bestanden is aan te geven welke de minimale versie is die behoort bij elk van de symbolen die door de bibliotheken aangeleverd worden. Gewoonlijk komt dit overeen met de eerste versie van het pakket dat in dat symbool voorzag, maar dit kan door de onderhouder manueel verhoogd worden indien de ABI van het symbool uitgebreid werd zonder dat daardoor de neerwaartse compatibiliteit verbroken wordt. Het is de verantwoordelijkheid van de onderhouder om deze bestanden up-to-date en accuraat te houden, maar dpkg-gensymbols helpt hierbij.
Indien het gegenereerde symboolbestand verschilt van datgene wat de onderhouder aanlevert, zal dpkg-gensymbols de verschillen tussen de twee versies tonen in diff-formaat. Bovendien kan dit zelfs tot een mislukking leiden als de verschillen te significant zijn (u kunt aanpassen hoeveel verschil u kunt tolereren; zie de optie -c).
De basisuitwisselingsindeling van het symboolbestand wordt beschreven in deb-symbols(5), hetgeen gebruikt wordt door de symboolbestanden uit de binaire pakketten. Deze worden gegenereerd uit sjabloonsymboolbestanden met een indeling gebaseerd op het eerste, beschreven in deb-src-symbols(5) en opgenomen in broncodepakketten.
De symboolbestanden zijn pas echt nuttig als ze de evolutie van het pakket reflecteren doorheen verschillende releases. De onderhouder moet ze dus iedere keer bijwerken wanneer een nieuw symbool toegevoegd wordt, zodat de minimale versie die eraan gekoppeld wordt, overeenkomt met de realiteit.
De diffs (weergave van de verschillen) die in de bouwlogs te vinden zijn, kunnen als startpunt genomen worden, maar daarbovenop moet de onderhouder erop letten dat het gedrag van deze symbolen niet zodanig veranderd werd, dat iets dat van deze symbolen gebruik maakt en linkt met de nieuwe versie, niet stopt met werken met de oude versie.
In de meeste gevallen kan de diff rechtstreeks toegepast worden op het bestand debian/pakket.symbols. Dit gezegd zijnde, zijn verdere aanpassingen meestal wel nodig: het wordt bijvoorbeeld aanbevolen om het Debian revisienummer weg te laten uit de minimale versie, zodat backports (nieuwere programmaversies die geschikt gemaakt worden voor een vroegere release) met een lager versienummer maar eenzelfde bovenstroomse versie nog steeds voldoen aan de gegenereerde afhankelijkheidsrelaties. Indien het Debian revisienummer niet weggelaten kan worden omdat het symbool echt via een Debian-specifieke aanpassing toegevoegd werd, moet men aan het versienummer het achtervoegsel ‘~’ toevoegen.
Vooraleer een patch toe te passen op een symboolbestand, moet de onderhouder grondig controleren of dat wel correct is. Publieke symbolen worden verondersteld niet te verdwijnen. Een patch zou dus idealiter enkel nieuwe regels mogen toevoegen.
Merk op dat u in symboolbestanden commentaar kunt invoegen.
Vergeet niet na te gaan of oudere symboolversies niet verhoogd moeten worden. Er bestaat geen manier voor dpkg-gensymbols om in dit verband waarschuwingen te geven. Een diff (weergave van de verschillen) blindweg toepassen of ervan uitgaan dat er niets aangepast moet worden als er geen diff is zonder zelf op eventuele wijzigingen te controleren, kan leiden tot pakketten met verslapte afhankelijkheidsrelaties die onterecht laten veronderstellen dat ze met oudere pakketten kunnen samenwerken. Dit kan bij (gedeeltelijke) opwaarderingen leiden tot moeilijk te vinden bugs.
Een goed onderhouden bibliotheek heeft de volgende functionaliteit:
Bij het onderhoud van een symboolbestand is het gemakkelijk om het verschijnen en verdwijnen van symbolen op te merken. Maar het is moeilijker om incompatibele API- en ABI-wijzigingen op te merken. Daarom moet de onderhouder het changelog-bestand van de toeleveraar grondig nakijken op situaties waarbij de regels van goed bibliotheekbeheer geschonden worden. Indien mogelijke problemen ontdekt worden, zou de toeleverende auteur erover ingelicht moeten worden, aangezien een reparatie op het niveau van de toeleveraar altijd te verkiezen valt boven een Debian-specifieke tijdelijke oplossing.
Opmerking: gebruik deze optie in de plaats van het instellen van LD_LIBRARY_PATH, aangezien die omgevingsvariabele gebruikt wordt om de runtime linker aan te sturen. Daarvan misbruik maken om de paden van gedeelde bibliotheken in te stellen tijdens het bouwen van het programma, kan problematisch zijn, bijvoorbeeld bij het cross-compileren.
Deze waarde kan vervangen worden door de omgevingsvariabele DPKG_GENSYMBOLS_CHECK_LEVEL.
<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).
2023-05-11 | 1.21.22 |