dpkg-source(1) | dpkg suite | dpkg-source(1) |
dpkg-source - gereedschap voor het manipuleren van een Debian broncodepakket (.dsc)
dpkg-source [optie...] commando
dpkg-source pakt Debian broncodearchieven in en uit.
Bij geen enkel van deze commando's is het toegelaten om meerdere opties tot één enkele optie te combineren of de waarde van een optie via een apart argument op te geven.
dpkg-source zal uit het controlebestand de namen van de andere bestanden lezen die samen het broncodepakket vormen. Er wordt van uitgegaan dat ze zich in dezelfde map bevinden als het .dsc-bestand.
De permissies en het eigenaarschap van de bestanden uit het geëxtraheerde pakket zullen zodanig ingesteld worden dat ze beantwoorden aan wat men zou mogen verwachten mochten de bestanden en mappen gewoon aangemaakt zijn - mappen en uitvoerbare bestanden zullen 0777 zijn en gewone bestanden 0666 en beide zullen aangepast worden op basis van het umask van degene die het pakket uitpakt. Indien de bovenliggende map setgid is, zullen de geëxtraheerde mappen dat ook zijn en al de bestanden en mappen zullen dit groepseigenaarschap overerven.
Indien het broncodepakket een niet-standaardindeling gebruikt (momenteel betekent dit alle indelingen behalve “1.0”), dan zal de naam ervan opgeslagen worden in debian/source/format, zodat standaard deze indeling gebruikt wordt bij de volgende malen dat het broncodepakket gebouwd wordt.
dpkg-source zal het broncodepakket bouwen volgens de eerste indeling die gevonden wordt in de hierna volgende geordende lijst: de indeling opgegeven met de commandoregeloptie --format, de indeling aangegeven in debian/source/format, “1.0”. Het terugvallen op “1.0” word afgeschaft en zal op een bepaald moment in de toekomst weggelaten worden. U zou de gewenste broncode-indeling steeds moeten documenteren in debian/source/format. Zie het onderdeel INDELINGEN VAN BRONCODEPAKKETTEN voor een uitgebreide beschrijving van de verschillende indelingen voor broncodepakketten.
De optie -i zelf schakelt deze instelling in met een standaard reguliere expressie (met behoud van eventuele wijzigingen aan de standaard reguliere expressie onder invloed van een eerder gebruikt --extend-diff-ignore) die zorgt voor het uitfilteren van controlebestanden en -mappen van de meest courante versiebeheersystemen, van back-upbestanden en wisselbestanden en van bouwuitvoermappen van Libtool. Er kan slechts één reguliere expressie actief zijn. Van meerdere -i-opties zal enkel de laatste uitwerking hebben.
Dit is erg bruikbaar voor het wegknippen van vreemde bestanden die mee opgenomen geraken in de diff, bijvoorbeeld als u de broncode onderhoudt in een versiebeheersysteem en een werkkopie (checkout) wilt gebruiken om een broncodepakket te bouwen, zonder dat daarin ook de extra bestanden en mappen die ze meestal bevat (bijvoorbeeld CVS/, .cvsignore, .svn/), mee opgenomen worden. De standaard reguliere expressie is reeds zeer exhaustief, maar indien u ze moet vervangen, moet u ermee rekening houden dat ze standaard een overeenkomst kan opleveren met elk onderdeel van een pad. Indien u dus een overeenkomst zoekt met het begin van een bestandsnaam of enkel met volledige bestandsnamen, zult u zelf de nodige ankers (bijvoorbeeld ‘(^|/)’, ‘($|/)’) moeten opgeven.
-I zelf voegt standaard --exclude-opties toe die zorgen voor het uitfilteren van controlebestanden en -mappen van de meest courante versiebeheersystemen, van back-upbestanden en wisselbestanden en van bouwuitvoermappen van Libtool.
Opmerking: hoewel zij vergelijkbare bedoelingen hebben, hebben -i en -I een heel verschillende syntaxis en semantiek. -i kan slechts eenmaal opgegeven worden en verwacht een reguliere expressie die perl-compatibel is en die vergeleken wordt met het volledige relatieve pad van elk bestand. -I kan meermaals opgegeven worden en verwacht een bestandsnaampatroon met shell-jokertekens. Het patroon wordt toegepast op het volledige relatieve pad maar ook op elk individueel onderdeel van het pad. De exacte semantiek van de optie --exclude van tar is enigszins gecompliceerd. Zie voor een volledige documentatie <https://www.gnu.org/software/tar/manual/tar.html#wildcards>.
De standaard reguliere expressies en patronen voor beide opties zijn te zien in de uitvoer van het commando --help.
Indien u niet weet welke indeling te kiezen voor de broncode, zou u wellicht ofwel “3.0 (quilt)” of “3.0 (native)” moeten kiezen. Zie <https://wiki.debian.org/Projects/DebSrc3.0> voor informatie over het in gebruik nemen van deze indelingen binnen Debian.
Een broncodepakket volgens deze indeling bestaat ofwel uit een .orig.tar.gz gekoppeld aan een .diff.gz of één enkele .tar.gz (in dat geval wordt van het pakket gezegd dat het native (eigen - van oorsprong van Debian) is). Optioneel mag bij het originele tar-archief een afzonderlijke handtekening van de toeleveraar .orig.tar.gz.asc gevoegd zijn. De extractie ervan wordt ondersteund sinds dpkg 1.18.5.
Extracting
Een Debian-eigen (native) pakket extraheren is een eenvoudige extractie van het enige tar-archief in de doelmap. Een niet-eigen pakket extraheren bestaat erin eerst het .orig.tar.gz uit te pakken en er dan de patch uit het bestand .diff.gz op toe te passen. Voor alle bestanden waarop een patch toegepast werd, wordt de tijdsaanduiding teruggezet op het tijdstip van extraheren van het broncodepakket (dit vermijdt scheeftrekkingen van de tijdsaanduiding wat tot problemen kan leiden wanneer automatisch gegenereerde bestanden gepatcht worden). Het diff-bestand kan nieuwe bestanden aanmaken (de volledige debian-map wordt op die manier aangemaakt), maar kan geen bestanden verwijderen (lege bestanden blijven achter) en kan geen symbolische koppelingen creëren of wijzigen.
Bouwen
Een Debian-eigen (native) pakket bouwen is gewoon een enkel tar-archief maken met daarin de broncodemap. Een niet-eigen pakket bouwen bestaat uit het extraheren van het originele tar-archief in een aparte map “.orig” en het opnieuw aanmaken van het bestand .diff.gz door de map van het broncodepakket te vergelijken met de .orig-map.
Bouwopties (met --build):
Indien een tweede argument opgegeven wordt dat geen optie is, moet het de naam van de originele broncodemap zijn of van het tar-archief of een lege tekenreeks als het pakket Debian-specifiek is en dus geen diffs bevat in verband met de debianisering. Indien geen tweede argument opgegeven werd, zal dpkg-source zoeken naar het tar-bestand met de originele broncode pakket_toeleveraarsversie.orig.tar.gz of naar de map met de originele broncode map.orig, afhankelijk van de argumenten -sX.
-sa, -sp, -sk, -su en -sr zullen geen bestaande tar-bestanden of -mappen overschrijven. Indien dat wel gewenst wordt, dan moeten in de plaats daarvan -sA, -sP, -sK, -sU en -sR gebruikt worden.
Extractieopties (met --extract):
In alle gevallen zal een eventuele bestaande originele broncodeboom verwijderd worden.
Al de -sX-opties sluiten elkaar wederzijds uit. Indien u er meer dan één opgeeft, dan zal enkel de laatste gebruikt worden.
Extraheren wordt sinds dpkg 1.13.9 ondersteund, bouwen sinds dpkg 1.14.8. Ook gekend als wig&pen. Deze indeling wordt niet aangeraden voor massaal gebruik, de indeling “3.0 (quilt)” vervangt ze. Wig&pen was de eerste specificatie van een broncodepakketindeling van de nieuwe generatie.
Het gedrag van deze indeling is hetzelfde als bij de indeling “3.0 (quilt)”, behalve dat het geen gebruik maakt van een expliciete lijst van patches. Alle bestanden in debian/patches/ die beantwoorden aan de reguliere expressie [\w-]+ moeten geldige patches zijn: zij worden op het moment van extraheren toegepast.
Bij het bouwen van een nieuw broncodepakket worden eventuele wijzigingen aan de broncode van de toeleveraar opgeslagen in een patch met als naam zz_debian-diff-auto.
Wordt ondersteund sinds dpkg 1.14.17. Deze indeling is een uitbreiding van de native pakketindeling, zoals gedefinieerd in de indeling 1.0. Ze ondersteunt alle compressiemethodes en negeert standaard eventuele VCS-specifieke bestanden en mappen (bestanden en mappen die verband houden met het versiebeheersysteem) evenals vele tijdelijke bestanden (zie de uitvoer van de optie --help voor de standaardwaarde van de optie -I).
Wordt ondersteund sinds dpkg 1.14.17. Een broncodepakket volgens deze indeling bevat minstens een origineel tar-archief (.orig.tar.ext waarbij ext gz, bz2, lzma en xz kan zijn) en een debian tar-archief (.debian.tar.ext). Het kan ook bijkomende originele tar-archieven bevatten (.orig-component.tar.ext). component mag enkel alfanumerieke tekens (‘a-zA-Z0-9’) en koppeltekens (‘-’) bevatten. Optioneel mag bij elk origineel tar-archief een afzonderlijke handtekening van de toeleveraar (.orig.tar.ext.asc en .orig-component.tar.ext.asc), gevoegd worden. De extractie ervan wordt ondersteund sinds dpkg 1.17.20 en het bouwen sinds dpkg 1.18.5.
Extracting
Eerst wordt het belangrijkste originele tar-archief uitgepakt en nadien worden alle bijkomende originele tar-archieven uitgepakt in onderliggende mappen die genoemd worden naar het component-gedeelte van hun bestandsnaam (een eventuele reeds bestaande map wordt vervangen). Het debian tar-archief wordt bovenop de broncodemap geëxtraheerd nadat eerst een eventuele reeds bestaande debian-map verwijderd werd. Merk op dat het debian tar-archief een onderliggende map debian moet bevatten, maar dat het ook binaire bestanden kan bevatten buiten die map (zie de optie --include-binaries).
Vervolgens worden alle patches toegepast die vermeld zijn in debian/patches/leverancier.series of debian/patches/series, waarbij leverancier de naam is in kleine letters van de huidige leverancier, of debian als geen leverancier gedefinieerd is. Indien het eerste bestand gebruikt wordt en het laatste niet bestaat (of een symbolische koppeling is), dan zal het laatste vervangen worden door een symbolische koppeling naar het eerste. Dit is bedoeld om het gebruik van quilt bij het beheer van het geheel van patches te vereenvoudigen. Leveranciersspecifieke series-bestanden hebben tot doel het serialiseren van meerdere leveranciersgebonden ontwikkelingstakken op een declaratieve manier mogelijk te maken, wat verkieslijker is boven een open codering van deze aanpak in debian/rules. Dit is in het bijzonder nuttig wanneer de broncode voorwaardelijk gepatched moet worden omdat de betrokken bestanden geen ingebouwde ondersteuning hebben voor conditionele occlusie. Merk nochtans op dat hoewel dpkg-source op correcte wijze de ontleding uitvoert van series-bestanden met expliciete opties die gebruikt worden voor het toepassen van patches (op elke regel opgeslagen na de bestandsnaam van de patch en één of meer spaties), het deze opties negeert en steeds patches verwacht die kunnen toegepast worden met de optie -p1 van patch. Het zal dus een waarschuwing geven als het dergelijke opties tegenkomt en het bouwen zal waarschijnlijk mislukken.
Opmerking: indien leveranciers-series-bestanden gebruikt worden, geeft lintian(1) onvoorwaardelijke waarschuwingen als gevolg van een controversieel Debian-specifiek besluit. Extern gebruik zou hierdoor niet getroffen mogen worden. Om dergelijke waarschuwingen het zwijgen op te leggen kunt u het dpkg-profiel van lintian gebruiken door aan lintian(1) de optie «--profile dpkg» mee te geven.
Voor alle bestanden waarop een patch toegepast werd, wordt de tijdsaanduiding teruggezet op het tijdstip van extraheren van het broncodepakket (dit vermijdt scheeftrekkingen van de tijdsaanduiding hetgeen tot problemen kan leiden wanneer automatisch gegenereerde bestanden gepatcht worden).
In tegenstelling tot het standaardgedrag van quilt wordt verwacht dat patches zonder gedoe toegepast kunnen worden. Indien dat niet het geval is, zou u de patches moeten verversen met quilt, anders zal dpkg-source met een foutmelding afbreken terwijl het probeert ze toe te passen.
Analoog aan het standaardgedrag van quilt kunnen patches ook bestanden verwijderen.
Als tijdens het extraheren patches werden toegepast, wordt het bestand .pc/applied-patches aangemaakt.
Bouwen
Alle originele tar-archieven die in de huidige map gevonden worden, worden geëxtraheerd in een tijdelijke map en daarbij wordt dezelfde logica gevolgd als bij het uitpakken. De debian-map wordt naar de tijdelijke map gekopieerd en alle patches worden toegepast, behalve de automatische patch (debian-changes-versie of debian-changes, afhankelijk van --single-debian-patch). De tijdelijke map wordt vergeleken met de map van het broncodepakket. Indien de diff niet leeg is, zal het bouwen mislukken, tenzij --single-debian-patch of --auto-commit gebruikt werden en in dat geval wordt de diff opgeslagen in de automatische patch. Indien de automatische patch aangemaakt/verwijderd wordt, wordt hij toegevoegd aan/verwijderd van het bestand series en van de metadata van quilt.
Een eventuele wijziging aan een binair bestand kan niet weergegeven worden in een diff en zal dus tot een mislukking leiden, tenzij de onderhouder bewust besloot dat gewijzigd binair bestand toe te voegen aan het Debian tar-archief (door het op te sommen in debian/source/include-binaries). Het bouwen zal ook mislukken als er binaire bestanden aangetroffen worden in de onderliggende map debian, tenzij dit toegestaan werd via debian/source/include-binaries.
De bijgewerkte map debian en de lijst van gewijzigde binaire bestanden wordt dan gebruikt om het Debian tar-archief te genereren.
De automatisch gegenereerde diff bevat geen wijzigingen aan VCS-specifieke bestanden (d.w.z. bestanden eigen aan het versiebeheersysteem) en aan veel tijdelijke bestanden (kijk in de uitvoer van --help voor de standaardwaarde die met de optie -i) verbonden is. In het bijzonder wordt de map .pc die door quilt gebruikt wordt, genegeerd tijdens het genereren van de automatische patch.
Opmerking: dpkg-source --before-build (en --build) zal ervoor zorgen dat alle patches die in het bestand series opgesomd zijn, toegepast worden, zodat bij het bouwen van een pakket steeds alle patches toegepast zijn. Het doet dit door te zoeken naar niet-toegepaste patches (ze worden opgesomd in het bestand series maar niet in .pc/applied-patches) en indien de eerste patch uit die reeks foutloos toegepast kan worden, zal het ze allemaal toepassen. De optie --no-preparation kan gebruikt worden om dit gedrag uit te schakelen.
Wijzigingen optekenen
Een patchbestand opgeven is vooral nuttig na een mislukte bouwpoging die dat bestand vooraf aanmaakte. Op grond daarvan wordt dat bestand na integratie verwijderd. Merk ook op dat de wijzigingen die het patch-bestand bevat, reeds toegepast moeten zijn op de boom en dat de bestanden die door de patch aangepast werden geen bijkomende niet-opgetekende wijzigingen mogen bevatten.
Indien het genereren van de patch gewijzigde binaire bestanden opmerkt, zullen die automatisch toegevoegd worden aan debian/source/include-binaries, zodat die terecht komen in het debian tar-archief (exact op dezelfde manier als dpkg-source --include-binaries --build zou doen).
Bouwopties
Extractieopties
Ondersteund sinds dpkg 1.14.17. Deze indeling is bijzonder. Ze stelt eigenlijk geen echte broncodepakketindeling voor, maar kan gebruikt worden om broncodepakketten met arbitraire bestanden te maken.
Bouwopties
Alle argumenten die geen opties zijn, worden geïnterpreteerd als bestanden die geïntegreerd moeten worden in het gegenereerde broncodepakket. Ze moeten bestaan en zich bij voorkeur in de huidige map bevinden. Tenminste één bestand moet opgegeven worden.
Ondersteund sinds dpkg 1.14.17. Dit is een experimentele indeling.
Een broncodepakket volgens deze indeling bestaat uit een eenvoudige bundeling van een git-depot .git die de broncode van het pakket bevat. Er kan ook een bestand .gitshallow bestaan die de revisies vermeldt van een git shallow clone (een summiere kloon van een git-depot).
Extracting
De bundel wordt gekloond in de doelmap als een git-depot. Als er een bestand gitshallow bestaat, wordt het als .git/shallow geïnstalleerd binnenin het gekloonde git-depot.
Merk op dat standaard het nieuwe depot dezelfde tak zal binnengehaald hebben die binnengehaald was in de originele broncode. (Meestal is dat “main”, maar dat kan om het even wat zijn). Eventuele andere takken zullen beschikbaar zijn onder remotes/origin/.
Bouwen
Vooraleer voort te gaan, worden een aantal controles uitgevoerd om zeker te zijn dat er geen niet-vastgelegde wijzigingen zijn die niet mogen genegeerd worden.
git-bundle(1) wordt gebruikt om een bundel te genereren van het git-depot. Standaard worden alle takken en tags uit het depot in de bundel opgenomen.
Bouwopties
Ondersteund sinds dpkg 1.14.17. Dit is een experimentele indeling. Ze genereert één enkel tar-archief met daarin het bzr-depot.
Extracting
Het tar-archief wordt uitgepakt en daarna wordt bzr gebruikt om een werkkopie van de huidige tak te maken.
Bouwen
Vooraleer voort te gaan, worden een aantal controles uitgevoerd om zeker te zijn dat er geen niet-vastgelegde wijzigingen zijn die niet mogen genegeerd worden.
Daarna wordt het versiebeheerspecifieke deel van de broncodemap gekopieerd naar een tijdelijke map. Vooraleer deze tijdelijke map in een tar-archief ingepakt wordt, worden verschillende opruimtaken verricht om plaats te winnen.
Het bestand debian/source/format moet altijd bestaan en de gewenste broncode-indeling aangeven. Met het oog op neerwaartse compatibiliteit wordt indeling “1.0” verondersteld als het bestand niet bestaat, maar u zou hierop niet moeten betrouwen: ergens in de toekomst zal dpkg-source aangepast worden, zodat het zal mislukken als het bestand niet bestaat.
De verantwoording is dat indeling “1.0” niet langer de aanbevolen indeling is. U zou gewoonlijk één van de recentere indelingen (“3.0 (quilt)”, “3.0 (native)”) moeten kiezen, maar dpkg-source zal dit niet automatisch voor u doen. Indien u de oude indeling wilt blijven gebruiken, moet u dat expliciet aangeven en “1.0” plaatsen in debian/source/format.
Als u broncode-indeling “1.0” gebruikt, is het meestal geen goed idee om rechtstreeks wijzigingen aan te brengen in bestanden van de toeleveraar, vermits de wijzigingen verborgen en grotendeels niet-gedocumenteerd belanden in het bestand .diff.gz. U zou uw wijzigingen dan beter opslaan als patches in de map debian en ze dan op het ogenblik van het bouwen toepassen. Om deze complexe werkwijze te vermijden, kunt u ook de indeling “3.0 (quilt)” gebruiken, die dit geïntegreerd aanbiedt.
Wijzigingen aan de broncode van de toeleveraar worden gewoonlijk met patch-bestanden opgeslagen, maar niet alle wijzigingen kunnen met patches gerepresenteerd worden, omdat die enkel de inhoud van gewone tekstbestanden kunnen aanpassen. Indien u een bestand tracht te vervangen door iets van een ander type (bijvoorbeeld een gewoon bestand vervangen door een symbolische koppeling of een map), zult u deze foutmelding krijgen.
Lege bestanden kunnen niet met behulp van patch-bestanden aangemaakt worden. Deze wijziging wordt dus niet geregistreerd in het broncodepakket en u wordt daarover ingelicht.
Patch-bestanden registreren geen toegangsrechten van bestanden en dus wordt het feit dat een bestand uitvoerbaar is, niet in het broncodepakket opgeslagen. Deze waarschuwing brengt dit feit in herinnering.
Patch-bestanden registreren geen toegangsrechten van bestanden en dus worden wijzigingen aan toegangsrechten niet opgeslagen in het broncodepakket. Deze waarschuwing brengt dit feit in herinnering.
Dit bestand bevat op één enkele regel de indeling die gebruikt moet worden om het broncodepakket te bouwen (mogelijke indelingen werden hierboven beschreven). Voorafgaande of nakomende witruimte is niet toegelaten.
Dit bestand bevat een lijst van padnamen van binaire bestanden (één per regel) relatief ten opzichte van de broncodebasismap, welke opgenomen moeten worden in het debian tar-archief. Voorafgaande of nakomende spaties worden gestript. Regels die beginnen met ‘#’ zijn commentaar en worden overgeslagen. Lege regels worden genegeerd.
Dit bestand bevat een lijst met lange opties die automatisch voorgevoegd moeten worden aan de reeks commandoregelopties die gebruikt worden bij het inroepen van het commando dpkg-source --build of dpkg-source --print-format. Opties zoals --compression en --compression-level zijn zeer geschikt voor dit bestand.
Elke optie moet op een aparte regel geplaatst worden. Lege regels en regels die beginnen met ‘#’ worden genegeerd. De ‘--’ vooraan moeten weggelaten worden en korte opties zijn niet toegelaten. Facultatieve witruimte rond het symbool ‘=’ en facultatieve aanhalingstekens rond de waarde zijn toegelaten. Hierna volgt een voorbeeld van een dergelijk bestand:
# laat dpkg-source een bestand debian.tar.bz2 aanmaken met maximale compressie compression = "bzip2" compression-level = 9 # gebruik debian/patches/debian-changes als automatische patch single-debian-patch # negeer wijzigingen aan config.{sub,guess} extend-diff-ignore = "(^|/)(config.sub|config.guess)$"
Opmerking: --format-opties worden niet aanvaard in dit bestand. U moet daarvoor eerder debian/source/format gebruiken.
Precies zoals debian/source/options, behalve dat het bestand niet opgenomen wordt in het gegenereerde broncodepakket. Dit kan nuttig zijn om een voorkeur op te slaan die eigen is aan de onderhouder of aan een bepaald depot van een versiebeheersysteem waarin het pakket onderhouden wordt.
Vrij opgemaakte tekst die geplaatst wordt bovenaan de automatische patch die gegenereerd wordt bij de indelingen “2.0” en “3.0 (quilt)”. local-patch-header wordt niet toegevoegd aan het gegenereerde broncodepakket, terwijl dat met patch-header wel het geval is.
Dit bestand somt alle patches op die toegepast moeten worden (in de opgegeven volgorde) bovenop het broncodepakket van de toeleveraar. Spaties vooraan en achteraan worden weggehaald. leverancier is de naam in kleine letters van de huidige leverancier of debian als geen leverancier gedefinieerd werd. Indien het leveranciersspecifieke series-bestand niet bestaat, zal het leveranciersloze series-bestand gebruikt worden. Regels die beginnen met ‘#’ zijn commentaar en worden overgeslagen. Lege regels worden genegeerd. De overige regels beginnen met de bestandsnaam van een patch (relatief ten opzichte van de map debian/patches/) tot aan de eerste spatie of het einde van de regel. Facultatieve quilt-opties kunnen daarna komen tot aan het einde van de regel of tot aan het eerste ‘#’-teken dat voorafgegaan wordt door één of meer spaties (hetgeen het begin van een commentaarstuk aangeeft dat doorloopt tot het einde van de regel).
Het punt waarop de vervanging van velden plaats vindt, vergeleken met bepaalde standaardinstellingen voor uitvoervelden, is eerder onduidelijk.
deb-src-control(5), deb-changelog(5), deb-substvars(5), dsc(5).
2023-05-11 | 1.21.22 |