dpkg-source(1) | dpkg suite | dpkg-source(1) |
dpkg-source - Outil de manipulation des paquets sources Debian (.dsc).
dpkg-source [option...] commande
dpkg-source empaquette ou dépaquette une archive source Debian.
Aucune de ces commandes ne permet la combinaison de plusieurs options en une seule et elles ne permettent pas d'indiquer la valeur d'une option dans un argument séparé.
dpkg-source lit, dans le fichier de contrôle, les noms des fichiers qui composent le paquet source ; il suppose qu'ils sont dans le même répertoire que le fichier .dsc.
Les fichiers extraits du paquet auront leurs propriétaires et permissions définis à ceux attendus s'ils avaient été simplement créés. Les répertoires et les fichiers exécutables auront une permission égale à 0777 et les simples fichiers à 0666, les deux étant modifiées par le masque (umask) de celui qui fait l'extraction. Si le répertoire parent est « setgid », les répertoires extraits le seront aussi et tous les fichiers et répertoires hériteront de sa propriété de groupe.
Si le paquet source utilise un format non standard (actuellement, cela signifie tous les formats sauf le « 1.0 »), son nom sera enregistré dans debian/source/format de sorte que la construction du paquet source utilise le même format par défaut.
dpkg-source va construire le paquet source dans le premier format trouvé dans la liste suivante : le(s) format(s) indiqué(s) avec le paramètre de la ligne de commande --format, le format indiqué dans debian/source/format, « 1.0 ». L'utilisation de « 1.0 » comme dernier recours est obsolète et sera retirée dans le futur. Le format source devrait toujours être indiqué dans debian/source/format. Voir la section FORMATS DE PAQUET SOURCE pour une description plus détaillée des différents formats de paquet source.
L'option -i active cette fonction avec une expression rationnelle par défaut (en préservant toutes les modifications faites avec l'expression rationnelle par défaut par une utilisation précédente de --extend-diff-ignore) qui couvre les fichiers de contrôle des plus usuels systèmes de gestion de version, les fichiers de sauvegarde, les fichiers d'échange et les répertoires utilisés par Libtool. Il ne peut y avoir qu'une seule expression rationnelle active ; avec de multiples options -i, seule la dernière mentionnée sera prise en compte.
C'est très utile pour supprimer des fichiers qui sont inclus dans le diff, par exemple, si vous maintenez un source avec un système de contrôle de version et que voulez construire un paquet source sans inclure des fichiers et répertoires additionnels qu'il contient généralement (par exemple CVS/, .cvsignore, .svn/). L'expression rationnelle par défaut est déjà très exhaustive, mais si avez besoin de la remplacer, veuillez noter que par défaut, il sait vérifier n'importe quelle partie d'un chemin, donc si vous voulez trouver le début d'un nom de fichier ou des noms de fichiers complets, vous devrez fournir les caractères spéciaux vous-même (par exemple « (^|/) », « ($|/) »).
-I ajoute par défaut des options --exclude qui élimineront les fichiers et les répertoires de contrôles des systèmes les plus connus de contrôle de version, les fichiers d'échange et de sauvegarde et les répertoires utilisés par Libtool.
Note : même si elles ont des rôles similaires, -i et -I ont une syntaxe et une sémantique très différentes. -i ne peut être spécifié qu'une fois et reçoit une expression rationnelle compatible avec le langage Perl qui est appliquée sur chaque chemin relatif complet de chaque fichier. -I peut être spécifié plusieurs fois et prend un motif de nom de fichier avec les méta-caractères du shell. Le motif est appliqué au chemin relatif complet mais aussi à chaque partie du chemin individuellement. La sémantique exacte de l'option --exclude de tar est un peu compliquée, voir <https://www.gnu.org/software/tar/manuel/tar.html#wildcards> pour une documentation plus complète.
L'expression rationnelle et le motif par défaut pour les deux options peuvent être trouvés dans la sortie de la commande --help.
Si vous ne savez pas quel format source utiliser, il est conseillé de choisir soit « 3.0 (quilt) » soit « 3.0 (native) ». Voir <https://wiki.debian.org/Projects/DebSrc3.0> pour plus d'informations sur la mise en œuvre de ces formats dans Debian.
Un paquet source dans ce format se compose soit d'un .orig.tar.gz associé à un .diff.gz ou un simple .tar.gz (dans ce cas, le paquet est appelé natif native). L'archive tar originale pourrait être accompagnée de façon facultative d'une signature amont séparée .orig.tar.gz.asc, extraction prise en charge depuis dpkg 1.18.5.
Extraction
Extraire un paquet natif revient à une simple extraction de l'archive tar dans le répertoire cible. L'extraction d'un paquet non natif consiste au dépaquetage du .orig.tar.gz puis l'application des correctifs contenus dans le .diff.gz. La date de tous les fichiers correctifs est réglée à celle du moment de l'extraction depuis le paquet source (cela évite les horodatages faux menant à des problèmes lorsque des fichiers générés automatiquement sont modifiés). Le diff peut créer de nouveaux fichiers (tout le répertoire debian est créé de cette façon) mais ne peut pas supprimer de fichiers (les fichiers vides seront laissés là) et ne peut ni créer ni modifier des liens symboliques.
Construction
Construire un paquet natif revient simplement à créer une archive tar avec le répertoire du source. La création d'un paquet non natif consiste à extraire l'archive d'origine dans un répertoire séparé « .orig » puis à régénérer le .diff.gz en comparant le répertoire du paquet source avec le répertoire « .orig ».
Options de construction (avec --build) :
Si l'on donne un second argument, ce sera le nom du répertoire source d'origine ou le nom du fichier tar ou bien une chaîne vide si le paquet est un « Debian pure souche » et n'a donc pas de fichiers « diffs » pour sa « debianisation ». S'il n'y a pas de second argument, dpkg-source cherche le fichier tar des sources d'origine paquet_version-amont.orig.tar.gz ou bien le répertoire source d'origine répertoire.orig selon les paramètres -sX.
Les options -sa, -sp, -sk, -su et -sr ne remplacent pas les fichiers tar ou les répertoires existants. Pour cela, il faut utiliser les options -sA, -sP, -sK, -sU et -sR.
options d'extraction (avec --extract) :
Dans tous ces cas, l'arborescence existante des sources d'origine est supprimée.
Toutes les options -sX s'excluent mutuellement. Si vous en indiquez plusieurs, seule la dernière sera prise en compte.
Extraction prise en charge depuis dpkg 1.13.9, construction depuis dpkg 1.14.8. Aussi connu sous le nom de « wig&pen ». Ce format n'est pas recommandé pour une utilisation massive, le format « 3.0 (quilt) » le remplace. Wig&pen a été la première spécification d'une nouvelle génération de format de paquet source.
Le comportement de ce format est le même que pour le format « 3.0 (quilt) » sauf qu'il n'utilise pas de liste explicite de correctifs. Tous les fichiers dans debian/patches/ correspondant à l'expression rationnelle Perl [\w-]+ doivent être des correctifs valables : ils sont appliqués au moment de l'extraction.
Lors de la construction d'un nouveau paquet source, toute modification apportée au source amont est enregistrée dans un correctif nommé zz_debian-diff-auto.
Pris en charge depuis dpkg 1.14.17. Ce format est une extension du format de paquet natif tel que défini dans le format 1.0. Il gère toutes les méthodes de compression et ignore par défaut tout fichier et répertoire spécifique à VCS ainsi que de nombreux fichiers temporaires (voir la valeur par défaut associée à l'option -I dans la sortie de --help).
Pris en charge depuis 1.14.17. Un paquet source dans ce format contient au moins une archive tar d'origine (.orig.tar.ext où ext peut être gz, bz2 lzma et xz) et une archive tar debian (.debian.tar.ext). Il peut également contenir d'autres archives tar d'origine (.orig-composant.tar.ext). composant ne peut être constitué que de caractères alphanumériques (« a-zA-Z0-9 ») et de tirets (« - »). Chaque archive tar originale peut être accompagnée de façon facultative d'une signature amont séparée (.orig.tar.ext.asc et .orig-composant.tar.ext.asc), extraction prise en charge depuis dpkg 1.17.20, construction depuis dpkg 1.18.5.
Extraction
L'archive principale tar d'origine est extraite tout d'abord, puis toutes les autres archives tar d'origine sont extraites dans des sous-répertoires dont le nom est formé à partir de la partie composant de leur nom. L'archive tar Debian est extraite du répertoire source, après la suppression de tout répertoire debian existant. Notez que l'archive tar Debian doit contenir un sous-répertoire debian, mais elle peut également contenir des fichiers binaires en dehors de ce répertoire (voir l'option --include-binaries).
Toutes les modifications figurant dans debian/patches/distributeur.series ou debian/patches/series sont alors appliquées, où distributeur sera le nom en minuscules du distributeur actuel, ou Debian s'il n'y a pas de distributeur défini. Si l'ancien fichier est utilisé et qu'il n'y en a pas de plus récent (ou si c'est un lien symbolique), alors celui-ci est remplacé par un lien symbolique vers l'ancien. Cette disposition vise à simplifier l'utilisation de quilt pour gérer l'ensemble des correctifs. Les fichiers de séries propres au distributeur sont destinés à permettre de sérialiser plusieurs branches de développement en se basant sur le distributeur, d'une manière déclarative, de préférence au codage ouvert de cette gestion dans debian/rules. Cela est particulièrement utile quand le source à besoin de correctifs de manière conditionnelle, car les fichiers affectés n’ont pas de gestion interne d’inclusion conditionnelle. Notez toutefois que si dpkg-source analyse correctement les fichiers de séries avec les options utilisées pour l'application du correctif (stockées sur chaque ligne après le nom du correctif et une ou plusieurs espaces), il ignore ces options et s'attendra toujours à ce que les correctifs puissent être appliqués avec l'option -p1 de patch. Il va donc émettre un avertissement lorsqu'il rencontrera ces options, et la construction est susceptible d'échouer.
Notez que lintian(1) émettra des avertissements sans condition lors de l'utilisation de séries de distributeur du fait d'une règle controversée particulière de Debian qui ne devrait pas affecter une utilisation externe ; pour les faire taire, le profil lintian de dpkg peut être utilisé en passant l'option «--profile dpkg» à lintian(1).
La date de tous les fichiers correctifs est celle du moment où se déroule l'extraction du paquet source (cela évite les horodatages faux menant à des problèmes lorsque des fichiers générés automatiquement sont modifiés).
Au contraire du comportement par défaut de quilt, les correctifs doivent s'appliquer sans décalage (« fuzz »). Quand cela n'est pas le cas, il est suggéré de les rafraîchir avec quilt sinon dpkg-source se terminera avec une erreur en tentant de les appliquer.
Similaire au comportement par défaut de quilt, les modifications peuvent aussi supprimer des fichiers.
Le fichier .pc/applied-patches est créé si certains correctifs ont été appliqués au cours de l'extraction.
Construction
Les originaux de toutes les archives tar trouvées dans le répertoire courant sont extraits dans un répertoire temporaire en suivant la même logique que pour le dépaquetage, le répertoire debian est copié dans le répertoire temporaire, et tous les correctifs excepté le correctif automatique debian-changes-version ou debian-changes, selon --single-debian-patch) sont appliquées. Le répertoire temporaire est comparé à celui du paquet source. Si le fichier de différences n'est pas vide, la construction échoue à moins que --single-debian-patch ou --auto-commit aient été utilisés, et dans ce cas le diff est stocké dans le correctif automatique. Si le correctif automatique est créé ou supprimé, il est ajouté ou supprimé dans le fichier « series » et les métadonnées de quilt.
Tout changement dans un fichier binaire ne peut être indiqué dans le diff et va déboucher sur un échec à moins que le responsable ne décide délibérément d'inclure cette modification binaire dans l'archive tar Debian (en le listant dans debian/source/include-binaries). La construction pourra également échouer si des fichiers binaires sont trouvés dans le sous-répertoire debian à moins qu'ils aient été autorisés au moyen de debian/source/include-binaries.
Le répertoire debian mis à jour et la liste des binaires modifiés sont ensuite utilisés pour recréer l'archive tar debian.
Le diff généré automatiquement n'inclut pas les changements spécifiques sur les fichiers VCS ainsi sur que de nombreux fichiers temporaires (pour la valeur par défaut associée à l'option -i, voir la sortie de --help). En particulier, le répertoire .pc utilisé par quilt est ignoré lors de la génération automatique du correctif.
Note : dpkg-source --before-build (et --build) prendront soin d'appliquer les correctifs indiqués dans le fichier series afin qu'un paquet soit toujours construit avec toutes les corrections appliquées. Pour effectuer cette détection, il recherche la liste des correctifs non appliqués (ils sont mentionnés dans le fichier series mais pas dans .pc/applied-patches) et si le premier de cette liste peut être appliqué sans erreur, il les applique tous. L'option --no-preparation peut être utilisée pour désactiver ce comportement.
Enregistrement des modifications
Le fait de passer fichier-de-correctifs est essentiellement utile après un échec de construction qui prégénère ce fichier. Sur ces bases, le fichier est supprimé après intégration. Veuillez également noter que les modifications contenues dans le fichier de correctifs doivent déjà être appliquées dans l'arborescence et que les fichiers modifiés par le correctif ne doivent pas comporter de modifications supplémentaires.
Si la création de correctif détecte des fichiers binaires modifiés, ils seront ajoutés automatiquement à debian/source/include-binaries afin de pouvoir être inclus dans l'archive debian (de façon analogue à ce que ferait dpkg-source --include-binaries --build).
Options de construction
Options d'extraction
Pris en charge depuis dpkg 1.14.17. Ce format est particulier. Il ne représente pas un réel format de paquet source mais peut être utilisé pour créer des paquets sources avec des fichiers arbitraires.
Options de construction
Tous les arguments qui ne sont pas des options sont pris pour des fichiers à intégrer dans le paquet source généré. Ils doivent exister et être de préférence dans le répertoire courant. Au moins un fichier doit être donné.
Pris en charge depuis dpkg 1.14.17. Ce format est expérimental.
Un paquet source qui utilise ce format est constitué d'un seul ensemble d'un dépôt git .git qui contient les sources du paquet. Il peut également exister un fichier .gitshallow qui donne les révisions d'un clone git « shallow ».
Extraction
Cet ensemble est cloné sous forme d'un dépôt git dans le répertoire cible. S'il existe un fichier .gitshallow, il est installé en tant que .git/shallow dans le dépôt git cloné.
Veuillez noter que, par défaut, le nouveau dépôt aura la même branche récupérée que celle qui était récupérée dans les sources d'origine (souvent « main » mais cela peut être tout à fait autre chose). Toutes les autres branches seront disponibles sous remotes/origin.
Construction
Avant d'aller plus loin, quelques vérifications sont effectuées afin de s'assurer qu'il n'existe aucun changement non ignoré non soumis.
git-bundle(1) permet de créer un ensemble à partir du dépôt git. Par défaut, toutes les branches et étiquettes du dépôt sont incluses dans cet ensemble.
Options de construction
Pris en charge depuis dpkg 1.14.17. Ce format est expérimental. Il crée une archive tar contenant le dépôt bzr correspondant.
Extraction
L'archive tar est décompressée puis bzr est utilisé afin de récupérer la branche courante.
Construction
Avant d'aller plus loin, quelques vérifications sont effectuées afin de s'assurer qu'il n'existe aucun changement non ignoré non soumis.
Ensuite, la partie spécifique du répertoire source du gestionnaire de versions est copiée dans un répertoire temporaire. Avant que ce répertoire temporaire ne soit empaqueté dans une archive tar, divers nettoyages sont effectués pour économiser de l'espace.
Le fichier debian/source/format devrait toujours exister et indiquer le format source souhaité. Pour préserver la compatibilité avec d'anciennes versions, le format « 1.0 » est implicite quand le fichier n'existe pas. Il est déconseillé de dépendre de ce comportement qui pourrait être modifié dans de futures versions de dpkg-source, qui échoueront alors en l'absence d'une mention explicite de format.
Cela est dû au fait que le format « 1.0 » n'est plus le format recommandé, qu'il est conseillé de choisir un des formats les plus récents (« 3.0 (quilt) » ou « 3.0 (native) ») mais que dpkg-source ne le fera pas automatiquement. Si vous souhaitez continuer à utiliser l'ancien format, il est nécessaire d'être explicite et indiquer « 1.0 » dans debian/source/format.
Lors de l'utilisation du format source « 1.0 », il est déconseillé de modifier directement les fichiers amont, car les modifications restent alors cachées et souvent non documentées dans le fichier diff.gz. Au contraire, il est conseillé de conserver les modifications sous forme de correctifs dans le répertoire debian et de les appliquer au moment de la construction. Pour éviter ces opérations plus complexes, vous pouvez également choisir le format « 3.0 (quilt) » qui permet ces opérations de manière native.
Les modifications des sources amont sont en général conservées dans des fichiers de correctifs mais certaines modifications ne peuvent être représentées sous forme de tels fichiers qui ne peuvent modifier que des fichiers texte. Si vous essayez de remplacer un fichier avec un objet d'un type différent (par exemple remplacer un fichier par un lien ou un répertoire), ce message d'erreur s'affichera.
Les fichiers vides ne peuvent pas être créés avec des correctifs. En conséquence, la modification n'est pas enregistrée dans le paquet source, ce qui provoque cet avertissement.
Les fichiers de correctifs n'enregistrent pas les permissions de fichiers et, en conséquence, les permissions des exécutables ne sont pas enregistrées dans le paquet source, ce qui provoque cet avertissement.
Les fichiers correctifs n'enregistrent pas les permissions de fichiers et, en conséquence, les permissions modifiées ne sont pas enregistrées dans le paquet source, ce qui provoque cet avertissement.
Ce fichier contient sur une seule ligne le format à utiliser pour construire le paquet source (les formats acceptés sont décrits plus haut). Il ne doit pas contenir d'espace avant ou après l'indication du format.
Ce fichier contient une liste de chemin de fichiers binaires (un par ligne) relatifs au répertoire racine source qui doivent être inclus dans l'archive tar debian. Les espaces placées avant ou après ces noms sont supprimées. Les lignes commençant par « # » sont des commentaires et sont ignorées, ainsi que les lignes vides.
Ce fichier contient la liste des options qui seront automatiquement ajoutées au jeu d'options de ligne de commande lors de l'appel à dpkg-source --build ou dpkg-source --print-format. Des options comme --compression et --compression-level conviennent bien pour ce fichier.
Chaque option doit être placée sur une ligne distincte. Les lignes vides et les lignes commençant par le caractère « # » sont ignorées. Les caractères initiaux « -- » doivent être retirés et les options courtes ne peuvent pas être utilisées. Des espaces optionnelles sont autorisées autour du symbole « = », ainsi que des guillemets optionnels autour de la valeur d'une option donnée. Voici un exemple d'un tel fichier :
# autoriser dpkg-source à créer un fichier debian.tar.bz2 avec la #compression maximale compression = "bzip2" compression-level = 9 # utiliser debian/patches/debian-changes comme correctif automatique single-debian-patch # ignorer les modifications dans config.{sub,guess} extend-diff-ignore = "(^|/)(config.sub|config.guess)$"
Note : les options de format ne sont pas acceptées dans ce fichier. Vous devriez utiliser debian/source/format à la place.
Identique à debian/source/options mais n'est pas enregistré dans le paquet source créé. Ce fichier peut être utile pour conserver une préférence propre au responsable ou au dépôt de gestionnaire de versions où le paquet source est géré.
Texte en format libre qui sera ajouté au début du correctif automatique créé dans les formats « 2.0 » et « 3.0 (quilt) ». local-patch-header n'est pas inclus dans le paquet source créé alors que patch-header l'est.
Ce fichier comporte la liste de toutes les correctifs qui ont été appliqués (dans l'ordre indiqué) aux sources amont. Les espaces situées avant et après les noms sont ignorées. L'argument distributeur sera le nom en minuscules du distributeur ou debian si aucun distributeur n'est défini. Si le fichier de séries propre au distributeur n'existe pas, le fichier de séries sans distributeur sera utilisé. Les lignes commençant par « # » sont des commentaires et sont ignorées, ainsi que les lignes vides. Les autres lignes débutent par le nom du fichier de correctifs (relatif au répertoire debian/patches/) et se terminent à la première espace ou à la fin de la ligne. Des options facultatives de quilt peuvent être ajoutées jusqu'à la fin de la ligne ou jusqu'au premier caractère « # » précédé par une ou plusieurs espaces (ce qui indique le début d'un commentaire se terminant à la fin de la ligne).
Le moment où se déroule le remplacement d'un champ par rapport à certaines déterminations de champ affichées sur la sortie standard est plutôt embrouillé.
deb-src-control(5), deb-changelog(5), deb-substvars(5), dsc(5).
Ariel VARDI <ariel.vardi@freesbee.fr>, 2002. Philippe Batailler, 2006. Nicolas François, 2006. Veuillez signaler toute erreur à <debian-l10n-french@lists.debian.org>.
2023-05-11 | 1.21.22 |