uscan
Tester ou surveiller la disponibilité d’une nouvelle version amont
- Provided by: devscripts (Version: 2.26.7)
- Report a bug
Tester ou surveiller la disponibilité d’une nouvelle version amont
uscan [options] [chemin]
Pour une utilisation basique, uscan est exécuté sans aucun paramètre à partir de la racine d’une arborescence source debianisée où on voit le répertoire debian/ ou un répertoire contenant plusieurs arborescences sources.
Sauf si --watchfile est indiqué, uscan recherche récursivement les arborescences source valides en partant du répertoire courant (voir la section "Vérification du nom du répertoire" ci-dessous pour plus de détails).
Pour chaque arborescence valide trouvée, typiquement la séquence est la suivante :
Veuillez noter les informations suivantes.
Le format actuel de debian/watch est décrit dans la page de manuel debian-watch(5). Les formats précédents (versions 1 à 4) le sont dans la page debian-watch-4(5).
Pour convertir un fichier version <= 4 dans la dernière version, utiliser simplement:
uscan --update-watchfile
et examiner le résultat.
Voici un exemple de fichier debian/copyright qui déclenche le rempaquetage automatique de l’archive amont en <spkg>_<oversion>.orig.tar.gz (dans debian/copyright, les alinéas Files-Excluded et Files-Excluded-component font partie du premier paragraphe et il existe un ligne vide avant les paragraphes suivants qui contiennent Files et d’autres alinéas.) :
Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/ Files-Excluded: exclude-this exclude-dir */exclude-dir .* */js/jquery.js Files: * Copyright: ... ...
Voici un autre exemple de fichier debian/copyright qui déclenche le rempaquetage automatique d’archives amont multiples en <spkg>_<oversion>.orig.tar.gz et <spkg>_<oversion>.orig-bar.tar.gz:
Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/ Files-Excluded: exclude-this exclude-dir */exclude-dir .* */js/jquery.js Files-Excluded-bar: exclude-this exclude-dir */exclude-dir .* */js/jquery.js Files: * Copyright: ... ...
Le fichier debian/copyright peut également contenir des entrées Files-Included et Files-Included-component qui ré-incluent des fichiers précédemment exclus. C'est pratique pour exclure un répertoire à l'exception de quelques fichiers :
Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/ Files-Excluded: vendor-dir Files-Included: vendor-dir/directory/to/keep vendor-dir/*/file-to-keep Files: * Copyright: ... ...
Voir mk-origtargz(1).
Supposons que la "clef de test d’uscan (non secrète) <none@debian.org>" amont signe son paquet avec une clef secrète OpenPGP et publie la clef publique OpenPGP correspondante. Cette clef publique OpenPGP peut être identifiée de trois façons différentes avec sa forme hexadécimale.
Compte tenu de l’existence des attaques par collisions sur les identificateurs courts, il est recommandé d’utiliser l’identificateur long pour recevoir des clefs à partir des serveurs de clefs publiques. Vous devez vérifier la clef OpenPGP téléchargée en utilisant la valeur de son empreinte complète dont vous savez qu’elle est sûre.
Le fichier de trousseau blindé debian/upstream/signing-key.asc peut être créé en utilisant la commande gpg comme suit.
$ gpg --recv-keys "C77E2D6872543FAF"
...
$ gpg --finger "C77E2D6872543FAF"
pub 4096R/72543FAF 2015-09-02
Key fingerprint = CF21 8F0E 7EAB F584 B7E2 0402 C77E 2D68 7254 3FAF
uid uscan test key (no secret) <none@debian.org>
sub 4096R/52C6ED39 2015-09-02
$ cd chemin/vers/<upkg>-<uversion>
$ mkdir -p debian/upstream
$ gpg --export --export-options export-minimal --armor \
'CF21 8F0E 7EAB F584 B7E2 0402 C77E 2D68 7254 3FAF' \
>debian/upstream/signing-key.asc
Les fichiers de trousseau binaires, debian/upstream/signing-key.pgp et debian/upstream-signing-key.pgp, sont encore gérés, mais ils sont obsolètes.
Si un groupe de développeurs signe le paquet, il faut la liste des empreintes de chacun d’entre eux dans le paramètre pour gpg --export ... afin que le trousseau contienne toutes leurs clefs OpenPGP.
Parfois, on se demande qui a créé le fichier de signature. Il est possible d’obtenir l’identificateur de la clef publique utilisé pour créer le fichier de signature séparé toto-2.0.tar.gz.asc en exécutant gpg ainsi :
$ gpg -vv toto-2.0.tar.gz.asc
gpg: armor: BEGIN PGP SIGNATURE
gpg: armor header: Version: GnuPG v1
:signature packet: algo 1, keyid C77E2D6872543FAF
version 4, created 1445177469, md5len 0, sigclass 0x00
digest algo 2, begin of digest 7a c7
hashed subpkt 2 len 4 (sig created 2015-10-18)
subpkt 16 len 8 (issuer key ID C77E2D6872543FAF)
data: [4091 bits]
gpg: assuming signed data in `toto-2.0.tar.gz'
gpg: Signature made Sun 18 Oct 2015 11:11:09 PM JST using RSA key ID 72543FAF
...
Pour un usage basique d’uscan, la configuration de ces options n’est pas nécessaire.
uscan --conf-file test.conf --verbose
uscan --conf-file +test.conf --verbose
Si l’un des --conf-file ne contient pas de "+", les fichiers de configuration par défaut sont ignorés.
Des archives précédemment téléchargées peuvent être utilisées.
Passage du comportement par défaut à --skip-signature.
Passage du comportement par défaut à --no-download et --skip-signature.
Quand l’objectif de l’exécution de uscan est de recueillir l’état du paquet amont sous un environnement conscient de la sécurité, veuillez vous assurer d’utiliser cette option.
Ce qui précède est vrai non seulement pour l’exécution unique d’uscan dans une arborescence de sources unique, mais aussi pour l’exécution par uscan d’une recherche avancée dans des sous-répertoires contenant plusieurs arborescences de sources.
Une exception existe quand les options --watchfile et --package sont utilisées ensemble. Dans ce cas, le répertoire courant interne d’exécution d’uscan et le répertoire de destination par défaut sont définis au répertoire courant . où uscan est lancé. Le répertoire de destination par défaut peut être remplacé en définissant aussi l’option --destdir.
Une exception existe quand les options --watchfile et --package sont utilisées ensemble. uscan peut être appelé à partir de n’importe quel répertoire et le répertoire courant interne d’exécution d’uscan et le répertoire de destination par défaut sont définis au répertoire courant . où uscan est lancé.
Vous trouverez plus d’informations dans l’explication de --destdir.
uscan --http-header https://example.org@My-Token=azertyuiop
Sécurité :
| valeur --http-header | Bonne pour | Inutilisée |
+------------------------------------+-----------------------------+------------+
| https://example.org.com@Hdr=Value | https://example.org.com/... | |
| https://example.org.com/@Hdr=Value | | X |
| https://e.com:1879@Hdr=Value | https://e.com:1879/... | |
| https://e.com:1879/dir@Hdr=Value | https://e.com:1879/dir/... | |
| https://e.com:1879/dir/@Hdr=Value | | X |
uscan accepte aussi les options suivantes et les passe à mk-origtargz :
Le paquet unzip doit être installé pour réempaqueter les archives zip, jar et xpi, le paquet xz-utils pour les archives tar compressées avec lzma ou xz, le paquet zstd pour les archives zstd et le paquet lzip pour les archives lz tar.
Pour une utilisation de base d’uscan, la configuration de ces variables n’est pas nécessaire.
Les deux fichiers de configuration /etc/devscripts.conf et ~/.devscripts sont évalués dans cet ordre par un interpréteur de commandes ("shell") pour placer les variables de configuration. Des options de ligne de commande peuvent être utilisées pour neutraliser les paramètres des fichiers de configuration. Les paramètres des variables d’environnement sont ignorés à cette fin. Si la première option donnée en ligne de commande est --noconf, alors ces fichiers ne sont pas évalués. Les variables actuellement identifiées sont :
Le code de retour indique si une nouvelle version a été trouvée ; il est conseillé de lire la sortie pour déterminer exactement ce qui s’est passé et pour voir s’il n’y a pas eu d’avertissement.
uscan possède beaucoup d’autres fonctionnalités qui sont sautées dans la section ci-dessus, pour être plus simple. Regardons leurs points marquants.
uscan peut être exécuté avec chemin comme paramètre pour passer le répertoire de départ de recherche du répertoire courant à chemin.
Si vous ne savez pas exactement ce qui se passe dans les coulisses, veuillez activer l’option --verbose. Si ce n’est pas suffisant, activez l’option --debug pour voir toutes les actions internes.
Voir "OPTIONS DE LIGNE DE COMMANDE" et "VARIABLES DE CONFIGURATION DE DEVSCRIPT" pour d’autres variantes.
After processing other stuff uscan will run script if requested in debian/watch. Otherwise there will be no extra action.
Pour des raisons de compatibilité avec d’autres outils tels que git-buildpackage, il peut être judicieux de ne pas créer des scripts personnalisés au comportement aléatoire. En général, uupdate est le meilleur choix pour un paquet non natif, et les scripts personnalisés, s’ils existent, devraient se comporter comme uupdate. Pour des cas d’utilisation potentiels, voir <http://bugs.debian.org/748474> comme exemple.
For info on how to request this script, please see debian-watch(5) for recommended version 5 format or debian-watch-4(5) for old version 4 format.
Voir "HISTORIQUE ET MISE À NIVEAU" pour voir comment uscan invoque le <script> personnalisé.
Certains sites populaires ont changé leur structure de page web provoquant des problèmes de maintenance du fichier de veille. Des services de redirection ont été créés pour faciliter sa maintenance. Actuellement, uscan fait un détournement automatique des requêtes d’URL pour les URL suivantes afin de gérer cette situation.
Comme plusieurs autres scripts du paquet devscripts, uscan parcourt l’arborescence du répertoire demandé à la recherche de fichiers debian/changelog et debian/watch. Pour se protéger contre certains fichiers égarés qui pourraient poser problème, et pour des raisons d’efficacité, il examine le nom du répertoire parent une fois qu’il a trouvé le fichier debian/changelog, et vérifie que le nom du répertoire correspond au nom du paquet. Il ne cherchera à télécharger les nouvelles versions d’un paquet et à effectuer l’action demandée que si le nom du répertoire correspond au nom du paquet. La façon précise utilisée est contrôlée par les deux variables du fichier de configuration DEVSCRIPTS_CHECK_DIRNAME_LEVEL et DEVSCRIPTS_CHECK_DIRNAME_REGEX, et les options en ligne de commande associées --check-dirname-level et --check-dirname-regex.
DEVSCRIPTS_CHECK_DIRNAME_LEVEL peut prendre les valeurs suivantes :
Le nom du répertoire est vérifié en testant si le nom du répertoire actuel (donné par pwd(1)) correspond à l’expression rationnelle donnée par la variable DEVSCRIPTS_CHECK_DIRNAME_REGEX du fichier de configuration ou par l’option --check-dirname-regex expression_rationnelle. Il s’agit d’une expression rationnelle Perl (voir perlre(1)), qui sera ancrée à son début et à sa fin. Si elle contient un /, alors elle doit correspondre au chemin complet. Sinon, elle doit correspondre au nom de répertoire complet. Si elle contient la chaîne paquet, cette chaîne sera remplacée par le nom du paquet source déterminé par le fichier debian/changelog. La valeur par défaut de cette expression rationnelle est : paquet(-.+)?, ce qui correspond aux répertoires nommés paquet ou paquet-version.
Cette section décrit brièvement les incompatibilités inverses des fonctionnalités du fichier watch qui ont été ajoutées dans chaque version du fichier watch et la première version du paquet devscripts qui les comprenait.
Si vous êtes en train de vous mettre à niveau depuis la version 2, l’incompatibilité principale est lorsqu’il existe plusieurs groupes dans la partie des motifs. Alors que seul le premier était utilisé dans la version 2, ils le seront tous dans la version 3. Pour éviter ce comportement, modifiez les groupes non liés au numéro de version en (?: ... ) au lieu d’un groupe ordinaire ( ... ).
La syntaxe du fichier de veille est assouplie pour permettre plus d’espaces de lisibilité.
Si vous avez un script personnalisé à la place de uupdate, vous pouvez aussi rencontrer des problèmes lors de la mise à jour à partir de la version 3.
Les restrictions pour --dehs sont levées en redirigeant les autres sorties sur la sortie d’erreur standard lorsque elle est active.
dpkg(1), mk-origtargz(1), perlre(1), uupdate(1), devscripts.conf(5), debian-watch(5), debian-watch-4(5)
La version initiale de uscan a été écrite par Christoph Lameter <clameter@debian.org>. Des améliorations significatives, d’autres modifications et des corrections de bogues ont été apportées par Julian Gilbey <jdg@debian.org>. La prise en charge de HTTP a été ajouté par Piotr Roszatycki <dexter@debian.org>. Le programme a été réécrit en Perl par Julian Gilbey. Xavier Guimard l’a convertit en Perl orienté-objet en utilisant Moo.
Cyril Brulebois <cyril.brulebois@enst-bretagne.fr>, 2006
Thomas Huriaux <thomas.huriaux@gmail.com>, 2006
David Prévot <david@tilapin.org>, 2010-2013
Xavier Guimard <yadd@debian.org>, 2018-2024