Provided by: dpkg-dev_1.19.0.5ubuntu2.4_all 
NAAM
dpkg-source - gereedschap voor het manipuleren van een Debian broncodepakket (.dsc)
OVERZICHT
dpkg-source [optie...] commando
BESCHRIJVING
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.
COMMANDO'S
-x, --extract bestandsnaam.dsc [uitvoermap]
Extraheer een broncodepakket (--extract sinds dpkg 1.17.14). Er moet één argument
dat geen optie is, opgegeven worden, namelijk de naam van het controlebestand
(.dsc) van de Debian broncode. Facultatief kan een tweede argument dat geen optie
is, opgegeven worden om de map op te geven waarin het pakket geëxtraheerd moet
worden. Die mag nog niet bestaan. Indien geen uitvoermap opgegeven werd, zal het
broncodepakket uitgepakt worden in een map met als naam broncode-versie, die onder
de huidige werkmap ligt.
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.
-b, --build map [indelingsspecifieke-parameters]
Bouw een broncodepakket (--build sinds dpkg 1.17.14). Het eerste argument dat geen
optie is, wordt gebruikt als de naam van de map die de voor Debian gereedgemaakte
broncodeboom bevat (d.w.z. met een onderliggende map debian en eventuele
veranderingen aan de originele bestanden). Afhankelijk van de
broncodepakketindeling die men gebruikt om het broncodepakket te bouwen, kunnen
bijkomende parameters opgegeven worden.
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.
--print-format map
Geef weer welke indeling gebruikt zou worden om het broncodepakket te bouwen indien
dpkg-source --build map aangeroepen werd (in dezelfde condities en met dezelfde
parameters; sinds dpkg 1.15.5).
--before-build map
Voer de overeenkomstige uitbreiding (hook) uit van de broncodepakketindeling (sinds
dpkg 1.15.8). Deze uitbreiding wordt telkens aangeroepen voor het pakket gebouwd
wordt (dpkg-buildpackage roept ze zeer vroeg aan, zelfs voor debian/rules clean).
Dit commando is idempotent en kan meermaals aangeroepen worden. Niet alle
broncode-indelingen implementeren iets in deze uitbreiding, en die welke dat wel
doen bereiden gewoonlijk de broncodeboom voor op het bouwproces, bijvoorbeeld door
ervoor te zorgen dat de Debian-patches toegepast worden.
--after-build map
Voer de overeenkomstige uitbreiding (hook) uit van de broncodepakketindeling (sinds
dpkg 1.15.8). Deze uitbreiding wordt telkens aangeroepen nadat het pakket gebouwd
werd (dpkg-buildpackage roept ze als laatste aan). Dit commando is idempotent en
kan meermaals aangeroepen worden. Niet alle broncode-indelingen implementeren iets
in deze uitbreiding, en die welke dat wel doen gebruiken ze gewoonlijk om ongedaan
te maken wat --before-build gedaan heeft.
--commit [map] ...
Tekent veranderingen op in de broncodeboom die in map uitgepakt werd (sinds dpkg
1.16.1). Aan dit commando kunnen afhankelijk van de broncode-indeling bijkomende
parameters opgegeven worden. Het zal een foutmelding geven bij indelingen waarvoor
deze operatie geen betekenis heeft.
-?, --help
Toon de gebruiksaanwijzing en sluit af. Met de optie --format kunnen de
indelingsspecifieke bouw- en extractie-opties getoond worden.
--version
Toon de versie en sluit af.
OPTIES
Generieke bouwopties
-ccontrolebestand
Duidt aan wat het belangrijkste controlebestand van de broncode is waaruit
informatie gelezen moet worden. Standaard is dat debian/control. Indien het
opgegeven wordt met een relatieve padnaam, dan wordt die geïnterpreteerd te
beginnen bij de basismap van de broncodeboom.
-lchangelog-bestand
Duidt het changelog-bestand aan waaruit informatie gelezen moet worden. Standaard
is dat debian/changelog. Indien het opgegeven wordt met een relatieve padnaam, dan
wordt die geïnterpreteerd te beginnen bij de basismap van de broncodeboom.
-Fchangelog-indeling
Geeft de indeling van het bestand changelog aan. Zie dpkg-parsechangelog(1) voor
informatie over alternatieve indelingen.
--format=waarde
Gebruik de opgegeven indeling om het broncodepakket te bouwen (sinds dpkg 1.14.17).
Het vervangt een eventuele in debian/source/format opgegeven indeling.
-Vnaam=waarde
Stel een uitvoersubstitutievariabele in. Zie deb-substvars(5) voor een bespreking
van uitvoersubstitutie.
-Tsubstvars-bestand
Lees substitutievariabelen uit substvars-bestand. De standaard is om geen enkel
bestand te lezen. Deze optie kan meermaals gebruikt worden om uit verschillende
bestanden substitutievariabelen te lezen (sinds dpkg 1.15.6).
-Dveld=waarde
Vervang in de uitvoer een veld uit het controlebestand of voeg er een toe.
-Uveld Verwijder in de uitvoer een veld uit het controlebestand.
-Zcompressie, --compression=compressie
Duidt het compressieniveau aan dat gebruikt wordt bij het maken van tar-archieven
en diff-bestanden (--compression sinds dpkg 1.15.5). Merk op dat deze optie niet
tot effect heeft dat bestaande tar-archieven opnieuw gecomprimeerd worden. Ze heeft
enkel invloed op nieuwe bestanden. Ondersteunde waarden zijn: gzip, bzip2, lzma en
xz. De standaardwaarde is xz voor de indeling 2.0 en recentere indelingen en gzip
voor de indeling 1.0. xz wordt enkel sinds dpkg 1.15.5 ondersteund.
-zniveau, --compression-level=niveau
Het te gebruiken compressieniveau (--compression-level sinds dpkg 1.15.5). Zoals
dit het geval is bij -Z, beïnvloedt dit enkel nieuw aangemaakte bestanden.
Ondersteunde waarden zijn: 1 tot 9, best, en fast. De standaardwaarde is 9 voor
gzip en bzip2, 6 voor xz en lzma.
-i[regex], --diff-ignore[=regex]
U kunt een perl reguliere expressie opgeven om bestanden die ermee overeenkomen weg
te houden uit de lijst bestanden waarover de gemaakte diff (overzicht van ondergane
wijzigingen) gaat (--diff-ignore sinds dpkg 1.15.6). (Deze lijst wordt gegenereerd
door een find-opdracht.) (Als het broncodepakket gebouwd wordt als een versie 3
broncodepakket dat gebruik maakt van een VCS (Version Control System -
versiebeheersysteem), kan dit gebruikt worden om niet-toegepaste wijzigingen aan
specifieke bestanden te laten negeren. Door -i.* te gebruiken zullen ze allemaal
genegeerd worden.)
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.
--extend-diff-ignore=regex
De opgegeven perl reguliere expressie breidt de standaardwaarde die door
--diff-ignore gebruikt wordt, uit en de huidige waarde ervan als die ingesteld werd
(sinds dpkg 1.15.6). Het doet dit door “|regex” samen te voegen met de bestaande
waarde. Deze optie is handig om te gebruiken in debian/source/options om bepaalde
automatisch gegenereerde bestanden uit te sluiten bij het automatisch genereren van
patches.
-I[bestandspatroon], --tar-ignore[=bestandspatroon]
Indien deze optie opgegeven werd, wordt het patroon doorgegeven aan de optie
--exclude van tar(1) wanneer dit commando ingeroepen wordt om een bestand .orig.tar
of .tar aan te maken (--tar-ignore sinds dpkg 1.15.6). Bijvoorbeeld, -ICVS zal tar
CVS-mappen doen overslaan bij het genereren van een .tar.gz-bestand. Deze optie kan
meermaals herhaald worden om meerdere patronen die uitgesloten moeten worden op te
sommen.
-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.
Generieke extractieopties
--no-copy
Kopieer de originele tar-archieven bij het geëxtraheerde broncodepakket niet (sinds
dpkg 1.14.17).
--no-check
Controleer voor het uitpakken geen ondertekeningen en controlesommen (sinds dpkg
1.14.17).
--no-overwrite-dir
Overschrijf de extractiemap niet als ze al bestaat (sinds dpkg 1.18.8).
--require-valid-signature
Weiger het broncodepakket uit te pakken als het geen OpenPGP-ondertekening bevat
die kan gecontroleerd worden (sinds dpkg 1.15.0) met ofwel de
trustedkeys.gpg-sleutelbos van de gebruiker, één van de leveranciersspecifieke
sleutelbossen of met één van de officiële sleutelbossen van Debian
(/usr/share/keyrings/debian-keyring.gpg en
/usr/share/keyrings/debian-maintainers.gpg).
--require-strong-checksums
Wijger het broncodepakket uit te pakken als het geen krachtige controlesommen bevat
(sinds dpkg 1.18.7). Momenteel is SHA-256 de enige gekende controlesom die als
krachtig aanzien wordt.
--ignore-bad-version
Als bij een controle het versienummer van het broncodepakket foutief blijkt te
zijn, maakt deze instelling dat de gegeven waarschuwing geen fataal karakter heeft
(sinds dpkg 1.17.7). Deze optie zou enkel nodig moeten zijn bij het extraheren van
oude broncodepakketten met een defecte versie om neerwaartse compatibiliteit te
verzekeren.
INDELINGEN VAN BRONCODEPAKKETTEN
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.
Indeling: 1.0
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.
Extraheren
Een Debian-eigen (native) pakket extraheren is een eenvoudige extractie van het enige
tar-archief in de doelmap. Een niet-eigen pakket extraheren bestaat eruit dat eerst
.orig.tar.gz uitgepakt wordt en dat dan de patch erop toegepast wordt uit het bestand
.diff.gz. 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). 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).
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):
If a second non-option argument is supplied it should be the name of the original source
directory or tarfile or the empty string if the package is a Debian-specific one and so
has no debianization diffs. If no second argument is supplied then dpkg-source will look
for the original source tarfile package_upstream-version.orig.tar.gz or the original
source directory directory.orig depending on the -sX arguments.
-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.
-sk Geeft aan dat verwacht mag worden dat de originele broncode in de vorm van een
tar-bestand kan aangetroffen worden, wat standaard
pakket_toeleveraarsversie.orig.tar.extensie is. Het zal deze originele broncode als
een tar-bestand laten staan of ze naar de huidige map kopiëren als ze zich daar nog
niet bevindt. Het tar-archief zal uitgepakt worden in map.orig met het oog op het
genereren van het diff-bestand.
-sp Zoals -sk maar dit zal naderhand de map weer verwijderen.
-su Geeft aan dat verwacht mag worden dat de originele broncode in de vorm van een map
kan aangetroffen worden, wat standaard pakket-toeleveraarsversie.orig is, en
dpkg-source zal er een nieuw archief met de originele broncode mee maken.
-sr Zoals -su, maar het zal die map na gebruik verwijderen.
-ss Geeft aan dat de originele broncode zowel als een map als in de vorm van een
tar-bestand te vinden is. dpkg-source zal de map gebruiken om het diff-bestand te
creëren, maar het tar-bestand om het .dsc-bestand te maken. Gebruik deze optie met
zorg - indien de map en het tar-bestand niet overeenkomen zal er een slecht
broncodearchief gegenereerd worden.
-sn Specifies to not look for any original source, and to not generate a diff. The
second argument, if supplied, must be the empty string. This is used for
Debian-specific packages which do not have a separate upstream source and therefore
have no debianization diffs.
-sa of -sA
Specifies to look for the original source archive as a tarfile or as a directory -
the second argument, if any, may be either, or the empty string (this is equivalent
to using -sn). If a tarfile is found it will unpack it to create the diff and
remove it afterwards (this is equivalent to -sp); if a directory is found it will
pack it to create the original source and remove it afterwards (this is equivalent
to -sr); if neither is found it will assume that the package has no debianization
diffs, only a straightforward source archive (this is equivalent to -sn). If both
are found then dpkg-source will ignore the directory, overwriting it, if -sA was
specified (this is equivalent to -sP) or raise an error if -sa was specified. -sA
is the default.
--abort-on-upstream-changes
Het proces mislukt als het gegenereerde diff-bestand wijzigingen aan bestanden
buiten de onderliggende debian-map bevat (sinds dpkg 1.15.8). Deze optie is in
debian/source/options niet toegestaan, maar ze kan wel gebruikt worden in
debian/source/local-options.
Extractieopties (met --extract):
In alle gevallen zal een eventuele bestaande originele broncodeboom verwijderd worden.
-sp Als dit bij het extraheren gebruikt wordt, dan zal het de (eventuele) originele
broncode in zijn vorm van tar-bestand laten. Indien dit zich nog niet in de huidige
map bevindt, of indien er zich een bestaand maar verschillend bestand bevindt, zal
het naar daar gekopieerd worden. (Dit is de standaard).
-su Pakt de originele broncodeboom uit.
-sn Zorgt ervoor dat de originele broncode noch naar de huidige map gekopieerd wordt
noch uitgepakt wordt. Een eventuele originele broncodeboom die zich in de huidige
map bevond, wordt nog steeds verwijderd.
Al de -sX-opties sluiten elkaar wederzijds uit. Indien u er meer dan één opgeeft, dan zal
enkel de laatste gebruikt worden.
--skip-debianization
Slaat het toepassen van de debian diff bovenop de broncode van de toeleveraar over
(sinds dpkg 1.15.1).
Indeling: 2.0
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.
Indeling: 3.0 (native) (d.w.z. debian-eigen)
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).
Indeling: 3.0 (quilt)
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
en koppeltekens (‘-’) bevatten. Optioneel mag bij elk originele tar-archief een
afzonderlijke handtekening van de toeleveraar (.orig.tar.ext.asc en
.orig-component.tar.ext.asc), gevoegd zijn. De extractie ervan wordt ondersteund sinds
dpkg 1.17.20 en het bouwen sinds dpkg 1.18.5.
Extraheren
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 opgesomd zijn in debian/patches/debian.series
of debian/patches/series. 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 de set patches te vereenvoudigen. Merk nochtans op dat hoewel dpkg-source op
correcte wijze series-bestanden ontleedt 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.
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 zij op de witte lijst gezet
werden 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
--commit [map] [patchnaam] [patchbestand]
Genereert een patch in verband met de lokale wijzigingen die niet door het
patchsysteem van quilt beheerd worden en integreert die in het patchsysteem onder
de naam patchnaam. Indien de naam ontbreekt, zal er interactief om gevraagd worden.
Indien patchbestand opgegeven werd, wordt dat gebruikt als de te integreren patch
in verband met de lokale wijzigingen. Na de integratie wordt een editor opgestart,
zodat u de meta-informatie in de koptekst van de patch kunt bewerken.
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
--allow-version-of-quilt-db=versie
Laat dpkg-source toe het broncodepakket te bouwen als de versie van de metadata van
quilt de opgegeven versie is, zelfs al kent dpkg-source die niet (sinds dpkg
1.15.5.4). Dit zegt effectief dat de opgegeven versie van de quilt-metadata
compatibel is met versie 2 die momenteel door dpkg-source ondersteund wordt. De
versie van de metadata van quilt wordt opgeslagen in .pc/.version.
--include-removal
Negeer verwijderde bestanden niet en neem ze op in de automatisch gegenereerde
patch.
--include-timestamp
Voeg de tijdsaanduiding toe in de automatisch gegenereerde patch.
--include-binaries
Voeg alle gewijzigde binaire bestanden toe aan het debian tar-archief. Voeg ze ook
toe in debian/source/include-binaries: in erop volgende bouwactiviteiten zullen ze
standaard toegevoegd worden en is deze optie dus niet meer nodig.
--no-preparation
Tracht de bouwboom niet voor te bereiden door patches toe te passen die blijkbaar
niet toegepast zijn (sinds dpkg 1.14.18).
--single-debian-patch
Gebruik debian/patches/debian-changes in plaats van
debian/patches/debian-changes-versie voor de naam van de tijdens het bouwen
automatisch gegenereerde patch (sinds dpkg 1.15.5.4). Deze optie is in het
bijzonder nuttig als het pakket wordt onderhouden in een VCS (versiebeheersysteem)
en een reeks patches niet op een betrouwbare manier gegenereerd kan worden. De
huidige verschillen (de diff) met de toeleveraarsversie moeten dan eerder in een
enkele patch opgeslagen worden. Deze optie wordt geplaatst in
debian/source/local-options en gaat samen met een bestand
debian/source/local-patch-header waarin uitgelegd wordt hoe de door Debian
aangebrachte wijzigingen best herzien kunnen worden, bijvoorbeeld in het
versiebeheersysteem dat gebruikt wordt.
--create-empty-orig
Creëer automatisch een leeg primair origineel tar-archief als dat ontbreekt en er
wel bijkomende originele tar-archieven zijn (sinds dpkg 1.15.6). Deze optie is
bedoeld om gebruikt te worden als het broncodepakket slechts een bundel is van
samengestelde toegeleverde software zonder een “centraal” programma.
--no-unapply-patches, --unapply-patches
Standaard zal dpkg-source de patches uit de uitbreiding (hook) --after-build
automatisch terugdraaien als het die tijdens --before-build heeft toegepast
(--unapply-patches sinds dpkg 1.15.8, --no-unapply-patches sinds dpkg 1.16.5). Deze
opties laten u toe om het proces van automatisch terugdraaien van patches
uitdrukkelijk in of uit te schakelen. Deze opties mogen enkel in
debian/source/local-options gebruikt worden, zodat alle gegenereerde
broncodepakketten standaard hetzelfde gedrag vertonen.
--abort-on-upstream-changes
Het proces mislukt als een automatische patch gegenereerd werd (sinds dpkg 1.15.8).
Deze optie kan gebruikt worden om te verzekeren dat alle wijzigingen terdege
geregistreerd worden in aparte quilt-patches vooraleer het broncodepakket
gegenereerd wordt. Deze optie is niet toegestaan in debian/source/options, maar mag
gebruikt worden in debian/source/local-options.
--auto-commit
Het proces mislukt niet als een automatische patch gegenereerd werd. In de plaats
daarvan wordt hij onmiddellijk opgetekend in het bestand series van quilt.
Extractieopties
--skip-debianization
Slaat het extraheren van het debian tar-archief bovenop de broncode van de
toeleveraar over (sinds dpkg 1.15.1).
--skip-patches
Pas op het einde van de extractie geen patches toe (sinds dpkg 1.14.18).
Indeling: 3.0 (custom) (d.w.z. aangepast)
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.
--target-format=waarde
Verplicht. Definieert de echte indeling van het gegenereerde broncodepakket. Het
gegenereerde .dsc-bestand zal in het veld Format deze waarde bevatten en niet “3.0
(custom)”.
Indeling: 3.0 (git)
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).
Extraheren
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 “master”, 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
--git-ref=ref
Laat toe om een git-referentie op te geven die in de bundel opgenomen moet worden.
Daar gebruik van maken schakelt het standaardgedrag om alle takken en tags op te
nemen uit. Kan meermaals vermeld worden. De referentie kan de naam van een tak of
een tag zijn die opgenomen moet worden. Het kan ook een parameter zijn die
doorgegeven kan worden aan git-rev-list(1). Gebruik bijvoorbeeld --git-ref=master
om enkel de master-tak op te nemen. Om alle takken en tags, behalve de tak
persoonlijk op te nemen, gebruikt u --git-ref=--all --git-ref=^persoonlijk.
--git-depth=aantal
Creëert een summiere (shallow) kloon met een geschiedenis die afgekapt werd bij het
opgegeven aantal revisies.
Indeling: 3.0 (bzr)
Ondersteund sinds dpkg 1.14.17. Dit is een experimentele indeling. Ze genereert één enkel
tar-archief met daarin het bzr-depot.
Extraheren
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.
DIAGNOSTIEK
geen broncode-indeling opgegeven in debian/source/format
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.
de diff wijzigt de volgende bestanden van de toeleveraar
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.
kan wijziging aan bestand niet representeren
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.
nieuw gecreëerd leeg bestand bestand zal niet gerepresenteerd worden in de diff
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.
toegangsrechten uitvoerbare modus van bestand zullen niet gerepresenteerd worden in de diff
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.
toegangsrechten bijzondere modus van bestand zullen niet gerepresenteerd worden in de diff
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.
OMGEVING
SOURCE_DATE_EPOCH
Indien dit ingesteld werd, zal het gebruikt worden als de tijdsaanduiding
(timestamp) (in seconden sinds de epoch) om de mtime vast te zetten op de items uit
het tar(5)-bestand.
VISUAL
EDITOR Gebruikt door de broncode-indelingmodules “2.0” en “3.0 (quilt)”.
GIT_DIR
GIT_INDEX_FILE
GIT_OBJECT_DIRECTORY
GIT_ALTERNATE_OBJECT_DIRECTORIES
GIT_WORK_TREE
Gebruikt door de broncode-indelingmodules “3.0 (git)”.
BESTANDEN
debian/source/format
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.
debian/source/include-binaries
Dit bestand bevat een lijst van binaire bestanden (één per regel) die 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.
debian/source/options
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.
debian/source/local-options
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.
debian/source/local-patch-header en debian/source/patch-header
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.
debian/patches/series
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. 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).
BUGS
Het punt waarop de vervanging van velden plaats vindt, vergeleken met bepaalde
standaardinstellingen voor uitvoervelden, is eerder onduidelijk.
ZIE OOK
deb-src-control(5), deb-changelog(5), dsc(5).