Provided by: devscripts_2.25.15_all 
NOM
uscan - Tester ou surveiller la disponibilité d’une nouvelle version amont
SYNOPSIS
uscan [options] [chemin]
DESCRIPTION
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 :
• uscan lit la première entrée dans debian/changelog pour déterminer le nom du paquet source <spkg> et
la dernière version amont.
• uscan traite les lignes de veille debian/watch de haut en bas en une passe unique.
• uscan télécharge une page web à partir de l’URL spécifiée dans debian/watch.
• uscan extrait les références href pointant vers l’archive amont (ou les archives) à partir de la
page web en utilisant le motif_correspondant dans debian/watch.
• uscan télécharge l’archive amont avec la version la plus haute plus récente que la dernière
version amont.
• uscan sauvegarde l’archive téléchargée dans le répertoire parent ../ :
../<upkg>-<uversion>.tar.gz
• uscan invoque mk-origtargz pour créer l’archive source : ../<spkg>_<oversion>.orig.tar.gz
• Pour un paquet MUT ("multiple upstream tarball" - archive amont multiple), l’archive amont
secondaire sera plutôt nommée ../<spkg>_<oversion>.orig-<composante>.tar.gz.
• L’action est répétée jusqu’à ce que toutes les lignes de debian/watch soient traitées.
• uscan invoque uupdate pour créer l’arborescence source debianisée : ../<spkg>-<oversion>/*
Veuillez noter les informations suivantes.
• Pour des raisons de simplicité, la méthode de compression utilisée dans les exemples est gzip avec le
suffixe .gz. Les autres méthodes telles que xz, bzip2 et lzma, avec les suffixes xz, bz2 et lzma
correspondants peuvent également être utilisées.
• La nouvelle version=4 permet la gestion des paquets MUT, mais ce sont des cas rares parmi les paquets
Debian. Pour un paquet d’archive simple, il n’y a qu’une ligne de veille et pas de
../<spkg>_<oversion>.orig-<composante>.tar.gz .
• uscan avec l’option --verbose produit un rapport lisible de son exécution.
• uscan avec l’option --debug produit un rapport lisible de son exécution avec l’état des variables
internes.
• uscan avec l’option --extra-debug produit un rapport lisible de son exécution avec l’état des
variables internes et le contenu distant lors de la phase "recherche".
• uscan avec l’option --dehs produit un rapport d’état du paquet amont au format XML pour que d’autres
programmes tels que Debian External Health System.
• L’objectif premier d’uscan est d’aider à déterminer si c’est bien la dernière version de l’archive
amont qui est utilisée et de télécharger cette version d’archive. L’ordre des versions est déterminée
par dpkg --compare-versions.
• L’option --safe d’uscan limite ses fonctionnalités à ses objectifs premiers. À la fois le repaquetage
des fichiers téléchargés et la mise à jour de l’arborescence source sont sautés pour éviter
l’exécution de scripts non sécurisés. Cela change aussi les options par défaut à --no-download et
--skip-signature.
FORMAT DU FICHIER DE VEILLE
Le format de la version 4 actuelle de debian/watch peut être résumé comme suit :
• Les espaces et les tabulations de début sont supprimées.
• Les lignes vides sont supprimées.
• Une ligne qui débute par # (dièse) est une ligne de commentaire et elle est supprimée.
• Un \ unique (barre inverse oblique) à la fin d’une ligne est supprimé et la ligne suivante est
concaténée après la suppression des espaces et des tabulations de début. La ligne concaténée est
analysée comme une seule ligne. (L’existence ou l’inexistence d’une espace avant le \ unique final
est signifiant.)
• La première ligne non commentée est la suivante :
version=4
Il s’agit d’une ligne obligatoire et c’est le numéro de la version recommandée.
Si vous utilisez ici "version=3" à la place, certaines fonctionnalités peuvent ne pas fonctionner
comme cela est documenté ici. Voir "HISTORIQUE ET MISE À NIVEAU".
• Les lignes suivantes non commentées (lignes de veille) précisent les règles de sélection des URL
d’archive amont candidates et sont dans un des trois formats suivants :
• opts=" ... " http://URL motif_correspondant [version [script]]
• http://URL motif_correspondant [version [script]]
• opts=" ... "
Ici,
• opts=" ... " précise le comportement d’uscan. Voir "OPTIONS DE FICHIER DE VEILLE".
• http://URL précise la page web où l’amont publie le lien vers la dernière archive source.
• https://URL peut être aussi utilisé, comme peut l’être
• ftp://URL
• Certaines parties d’URL peuvent être dans le motif de correspondance d’expression rationnelle
entourées par ( et ) comme /toto/titi-([\.\d]+)/. Si plusieurs répertoires correspondent, la
version la plus élevée est choisie.) Autrement, l’URL est prise textuellement.
• motif_correspondant précise le motif de chaîne complet correspondant aux références hrefs dans la
page web. Voir "EXEMPLES DE FICHIER DE VEILLE".
• Toutes les parties correspondantes entre ( et ) sont concaténées avec un . (point) pour
former la version amont.
• Si les références href ne contiennent pas de répertoires, il est possible de les combiner
avec l’entrée précédente. C’est-à-dire, http://URL/motif_correspondant.
• version restreint le choix d’archive amont pouvant être téléchargée. La version la plus récente
disponible est choisie dans tous les cas.
• debian réclame que l’archive amont à télécharger soit plus récente que la version obtenue à
partir de debian/changelog.
• Un numéro_de_version tel que 12.5 requiert que l’archive amont soit plus récente que le
numéro_de_version.
• same requiert que la version téléchargée des archives secondaires soit exactement la même que
celle de la première archive amont téléchargée. (Utile uniquement pour les paquets MUT)
• previous limite la version du fichier de signature. (Utilisé avec pgpmode=previous)
• ignore ne limite pas la version des archives secondaires. (Peut-être utile pour les paquets
MUT)
• group réclame que l’archive amont à télécharger soit plus récente que la version obtenue à
partir de debian/changelog. La version du paquet est la concaténation de toutes les versions
amont.
• checksum exige que l’archive amont à télécharger soit plus récente que la version obtenue à
partir de debian/changelog. La version du paquet est la concaténation de la version de la
prinicpale source, suivie de la somme de contrôle de toutes les versions amont utilisant le
système de version "checksum". À minima, la source principale doit être déclarée comme
"group".
• script est exécuté à la fin de l’exécution d’uscan avec les paramètres appropriés fournis par
uscan (défaut: pas d’action).
• Le paquet Debian typique est un paquet non natif fait à partir d’une archive amont. Seulement
une ligne unique du fichier de veille dans un des deux premiers formats est habituellement
utilisée avec sa version réglée à debian et script réglé à uupdate.
• Un paquet natif ne devrait pas spécifier de script.
• Un paquet MUT ("multiple upstream tarball" – archive amont multiple) devrait indiquer uupdate
comme script dans la dernière ligne de veille et ne devrait pas indiquer de script dans le
reste des lignes de veille.
• Le dernier format des lignes de veille est utile pour configurer des paramètres permanents :
user-agent, compression. Si ce format est utilisé, ces paramètres doivent être suivis de la (ou
des) lignes(s) de veille définissant l’URL.
• [and] dans le format ci-dessus sont ici pour marquer les parties optionnelles et ne devraient pas
être tapées.
Il y a quelques chaînes spéciales qui sont remplacées par uscan pour faciliter l’écriture du fichier de
veille.
@PACKAGE@
Cette chaîne est remplacée par le nom de paquet source trouvé dans la première ligne du fichier
debian/changelog.
@ANY_VERSION@
Cette chaîne est remplacée par l’expression rationnelle de la version amont légale (capture).
[-_]?[Vv]?(\d[\-+\.:\~\da-zA-Z]*)
@ARCHIVE_EXT@
Cette chaîne est remplacée par l’expression rationnelle de l’extension habituelle de fichier
d’archive (sans capture).
(?i)(?:\.(?:tar\.xz|tar\.bz2|tar\.gz|tar\.zstd?|zip|tgz|tbz|txz))
@SIGNATURE_EXT@
Cette chaîne est remplacée par l’expression rationnelle de l’extension habituelle de fichier de
signature (sans capture).
(?i)(?:\.(?:tar\.xz|tar\.bz2|tar\.gz|tar\.zstd?|zip|tgz|tbz|txz))'(?:\.(?:asc|pgp|gpg|sig|sign))'
@DEB_EXT@
Cette chaîne est remplacée par l’expression rationnelle de habituelle de Debian (sans capture).
[\+~](debian|dfsg|ds|deb)(\.)?(\d+)?$
Certaines extensions de fichiers ne sont volontairement pas incluses dans la liste précédente pour éviter
des faux positifs. Il vous est encore possible de rajouter ces motifs d’extension de fichier
manuellement.
OPTIONS DE FICHIER DE VEILLE
uscan lit les options de veille spécifiées dans opts=" ... " pour personnaliser son comportement. De
multiples options option1, option2, option3, ..., peuvent être configurées de cette manière :
opts="option1, option2, option3, ... ". Les guillemets doubles sont nécessaires si les options
contiennent des espaces.
À moins qu’elles ne soient notées par ailleurs comme persistantes, la plupart des options ne sont
valables que dans la ligne de veille qui les contient.
Les options de veille disponibles sont :
component=composante
Configurer le nom de l’archive source secondaire comme <spkg>_<oversion>.orig-<composante>.tar.gz
pour un paquet MUT.
ctype=component-type
Indique le type du composant (seuls "nodejs" et "perl" sont disponible actuellement). Ceci aide uscan
à trouver la version courante si la version du composant est ignorée.
Lorsque ctype=nodejs est utilisé, uscan recherche une version dans "package.json", lorsque ctype=perl
est utilisé, uscan recherche une version dans "META.json". Si une version est trouvée, elle est
utilisée comme version courante du composant, en ignorant la version trouvée dans la chaîne de
version de Debian. Ceci permet une meilleure détection des changements lorsque ignore ou checksum
sont utilisés dans la version Debian.
compression=méthode
Configurer la méthode de compression quand l’archive est rempaquetée (persistant).
Les valeurs de méthode disponibles sont xz, gzip (alias gz), bzip2 (alias bz2) lzma et default. La
valeur par défaut est xz. Lorsque uscan est lancé dans un répertoire source Debian et que le format
est "1.0" ou n’est pas défini, la méthode par défaut devient gzip.
Veuillez noter que le rempaquetage des archives amont par mk-origtargz ne se produit que si une des
conditions suivantes est satisfaite :
• USCAN_REPACK est configuré dans la configuration de devscript. Voir "VARIABLES DE CONFIGURATION
DE DEVSCRIPT".
• --repack est configuré en ligne de commande. Voir <OPTIONS DE LIGNE DE COMMANDE>.
• repack est configuré sur la ligne de veille de cette manière : opts="repack,...".
• L’archive amont est de type zip, y compris jar, xpi, ...
• L’archive amont est de type zstdi (Zstandard).
• Les alinéas Files-Excluded ou Files-Excluded-composante sont configurés dans debian/copyright
pour que mk-origtargz invoqué à partir d’uscan supprime les fichiers de l’archive amont et la
rempaquette. Voir "EXEMPLES DE FICHIER DE COPYRIGHT" et mk-origtargz(1).
repack
Forcer le rempaquetage de l’archive amont avec la méthode de compression.
repacksuffix=suffixe
Ajouter un suffixe à la version du paquet Debian amont seulement lorsque l’archive source est
rempaquetée. Cette règle peut être utilisée seulement pour un unique paquet d’archive amont.
mode=mode
Configurer le mode de téléchargement de l’archive.
LWP Il s’agit du mode par défaut qui télécharge l’archive spécifiée à partir de l’URL sur le web. La
valeur interne mode est automatiquement mise à jour soit vers http soit vers ftp d’après l’URL.
git Ce mode accède directement à l’archive git amont avec la commande git et empaquette
l’arborescence source avec l’étiquette spécifiée par motif_correspondant dans spkg-
version.tar.xz.
Si l’amont fournit l’archive publiée au travers de son interface web, veuillez utiliser celle-ci
plutôt que ce mode. Ce mode est le dernier recours.
Dans le mode git, motif_correspondant spécifie le motif correspondant complet de la chaîne pour
les étiquettes au lieu des références href. Si motif_correspondant est réglé à
refs/tags/étiquette-motif_correspondant, uscan télécharge le fichier source à partir de
refs/tags/étiquette-correspondante du dépôt git. La version amont est extraite en concaténant les
parties correspondantes de ( ... ) avec .. Voir "EXEMPLES DE FICHIER DE VEILLE".
Si motif_correspondant est réglé à HEAD, uscan télécharge le fichier source à partir du HEAD du
dépôt git et la version pertinente est automatiquement générée avec la date et l’empreinte du
HEAD du dépôt git.
Si motif_correspondant est réglé à heads/branche, uscan télécharge le fichier source à partir de
la branche spécifiée du dépôt git.
Le dépôt local est créé temporairement soit comme un dépôt git brut soit comme un dépôt git cloné
si gitmodules est spécifié. L’archive est ensuite générée depuis le dépôt temporaire et
enregistrée dans le répertoire de destination.
Le dépôt temporaire est normalement effacé après l’exécution de uscan mais est conservé si
l’option --debug est spécifiée.
Si le répertoire courant est un dépôt git et si le dépôt recherché est listé dans les sources
amont ("remote"), alors uscan l’utilisera au lieu de dupliquer le dépôt dans un répertoire
temporaire. Le seul changement dans le répertoire local est une mise à jour ("fetch").
svn Ce mode accède directement à l’archive Subversion amont avec la commande svn et empaquette
l’arborescence source.
Dans le mode svn, motif_correspondant spécifie le motif correspondant complet de la chaîne pour
les répertoires su dépôt Subversion. La version amont est extraite en concaténant les parties
correspondantes de ( ... ) avec ..
Si motif_correspondant est réglé à HEAD, uscan télécharge la dernière arborescence source de
l’URL. La version amont est ensuite construite en ajoutant la dernière révision de l’URL à
0.0~svn.
Comme la signature des commits n’est pas possible avec Subversion, pgpmode est mis d’office à
none lorsque mode=svn. Les valeurs de pgpmode autres que default et none affichent des erreurs.
pretty=règle
Configurer la chaîne de version amont à un format arbitraire comme un argument optionnel de opts
quand le motif_correspondant est HEAD ou heads/branch pour le mode git. Pour connaître la syntaxe
exacte, voir la page de manuel de git-log avec tformat. Le format par défaut est
pretty=0.0~git%cd.%h. Aucune règle uversionmangle n’est applicable dans ce cas.
Lorsque pretty=describe est utilisé, la chaîne de version amont est la sortie de la commande "git
describe --tags | sed s/-/./g". Par exemple, si l’envoi (commit) est le cinquième après la dernière
étiquette v2.17.12 et son empreinte courte est ged992511, alors, la chaîne est v2.17.12.5.ged992511.
Dans ce cas, c’est une bonne idée d’ajouter uversionmangle=s/^/0.0~/ ou uversionmangle=s/^v// pour
rendre la chaîne de la version amont compatible avec Debian. Veuillez noter qu’afin que
pretty=describe fonctionne bien, l’amont doit éviter d’étiqueter avec des étiquettes alphabétiques
aléatoires.
L’option pretty=describe contraint à configurer gitmode=full pour créer automatiquement un clone
local complet du dépôt.
date=règle
Configurer la chaîne de date utilisée par l’option pretty à un format arbitraire comme un paramètre
optionnel de opts quand le motif_correspondant est HEAD ou heads/branch pour le mode git. Pour
connaître la syntaxe exacte, voir la page de manuel strftime. Le format par défaut est date=%Y%m%d.
gitexport=mode
Indiquer le mode d’opération d’un export d’archive git. La valeur par défaut est gitexport=default.
Positionner à gitexport=all pour inclure tous les fichiers dans l’archive .orig.tar, en ignorant tous
les attributs git export-ignore définis par le projet amont. Cette option s’applique également aux
sous-modules si gitmodules est spécifié.
Cette option n’est valable qu’en mode "git".
gitmode=mode
Configurer le mode de l’opération git clone. La valeur par défaut est gitmode=shallow. Pour certains
serveurs git simples ("dumb"), il peut être nécessaire de configurer soi-même la valeur gitmode=full
pour imposer une opération de clonage complète.
Si le répertoire courant est un dépôt git et si le dépôt recherché est listé dans les sources amont
("remote"), alors uscan l’utilisera au lieu de dupliquer le dépôt dans un répertoire temporaire.
gitmodules[=modules]
Cloner un ou plusieurs sous-modules après avoir cloné le dépôt principal. Par défaut, uscan clone
tous les sous-modules liés au dépôt git.
Pour cloner une sélection de sous-modules, utiliser une liste dont les éléments sont séparés par des
points-virgules. Par exemple : gitmodules=m4;doc/common.
pgpmode=mode
Configurer le mode de vérification de signature OpenPGP.
auto
uscan vérifie les URL possibles pour le fichier de signature et génère automatiquement une règle
pgpsigurlmangle pour l’utiliser.
default
Utiliser pgpsigurlmangle=règles pour créer la chaîne d’URL du fichier de signature amont candidat
à partir de l’URL de l’archive amont. (Par défaut)
Si le pgpsigurlmangle spécifié est manquant, uscan vérifie les URL possible pour le fichier de
signature et suggère l’ajout d’une règle pgpsigurlmangle.
mangle
Utiliser pgpsigurlmangle=règles pour créer la chaîne d’URL du fichier de signature amont candidat
à partir de l’URL de l’archive amont.
next
Vérifier ce fichier d’archive téléchargé avec le fichier de signature spécifié dans la ligne de
veille suivante. La ligne de veille suivante doit être pgpmode=previous. Autrement, aucune
vérification n’est effectuée.
previous
Vérifier le fichier d’archive téléchargé spécifié dans la ligne de veille précédente avec ce
fichier de signature. La ligne de veille précédente doit être pgpmode=next.
self
Vérifier le fichier toto.ext téléchargé avec sa propre signature et extraire son fichier archive
de contenu en toto.
gittag
Vérifie la signature du tag si mode=git.
none
Pas de signature disponible. (Pas d’alerte.)
searchmode=mode
Configurer le mode de recherche.
html (défaut)): recherche l’expression dans les paramètres "href" des tags HTML <a>
plain: recherche l’expression dans la page entière
C’est utile si le contenu de la page n’est pas au format HTML mais au format JSON. Exemple avec
npmjs.com :
version=4
opts="searchmode=plain" \
https://registry.npmjs.org/aes-js \
https://registry.npmjs.org/aes-js/-/aes-js-(\d[\d\.]*)@ARCHIVE_EXT@
decompress
Décompresser l’archive compressée avant la vérification de la signature OpenPGP.
bare
Désactiver tout le code spécifique au site de cas particuliers tels que les utilisations de
redirecteur d’URL et les altérations de contenu de page. (Persistant)
user-agent=chaîne_user-agent
Configurer la chaîne user-agent utilisée pour contacter le serveur HTTP(S) comme chaîne_user-agent.
(Persistant)
L’option user-agent devrait être précisée par elle-même dans la ligne de veille sans URL, pour
permettre l’utilisation de point-virgules et de virgules.
pasv, passive
Utiliser le mode passif ("PASV") pour les connexions FTP.
Si le mode PASV (passif) est requis à cause de l’environnement réseau côté client, configurer uscan
pour qu’il utilise le mode PASV avec les "OPTIONS DE LIGNE DE COMMANDE" ou plutôt avec les "VARIABLES
DE CONFIGURATION DE DEVSCRIPT".
active, nopasv
Ne pas utiliser le mode PASV (passif) pour les connexions FTP.
unzipopt [options]
Ajouter les options supplémentaires à utiliser avec la commande unzip telles que -a, -aa et -b lors
de l’exécution par mk-origtargz.
dversionmangle=règles
Normaliser la dernière chaîne de version amont trouvée dans debian/changelog pour la comparer avec la
version de l’archive amont disponible. Le retrait de suffixes spécifiques à Debian tels que
s/\+dfsg\d*$// est habituellement réalisé à ce moment là.
Il est également possible d’utiliser dversionmangle=auto, ce qui est exactement la même chose que
dversionmangle=s/@DEB_EXT@//
dirversionmangle=règles
Normaliser la chaîne du chemin du répertoire correspondant à l’expression rationnelle dans un jeu de
parenthèses de l’adresse http://URL comme chaîne d’index pour trier par version. Ce n’est utilisé que
pour trier les chemins de répertoire.
Une substitution telle que s/PRE/~pre/; s/RC/~rc/ peut aider.
pagemangle=règles
Normaliser la chaîne de page web téléchargée. (À n’utiliser qu’en cas de nécessité absolue. En
général, l’étiquette g est requise pour ces règles.)
Cela est pratique si vous souhaitez accéder à Amazon AWS ou à des dépôts Subversion dans lesquels <a
href="..."> n’est pas utilisé.
uversionmangle=règles
Normaliser les chaînes de version amont candidate extraites des références href dans le code source
de la page web. Cela est utilisé comme l’index de tri de version lors de la sélection de la dernière
version amont.
Une substitution telle que s/PRE/~pre/; s/RC/~rc/ peut aider.
versionmangle=règles
Il s’agit d’un raccourci syntaxique pour uversionmangle=règles,dversionmangle=règles
hrefdecode=percent-encoding
Convertir la chaîne des références href de l’archive amont sélectionnée de la chaîne hexadécimale
encodée en pourcent vers la chaîne décodée de l’URL normale pour les sites web embrouillés. Seul
percent-encoding est disponible et est décodé avec l’instruction s/%([A-Fa-f\d]{2})/chr hex $1/eg.
downloadurlmangle=règles
Convertir la chaîne des références href de l’archive amont sélectionnée dans l’URL accessible des
sites web embrouillés. L’exécution intervient après hrefdecode.
filenamemangle=règles
Générer le nom de fichier de l’archive amont à partir de la chaîne des références href sélectionnée
si motif_correspondant peut extraire l’<uversion> de la dernière version amont à partir de la chaîne
des références href sélectionnée. Autrement, générer le nom de fichier de l’archive amont à partir de
la chaîne de l’URL complète et configurer l’<uversion> manquant à partir du nom de fichier de
l’archive amont généré.
Sans cette option, le nom de fichier de l’archive amont par défaut est généré en prenant la dernière
composante de l’URL et en retirant tout ce qui est après un "?" ou un "#".
pgpsigurlmangle=règles
Générer la chaîne d’URL du fichier de signature amont candidat à partir de l’URL de l’archive amont.
oversionmangle=règles
Générer la chaîne de version <oversion> de l’archive source <spkg><spkg>_<oversion>.orig.tar.gz à
partir de <uversion>. Cela devrait être utilisé pour ajouter un suffixe tel que +dfsg à un paquet
MUT.
Ici, les règles de manipulation appliquent les règles à la chaîne pertinente. De multiples règles peuvent
être précisées dans une chaîne de règle de manipulation en créant une chaîne concaténée de chaque règle
de manipulation séparée par des ; (point-virgule).
Les règles de manipulation ne peuvent pas comporter de ; (point-virgule), , (virgule) ni de " (guillemet
double).
Chaque règle de manipulation se comporte comme si une commande Perl "$string =~ règle" était exécutée. Il
y a quelques particularités notables.
• Une règle peut seulement utiliser les opérations s, tr et y.
s/expression_rationnelle/remplacement/options
Rechercher la correspondance du motif d’expression rationnelle et remplacer la chaîne cible. Les
étiquettes g, i et x sont les seules disponibles. Utiliser la syntaxe $1 pour des références
arrières (pas de syntaxe \1). L’exécution de code n’est pas permise (c’est-à-dire pas de
constructions (?{}) ou (??{})).
y/source/dest/ ou tr/source/dest/
Translittérer les caractères de la chaîne cible.
EXEMPLE D’EXÉCUTION
uscan lit la première entrée dans debian/changelog pour déterminer le nom du paquet source et la dernière
version amont.
Par exemple, si la première entrée de debian/changelog est :
• titi (3:2.03+dfsg-4) unstable; urgency=low
alors, le nom du paquet source est titi et la version la plus récente du paquet Debian est 3:2.03+dfsg-4.
La dernière version amont est normalisée à 2.03+dfsg en retirant l’epoch et la révision Debian.
Si la règle dversionmangle existe, la dernière version amont est normalisée plus profondément en lui
appliquant cette règle. Par exemple, si la dernière version amont est 2.03+dfsg indiquant que l’archive
source a été rempaquetée, le suffixe +dfsg est retiré par la substitution de chaîne s/\+dfsg\d*$// pour
produire la dernière version amont 2.03 (traitée avec dversionmangle) et est comparée aux versions
d’archive amont candidates comme 2.03, 2.04, ..., qui se trouvent sur le site distant. Donc, configurer
la règle ainsi :
• opts="dversionmangle=s/\+dfsg\d*$//"
uscan télécharge une page web à partir de l’adresse http://URL spécifiée dans debian/watch.
• Si la partie nom du répertoire de l’URL n’a pas de parenthèse, ( et ), il est pris tel quel.
• Si la partie nom du répertoire de l’URL a des parenthèses ( et ), alors uscan cherche de façon
récursive tous les répertoires possibles pour trouver une page avec la nouvelle version. Si la règle
dirversionmangle existe, l’index de tri généré est utilisé pour trouver la version la plus récente.
Si une version particulière est spécifiée pour le téléchargement, la chaîne de version correspondante
a la priorité sur la version la plus récente.
Par exemple, cette adresse http://URL peut être spécifiée ainsi :
• http://www.example.org/@ANY_VERSION@/
Veuillez noter le / final dans l’adresse ci-dessus pour faire de @ANY_VERSION@ le répertoire.
Si la règle pagemangle existe, la totalité de la page web téléchargée, considérée comme une chaîne, est
normalisée en y appliquant la règle. C’est un outil très puissant qui doit être utilisé avec prudence. Si
d’autres règles de manipulation peuvent être utilisées pour répondre à vos objectifs, n’utilisez pas
cette règle.
Des références href, définies dans l’étiquette <a href=" ... ">, sont recherchées dans la page web
téléchargée pour localiser les références de l’archive amont candidate. Ces références de l’archive amont
candidate sont sélectionnées par le motif d’expression rationnelle Perl motif-correspondant, tel que
DL-(?:[\d\.]+?)/toto-(.+)\.tar\.gz pour réduire le nombre de candidates. Ce motif de sélection doit être
borné au début et à la fin. Par exemple, les références candidates peuvent être :
• DL-2.02/toto-2.02.tar.gz
• DL-2.03/toto-2.03.tar.gz
• DL-2.04/toto-2.04.tar.gz
Ici, la chaîne de sélection (.+) dans motif-correspondant est considérée comme la version amont
candidate. S’il y a plusieurs chaînes correspondantes de motifs de capture dans motif-correspondant,
elles sont toutes concaténées avec un point (.) pour former la version amont candidate. Il convient de
s’assurer d’utiliser des expressions rationnelles non capturantes telles que (?:[\d\.]+?) à la place pour
la partie correspondant à du texte variable sans rapport avec la version.
Les versions amont candidates sont alors :
• 2.02
• 2.03
• 2.04
Le nom de fichier de l’archive téléchargée est simplement fixé comme le nom de fichier dans l’URL
distante de la référence href sélectionnée.
Si la règle <uversionmangle> existe, les versions amont candidates sont normalisées en leur appliquant
cette règle. (Cette règle peut être utilisée si le schéma de la version amont ne permet pas un tri qui
identifie correctement la version la plus récente.)
La référence href de l’archive amont correspondant à la version amont candidate la plus récente (traitée
par uversionmangle), plus récente que la dernière version amont (traitée par dversionmangle) est
sélectionnée.
Si plusieurs références href d’archive amont correspondant à une version unique existent avec différentes
extensions, c’est la plus forte compression qui est choisie. (Ordre de priorité : tar.xz > tar.lzma >
tar.bz2 > tar.gz.)
Si la référence href de l’archive amont sélectionnée est une URL relative, elle est convertie en URL
absolue avec l’URL de base de la page web. Si l’étiquette <base href=" ... "> existe sur la page web, la
référence href de l’archive amont est convertie en URL absolue en utilisant plutôt l’URL de base
spécifiée dans l’étiquette de base.
Si la règle downloadurlmangle existe, la référence href de l’archive amont sélectionnée est normalisée en
lui appliquant cette règle. (Cela est utile sur certains sites avec des URL de téléchargement
embrouillées.)
Si la règle filenamemangle existe, le nom de fichier d’archive téléchargé est généré en appliquant cette
règle à la référence href sélectionnée si le motif-correspondant peut extraire la dernière version amont
<uversion> à partir de la chaîne de la référence href sélectionnée. Autrement, le nom de fichier
d’archive amont est généré à partir de sa chaîne d’URL complète et règle le <uversion> manquant à partir
du nom de fichier d’archive amont généré.
En absence de règle filenamemangle, le nom de fichier d’archive amont par défaut est généré en prenant la
dernière composante de l’URL et en retirant tout ce qu’il y a après un "?" ou un "#".
uscan télécharge l’archive amont sélectionnée dans le répertoire parent ../. Par exemple, le fichier
téléchargé peut être :
• ../toto-2.04.tar.gz
De façon générique, nous appellerons par la suite cette version 2.04 téléchargée dans l’exemple ci-dessus
sous le nom de <uversion>.
Si la règle pgpsigurlmangle existe, l’URL du fichier de signature amont est générée en appliquant cette
règle à la référence href de l’archive amont sélectionnée (traitée par downloadurlmangle) et on tente de
télécharger le fichier de signature à partir de cette URL.
Si la règle pgpsigurlmangle n’existe pas, uscan prévient l’utilisateur si le fichier de signature amont
correspondant est disponible à partir de la même URL, en ajoutant à son nom de fichier les cinq suffixes
courants asc, sig, sign, pgp et gpg. (On peut éviter cet avertissement avec le réglage pgpmode=none.)
Si le fichier de signature est téléchargé, l’authenticité de l’archive amont téléchargée est vérifiée par
rapport au fichier de signature téléchargé en utilisant le trousseau blindé
debian/upstream/signing-key.asc. (Voir "EXEMPLES DE FICHIER DE TROUSSEAU"). Si la signature n’est pas
valable, ou si la clef ne fait pas partie du trousseau, uscan signalera une erreur.
Si la règle oversionmangle existe, la version d’archive source oversion est générée à partir de la
version amont téléchargée uversion en appliquant cette règle. Elle est utile pour ajouter un suffixe tel
que +dfsg à la version de tous les paquets source du paquet MUT pour lequel le mécanisme de suffixe de
rempaquetage ne fonctionne pas.
uscan invoque mk-origtargz pour créer l’archive source nommée correctement pour le paquet source avec
.orig. (ou .orig-<component>. pour les archives secondaires) dans son nom de fichier.
cas A : empaquetage de l’archive amont telle quelle
mk-origtargz crée un lien symbolique ../titi_<oversion>.orig.tar.gz avec l’archive locale amont
téléchargée. Ici, << titi >> est le nom du paquet source trouvé dans debian/changelog. Le lien
symbolique généré peut être :
• ../titi_2.04.orig.tar.gz -> toto-2.04.tar.gz (tel quel)
Habituellement, il n’y a pas besoin de paramétrer opts="dversionmangle= ... " dans ce cas.
cas B : empaquetage de l’archive amont après le retrait des fichiers non-DFSG
mk-origtargz vérifie le motif générique ("glob") des noms de fichiers du paragraphe Files-Excluded
dans la première section de debian/copyright, retire les fichiers correspondants pour créer une
archive amont rempaquetée. Normalement, l’archive amont rempaquetée est renommée en
../bar_<oversion><suffixe>.orig.tar.gz avec suffixe, utilisant l’option repacksuffix pour le seul
paquet amont. Ici, <oversion> est mis à jour en <oversion><suffixe>.
Le retrait des fichiers est requis si les fichiers ne sont pas compatibles avec DFSG. Dans ce cas,
+dfsg est utilisé comme suffixe.
Alors, les options sont plutôt ainsi combinées opts="dversionmangle=s/\+dfsg\d*$// ,
repacksuffix=+dfsg".
Par exemple, l’archive amont rempaquetée peut être :
• ../titi_2.04+dfsg.orig.tar.gz (rempaqueté)
uscan invoque normalement "uupdate --find --upstream-version oversion" pour le fichier de veille
version=4.
Veuillez noter que l’option --find est ici utilisée dans la mesure où mk-origtargz a déjà été invoquée
pour construire le fichier *.orig.tar.gz. uscan choisit bar à partir de debian/changelog.
Il crée la nouvelle arborescence source amont sous le répertoire ../bar-<oversion> et l’adapte à Debian
en exploitant le contenu du dernier paquet.
EXEMPLES DE FICHIER DE VEILLE
Lors de l’écriture du fichier de veille, vous devriez vous servir de la dernière page d’annonce web de la
source amont. Vous ne devriez pas, si possible, essayer de deviner la structure de l’archive amont. Voici
des fichiers debian/watch typiques.
Veuillez noter que l’exécution de uscan avec -v ou -vv révèle ce qui se passe précisément en interne.
L’existence ou l’absence d’une espace avant le \ ("back slash") final est significatif.
Certaines chaînes de configuration plus courtes non documentées sont utilisées dans les EXEMPLES ci-
dessous pour faciliter votre saisie. Elles sont intentionnelles. uscan est écrit pour accepter de telles
abréviations de bon sens, mais il ne faut pas exagérer.
Site HTTP (de base)
Voici un exemple d’archive amont simple basique.
version=4
http://example.com/~user/release/@PACKAGE@.html \
files/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@
Ou sans utiliser les chaînes de substitution (non recommandé):
http://example.com/~user/release/foo.html \
files/foo-([\d\.]+)\.tar\.gz
version=4
Pour le paquet source amont toto-2.0.tar.gz, ce fichier de veille télécharge et crée le fichier orig.tar
Debian toto_2.0.orig.tar.gz.
Site HTTP (pgpsigurlmangle)
Voici un exemple d’archive amont simple de base avec le fichier de signature correspondant dans le même
chemin de fichier.
version=4
opts="pgpsigurlmangle=s%$%.asc%" http://example.com/release/@PACKAGE@.html \
files/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@
Pour le paquet source amont toto-2.0.tar.gz et le fichier de signature amont toto-2.0.tar.gz.asc, ce
fichier de veille télécharge ces fichiers, vérifie l’authenticité avec le trousseau
debian/upstream/signing-key.asc et crée le fichier orig.tar Debian toto_2.0.orig.tar.gz.
Voici un autre exemple d’archive amont simple de base avec le fichier de signature correspondant sur
l’archive décompressée dans le même chemin de fichier.
version=4
opts="pgpsigurlmangle=s%@ARCHIVE_EXT@$%.asc%,decompress" \
http://example.com/release/@PACKAGE@.html \
files/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@
Pour le paquet source amont toto-2.0.tar.gz et le fichier de signature amont toto-2.0.tar.asc, ce fichier
de veille télécharge ces fichiers, vérifie l’authenticité avec le trousseau
debian/upstream/signing-key.asc et crée le fichier orig.tar Debian toto_2.0.orig.tar.gz.
Site HTTP (pgpmode = next/previous)
Voici un exemple d’archive amont simple basique avec le fichier de signature correspondant dans un chemin
de fichier indépendant.
version=4
opts="pgpmode=next" http://example.com/release/@PACKAGE@.html \
files/(?:\d+)/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@ debian
opts="pgpmode=previous" http://example.com/release/@PACKAGE@.html \
files/(?:\d+)/@PACKAGE@@ANY_VERSION@@SIGNATURE_EXT@ previous
La partie (?:\d+) peut être une valeur aléatoire. Le fichier d’archive peut avoir la valeur 53, alors que
le fichier de signature peut avoir la valeur 33.
La partie ([\d\.]+) pour le fichier de signature est soumise à l’exigence stricte de correspondre à cela
pour l’archive amont spécifiée dans la ligne précédente en ayant previous comme version dans la ligne de
veille.
Site HTTP (flexible)
Voici un exemple pour une extrême flexibilité des extensions de l’archive amont et du fichier de
signature.
version=4
opts="pgpmode=next" http://example.com/DL/ \
files/(?:\d+)/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@ debian
opts="pgpmode=previous" http://example.com/DL/ \
files/(?:\d+)/@PACKAGE@@ANY_VERSION@@SIGNATURE_EXT@ \
previous
Site HTTP (MUT de base)
Voici un exemple pour les archives amont multiples de base.
version=4
opts="pgpsigurlmangle=s%$%.sig%" \
http://example.com/release/foo.html \
files/foo-@ANY_VERSION@@ARCHIVE_EXT@ debian
opts="pgpsigurlmangle=s%$%.sig%, component=bar" \
http://example.com/release/foo.html \
files/foobar-@ANY_VERSION@@ARCHIVE_EXT@ same
opts="pgpsigurlmangle=s%$%.sig%, component=baz" \
http://example.com/release/foo.html \
files/foobaz-@ANY_VERSION@@ARCHIVE_EXT@ same
Pour le paquet source amont principal toto-2.0.tar.gz et les paquets source amont secondaires
tototiti-2.0.tar.gz et tototitiz-2.0.tar.gz qui installent dans les répertoires titi/ and titiz/, ce
fichier de veille télécharge et crée le fichier Debian orig.tar, toto_2.0.orig.tar.gz,
toto_2.0.orig-titi.tar.gz et toto_2.0.orig-titiz.tar.gz. Les fichiers de signature de ces archives amont
sont aussi vérifiées.
Site HTTP (recherche récursive de répertoire)
Voici un exemple avec recherche récursive de répertoire de l’archive amont et de ses fichiers de
signature publiés dans un répertoire nommé d’après leur version.
version=4
opts="pgpsigurlmangle=s%$%.sig%, dirversionmangle=s/-PRE/~pre/;s/-RC/~rc/" \
http://tmrc.mit.edu/mirror/twisted/Twisted/@ANY_VERSION@/ \
Twisted-@ANY_VERSION@@ARCHIVE_EXT@
Ici, le site web devrait être accessible à l’URL suivante :
http://tmrc.mit.edu/mirror/twisted/Twisted/
Ici, l’option dirversionmangle est utilisée pour normaliser l’ordre de tri des noms de répertoire.
Site HTTP (raccourci alternatif)
Pour le site HTTP simple où il est possible de voir directement les noms de fichiers de l’archive, le
fichier de veille normal :
version=4
opts="pgpsigurlmangle=s%$%.sig%" \
http://www.cpan.org/modules/by-module/Text/ \
Text-CSV_XS-@ANY_VERSION@@ARCHIVE_EXT@
peut être réécrit dans une forme raccourcie alternative avec une seule chaîne englobant l’URL et le nom
de fichier :
version=4
opts="pgpsigurlmangle=s%$%.sig%" \
http://www.cpan.org/modules/by-module/Text/Text-CSV_XS-@ANY_VERSION@@ARCHIVE_EXT@
Dans version=4, les espaces blancs initiaux sont retirés. Donc, cette forme raccourcie alternative peut
aussi être écrite ainsi :
version=4
opts="pgpsigurlmangle=s%$%.sig%" \
http://www.cpan.org/modules/by-module/Text/\
Text-CSV_XS-@ANY_VERSION@@ARCHIVE_EXT@
Veuillez noter la légère différence d’une espace avant le \ final entre le premier et le dernier exemple.
Site HTTP (version exotique)
Pour un site qui possède des numéros de version exotiques, les groupes entre parenthèses devront être
joints par des points (.) pour créer un numéro de version sain.
version=4
http://www.site.com/pub/foobar/foobar_v(\d+)_(\d+)@ARCHIVE_EXT@
Site HTTP (DFSG)
La partie amont du numéro de version Debian peut être modifiée pour indiquer que le paquet source a été
rempaqueté pour retirer les fichiers non-DFSG :
version=4
opts="dversionmangle=s/\+dfsg\d*$//,repacksuffix=+dfsg" \
http://some.site.org/some/path/foobar-@ANY_VERSION@@ARCHIVE_EXT@
Voir "EXEMPLES DE FICHIER DE COPYRIGHT".
Site HTTP (filenamemangle)
Le nom de fichier de l’archive amont est découvert en prenant le dernier composant de l’URL et en
retirant tout ce qui se trouve après un "?" ou un "#".
Si cela ne vous convient pas, utiliser filenamemangle. Par exemple, <A
href="http://toto.titi.org/dl/?path=&dl=foo-0.1.1.tar.gz"> peut être traité ainsi :
version=4
opts=filenamemangle=s/.*=(.*)/$1/ \
http://foo.bar.org/dl/\?path=&dl=foo-@ANY_VERSION@@ARCHIVE_EXT@
<A href="http://toto.titi.org/dl/?path=&dl_version=0.1.1"> peut être géré comme ceci :
version=4
opts=filenamemangle=s/.*=(.*)/foo-$1\.tar\.gz/ \
http://foo.bar.org/dl/\?path=&dl_version=@ANY_VERSION@
Si la chaîne de référence href n’a pas de version utilisant <I>motif-correspondant>, la version peut être
obtenue à partir de l’URL complète avec filenamemangle.
version=4
opts=filenamemangle=s&.*/dl/(.*)/foo\.tar\.gz&foo-$1\.tar\.gz& \
http://foo.bar.org/dl/@ANY_VERSION@/ foo.tar.gz
Site HTTP (downloadurlmangle)
L’option downloadurlmangle peut être utilisée pour modifier l’URL du fichier à télécharger. Cela ne peut
être utilisé qu’avec des URL http:// et peut être nécessaire si le lien donné sur la page web doit être
transformé de manière à ce que cela fonctionne automatiquement, par exemple :
version=4
opts=downloadurlmangle=s/prdownload/download/ \
http://developer.berlios.de/project/showfiles.php?group_id=2051 \
http://prdownload.berlios.de/softdevice/vdr-softdevice-@ANY_VERSION@@ARCHIVE_EXT@
Site HTTP (oversionmangle, MUT)
L’option oversionmangle peut être utilisée pour manipuler la version de l’archive source (.orig.tar.gz et
.orig-bar.tar.gz). Par exemple, +dfsg peut être ajouté à la version amont comme ceci :
version=4
opts=oversionmangle=s/(.*)/$1+dfsg/ \
http://example.com/~user/release/foo.html \
files/foo-@ANY_VERSION@@ARCHIVE_EXT@ debian
opts="component=bar" \
http://example.com/~user/release/foo.html \
files/bar-@ANY_VERSION@@ARCHIVE_EXT@ same
Voir "EXEMPLES DE FICHIER DE COPYRIGHT".
Site HTTP (pagemangle)
L’option pagemangle peut être utilisée pour modifier la page web téléchargée avant d’appliquer d’autres
règles. Une page web non standard sans entrées <a href=" << ... >> "> correctes peut être convertie. Par
exemple, si toto.html utilise <un faux site=" ... ">, la conversion vers un format de page standard peut
être réalisée avec :
version=4
opts=pagemangle="s/<a\s+bogus=/<a href=/g" \
http://example.com/release/foo.html \
files/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@
Veuillez notez ici l’utilisation de g pour remplacer toutes les occurrences.
Si toto.html utilise <Key> ... </Key>, la conversion vers un format de page standard peut être réalisée
avec :
version=4
opts="pagemangle=s%<Key>([^<]*)</Key>%<Key><a href="$1">$1</a></Key>%g" \
http://example.com/release/foo.html \
(?:.*)/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@
Site FTP (de base) :
version=4
ftp://ftp.tex.ac.uk/tex-archive/web/c_cpp/cweb/cweb-@ANY_VERSION@@ARCHIVE_EXT@
Site FTP (expressions rationnelles) :
version=4
ftp://ftp.worldforge.org/pub/worldforge/libs/\
Atlas-C++/transitional/Atlas-C\+\+-@ANY_VERSION@@ARCHIVE_EXT@
Veuillez noter que cette URL est connectée pour être ... libs/Atlas-C++/ ... . Pour les ++, le premier
dans le chemin du répertoire est verbatim, tandis que celui qui est dans le nom de fichier est protégé
par \.
Site FTP (version exotique)
Voici une autre manière pour des sites ayant des numéros de version bizarres, en effectuant une
modification cette fois. (Remarquez que plusieurs groupes seront concaténés avant d’effectuer la
modification, et que les modifications ne seront effectuées que sur le numéro de version de base, et pas
dans les numéros de versions contenus dans les chemins.)
version=4
opts="uversionmangle=s/^/0.0./" \
ftp://ftp.ibiblio.org/pub/Linux/ALPHA/wine/\
development/Wine-@ANY_VERSION@@ARCHIVE_EXT@
sf.net
Pour les projets hébergés sur SourceForge, qa.debian.org fournit un redirecteur qui permet une forme plus
simple d’URL. Le format ci-dessous sera automatiquement réécrit pour utiliser le redirecteur avec le
fichier de veille :
version=4
https://sf.net/<project>/ <tar-name>-@ANY_VERSION@@ARCHIVE_EXT@
Pour audacity, configurer le fichier de veille ainsi :
version=4
https://sf.net/audacity/ audacity-minsrc-@ANY_VERSION@@ARCHIVE_EXT@
Veuillez noter, qu’il est encore possible d’utiliser les fonctionnalités normales de uscan pour
configurer un fichier de veille pour ce site sans utiliser le redirecteur.
version=4
opts="uversionmangle=s/-pre/~pre/, \
filenamemangle=s%(?:.*)audacity-minsrc-(.+)\.tar\.xz/download%\
audacity-$1.tar.xz%" \
http://sourceforge.net/projects/audacity/files/audacity/@ANY_VERSION@/ \
(?:.*)audacity-minsrc-@ANY_VERSION@@ARCHIVE_EXT@/download
Ici, % est utilisé comme séparateur à la place du / standard.
github.com
Pour les projets hébergés par GitHub, il est possible d’utiliser l’API des tags ou des publications. Si
le projet amont a correctement nommé ses paquets sur sa page de publications, il est possible de chercher
l’URL de téléchargement (clef API browser_download_url) :
version=4
opts=\
filenamemangle=s%.*/@ANY_VERSION@%@PACKAGE@-$1.tar.gz%,\
downloadurlmangle=s%(api.github.com/repos/[^/]+/[^/]+)/git/refs/%$1/tarball/refs/%g,\
searchmode=plain \
https://api.github.com/repos/<utilisateur>/<projet>/git/matching-refs/tags/ \
https://api.github.com/repos/[^/]+/[^/]+/git/refs/tags/@ANY_VERSION@
Il est aussi possible de filtrer les tags par préfixe. Par exemple pour obtenir seulement les tags
commençant par "v1" :
version=4
opts=\
filenamemangle=s%.*/@ANY_VERSION@%@PACKAGE@-$1.tar.gz%,\
downloadurlmangle=s%(api.github.com/repos/[^/]+/[^/]+)/git/refs/%$1/tarball/refs/%g,\
searchmode=plain \
https://api.github.com/repos/<utilisateur>/<projet>/git/matching-refs/tags/v1 \
https://api.github.com/repos/[^/]+/[^/]+/git/refs/tags/@ANY_VERSION@
Alternatives pour publications uniquement (si le projet amont ne supprime pas les tags après la
publication) :
version=4
opts=\
filenamemangle=s%.*/@ANY_VERSION@%@PACKAGE@-$1.tar.gz%,\
downloadurlmangle=s%api.github.com/repos/([^/]+/[^/]+)/git/refs/tags/@ANY_VERSION@%github.com/$1/archive/refs/tags/$2.tar.gz%g,\
searchmode=plain \
https://api.github.com/repos/<utilisateur>/<projet>/git/matching-refs/tags/ \
https://api.github.com/repos/[^/]+/[^/]+/git/refs/tags/@ANY_VERSION@
Dans le cas d’une version qui n’utilise pas de tag ou un tag supprimé :
version=4
opts="filenamemangle=s%.*/@ANY_VERSION@%@PACKAGE@-$1.tar.gz%,searchmode=plain" \
https://api.github.com/repos/<user>/<project>/releases?per_page=100 \
https://api.github.com/repos/<user>/<project>/tarball/@ANY_VERSION@
S’il y a des archives alpha/beta, il est conseillé utiliser l’option uversionmangle :
uversionmangle=s/(a|alpha|b|beta|c|dev|pre|rc)/~$1/
Si le projet amont oublie d’étiqueter une version publiée, par exemple ici la version 1.2.3 correspondant
à la commission "0123456789abcdf01234567890abcef012345678", vous pouvez la télécharger en utilisant la
combinaison suivante d’options oversionmangle, filenamemangle et downloadurlmangle :
version=4
opts=\
downloadurlmangle=s%(api.github.com/repos/[^/]+/[^/]+)/git/refs/.*%$1/tarball/0123456789abcdf01234567890abcef012345678%g,\
oversionmangle=s/.*/1.2.3~git/g,\
filenamemangle=s%.*%1.2.3~git.tar.gz%,\
searchmode=plain \
https://api.github.com/repos/ImageMagick/ImageMagick/git/matching-refs/tags/ \
https://api.github.com/repos/[^/]+/[^/]+/git/refs/tags/@ANY_VERSION@
Dans ce cas ne pas oublier, après avoir exécuté gbp import-orig --uscan, de retirer ces changements du
fichier debian/watch.
PyPI
Pour les projets hébergés sur PyPI, pypi.debian.net fournit un redirecteur qui permet une forme plus
simple d’URL. Le format ci-dessous sera automatiquement réécrit pour utiliser le redirecteur avec le
fichier de veille :
version=4
https://pypi.python.org/packages/source/<initial>/<project>/ \
<tar-name>-@ANY_VERSION@@ARCHIVE_EXT@
Pour cfn-sphere, configurer le fichier ainsi :
version=4
https://pypi.python.org/packages/source/c/cfn-sphere/ \
cfn-sphere-@ANY_VERSION@@ARCHIVE_EXT@
Veuillez noter, qu’il est encore possible d’utiliser les fonctionnalités normales de uscan pour
configurer un fichier de veille pour ce site sans utiliser le redirecteur.
version=4
opts="pgpmode=none" \
https://pypi.python.org/pypi/cfn-sphere/ \
https://pypi.python.org/packages/.*/.*/.*/\
cfn-sphere-@ANY_VERSION@@ARCHIVE_EXT@#.*
code.google.com
Les sites habituellement hébergés sur le service Google Code devraient avoir migré ailleurs (github ?).
Veuillez rechercher les sites amont les plus récents s’ils sont disponibles.
npmjs.org (modules Node)
Les modules npmjs.org sont publiés au format JSON. Voici un moyen de les lire :
version=4
opts="searchmode=plain" \
https://registry.npmjs.org/aes-js \
https://registry.npmjs.org/aes-js/-/aes-js-@ANY_VERSION@@ARCHIVE_EXT@
paquet groupé
Certains modules Node sont découpés en de multiples petits paquets. Voici un moyen de les grouper :
version=4
opts="searchmode=plain,pgpmode=none" \
https://registry.npmjs.org/mongodb \
https://registry.npmjs.org/mongodb/-/mongodb-@ANY_VERSION@@ARCHIVE_EXT@ group
opts="searchmode=plain,pgpmode=none,component=bson" \
https://registry.npmjs.org/bson \
https://registry.npmjs.org/bson/-/bson-@ANY_VERSION@@ARCHIVE_EXT@ group
opts="searchmode=plain,pgpmode=none,component=mongodb-core" \
https://registry.npmjs.org/mongodb-core \
https://registry.npmjs.org/mongodb-core/-/mongodb-core-@ANY_VERSION@@ARCHIVE_EXT@ group
opts="searchmode=plain,pgpmode=none,component=requireoptional" \
https://registry.npmjs.org/require_optional \
https://registry.npmjs.org/require_optional/-/require_optional-@ANY_VERSION@@ARCHIVE_EXT@ group
La version du paquet est alors la concaténation des versions amont séparées par "+~".
Pour éviter d’avoir un trop long numéro de version, la méthode "checksum" (somme de contrôle) peut être
utilisée. Dans ce cas la principale source doit être déclarée comme "group" :
version=4
opts="searchmode=plain,pgpmode=none" \
https://registry.npmjs.org/mongodb \
https://registry.npmjs.org/mongodb/-/mongodb-@ANY_VERSION@@ARCHIVE_EXT@ group
opts="searchmode=plain,pgpmode=none,component=bson" \
https://registry.npmjs.org/bson \
https://registry.npmjs.org/bson/-/bson-@ANY_VERSION@@ARCHIVE_EXT@ checksum
opts="searchmode=plain,pgpmode=none,component=mongodb-core" \
https://registry.npmjs.org/mongodb-core \
https://registry.npmjs.org/mongodb-core/-/mongodb-core-@ANY_VERSION@@ARCHIVE_EXT@ checksum
opts="searchmode=plain,pgpmode=none,component=requireoptional" \
https://registry.npmjs.org/require_optional \
https://registry.npmjs.org/require_optional/-/require_optional-@ANY_VERSION@@ARCHIVE_EXT@ checksum
La somme de contrôle est composée des sommes séparées de chaque nombre composant la version des
composants et préfixée par ~cs (abréviation de "checksum"). Voici un exemple avec 3 composants dont les
versions respectives sont : "1.2.4", "2.0.1" et "10.0", et la version de l’archive principale est
"2.0.6" :
Principale : 2.0.6
Comp1 : 1 . 2 . 4
Comp2 : 2 . 0 . 1
Comp3 : 10 . 0
=================================
Addition : 1+2+10 . 2+0+0 . 4+1
Résultat : 13 . 2 . 5
=================================
Version finale : 2.0.6+~cs13.2.5
uscan affichera également la chaîne de version originale avant encodage en somme de contrôle, ce qui peut
être utilisé par exemple dans une entrée de debian/changelog pour suivre facilement les changements :
2.0.6+~1.2.4+~2.0.1+~10.0
Note : cette fonctionnalité n’accepte actuellement que les versions composées exclusivement de chiffres
et de points (".").
accès direct au dépôt git (étiquettes)
Si l’équipe amont ne publie son code que dans un dépôt git et que son code n’a pas d’interface web pour
obtenir l’archive publiée, il est possible d’utiliser uscan avec les étiquettes du dépôt git pour suivre
et empaqueter la nouvelle publication amont.
version=4
opts="mode=git, gitmode=full, pgpmode=none" \
http://git.ao2.it/tweeper.git \
refs/tags/v@ANY_VERSION@
Veuillez noter que "git ls-remote" est utilisé pour obtenir les références des étiquettes.
Si l’étiquette v20.5 est l’étiquette la plus récente, l’exemple ci-dessus télécharge spkg-20.5.tar.xz
après avoir fait un clone complet du dépôt git nécessaire au serveur git simple.
Si les tags sont signés, utiliser pgpmode=gittag pour les vérifier.
accès direct au dépôt git (HEAD)
Si l’équipe amont ne publie son code que dans un dépôt git et que son code n’a pas d’interface web ni les
étiquettes pour obtenir l’archive publiée, il est possible d’utiliser uscan avec le HEAD du dépôt git
pour suivre et empaqueter la nouvelle publication amont avec une chaîne de version générée
automatiquement.
version=4
opts="mode=git, pgpmode=none" \
https://github.com/Debian/dh-make-golang \
HEAD
Veuillez noter qu’une copie superficielle locale du dépôt git est réalisée avec la commande "git clone
--bare --depth=1 ..." normalement dans le répertoire cible. uscan génère la nouvelle version amont avec
"git log --date=%Y%m%d --pretty=0.0~git%cd.%h" sur cette copie locale du dépôt, comme comportement par
défaut.
La création de la chaîne de version amont peut être ajustée à votre goût en ajoutant les options pretty
et date aux arguments de opts.
accès direct au dépôt git (avec sous-modules)
Si l’équipe amont ne publie son code que dans un dépôt git incluant des sous-modules, vous pouvez
utiliser uscan avec les étiquettes ou la tête (HEAD) du dépôt git pour suivre et empaqueter la nouvelle
publication amont.
Utiliser gitmodules pour cloner tous les sous-modules :
version=4
opts="mode=git, gitmode=shallow, gitmodules" \
https://github.com/namespace/project [refs/tags/v@ANY_VERSION@|HEAD]
Pour cloner des sous-modules sélectionnés (et en exclure d’autres), utiliser gitmodules avec une liste en
séparant les éléments par des points-virgules :
version=4
opts="mode=git, gitmode=shallow, gitmodules=m4;doc/common" \
https://github.com/namespace/project [refs/tags/v@ANY_VERSION@|HEAD]
accès direct au dépôt Subversion (étiquettes)
Si l’équipe amont ne publie son code que dans un dépôt Subversion et que son code n’a pas d’interface web
pour obtenir l’archive publiée, il est possible d’utiliser uscan avec les étiquettes du dépôt Subversion
pour suivre et empaqueter la nouvelle publication amont.
version=4
opts="mode=svn, pgpmode=none" \
svn://svn.code.sf.net/p/jmol/code/tags/ \
@ANY_VERSION@\/
accès direct au dépôt Subversion (HEAD)
Si l’équipe amont ne publie son code que dans un dépôt Subversion et que son code n’a pas d’interface web
ni les étiquettes pour obtenir l’archive publiée, il est possible d’utiliser uscan pour obtenir les
dernières sources d’une sous-arborescence avec une chaîne de version générée automatiquement.
version=4
opts="mode=svn, pgpmode=none" \
svn://svn.code.sf.net/p/jmol/code/trunk/ \
HEAD
Par défaut, uscan génère la nouvelle version en ajoutant "0.0~svn" au numéro de révision. Ce peut être
changé en utilisant uversionmangle.
Fossil
Pour les projets basés sur Fossil, l’URL de l’archive peut être déduite de la page listant les
étiquettes.
version=4
opts=" \
searchmode=plain, \
filenamemangle=s/timeline\?t=(@ANY_VERSION@)/@PACKAGE@-$1.tar.gz/, \
downloadurlmangle=s#/timeline\?t=(@ANY_VERSION@)#/tarball/Grammalecte.tar.gz?r=$1#" \
http://grammalecte.net:8080/taglist \
/timeline\?t=@ANY_VERSION@
EXEMPLES DE FICHIER DE COPYRIGHT
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: ...
...
Voir mk-origtargz(1).
EXEMPLES DE FICHIER DE TROUSSEAU
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.
• L’empreinte sous la forme des 20 octets de données calculés à partir de la clef publique OpenPGP. Par
exemple "CF21 8F0E 7EAB F584 B7E2 0402 C77E 2D68 7254 3FAF
• L’identificateur long " long keyid") sous la forme des 8 derniers octets de données de l’empreinte.
Par exemple, "C77E2D6872543FAF"
• L’identificateur court ("short keyid") sous la forme des 4 derniers octets de données de l’empreinte.
Par exemple, "72543FAF"
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
...
OPTIONS DE LIGNE DE COMMANDE
Pour un usage basique d’uscan, la configuration de ces options n’est pas nécessaire.
--conffile, --conf-file
Ajoute ou remplace les fichiers de configuration par défaut ("/etc/devscripts.conf" and
"~/.devscripts"). L’option ne peut être utilisée qu’en première position de la ligne de commande.
remplacer :
uscan --conf-file test.conf --verbose
ajouter :
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.
--no-conf, --noconf
Ne lire aucun fichier de configuration. L’option ne peut être utilisée qu’en première position de la
ligne de commande.
--no-verbose
Ne pas rapporter d’informations verbeuses. (Par défaut).
--verbose, -v
Rapporter des informations verbeuses.
--debug, -vv
Rapporter des informations verbeuses et les valeurs de certains états internes.
--extra-debug, -vvv
Rapporter des informations verbeuses y compris les pages web téléchargées traitées sur la sortie
d’erreur standard pour débogage.
--dehs
Envoyer la sortie de style DEHS (type XML) sur la sortie standard, tout en envoyant toutes les autres
sorties de uscan sur la sortie d’erreur standard.
--no-dehs
Utiliser seulement le format de sortie traditionnel de uscan. (Par défaut)
--download, -d
Télécharger la nouvelle version amont. (Par défaut)
--force-download, -dd
Télécharger la nouvelle version amont même si elle est à jour (peut ne pas écraser les fichiers
locaux).
--overwrite-download, -ddd
Télécharger le fichier amont même si le paquet est à jour (peut écraser les fichiers locaux).
--no-download, --nodownload
Ne pas télécharger ni rapporter d’information.
Des archives précédemment téléchargées peuvent être utilisées.
Passage du comportement par défaut à --skip-signature.
--signature
Télécharger la signature. (Par défaut)
--no-signature
Ne pas télécharger la signature, mais vérifier si elle a déjà été téléchargée.
-skip-signature
Ne pas s’occuper de télécharger ni de vérifier la signature.
--safe, --report
Éviter l’exécution de scripts non sécurisés en sautant à la fois le rempaquetage du paquet téléchargé
et la mise à jour de l’arborescence de la nouvelle source.
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.
--report-status
Équivaut à utiliser l’option --verbose --safe.
--download-version version
Indiquer la version à laquelle la version amont doit correspondre pour être prise en compte, plutôt
qu’utiliser celle avec le numéro de version le plus important (fonctionnalité optimale).
--download-debversion version
Préciser la version du paquet Debian dont il faut télécharger la version amont correspondante. Les
règles dversionmangle et uversionmangle sont prises en compte (fonctionnalité au meilleur effort).
--download-current-version
Télécharger la version actuelle du paquet. (fonctionnalité optimale)
--check-dirname-level N
Veuillez consulter la section "Vérification du nom du répertoire" ci-dessus pour une explication de
cette option.
--check-dirname-regex regex
Veuillez consulter la section "Vérification du nom du répertoire" ci-dessus pour une explication de
cette option.
--destdir chemin Normalement, uscan change son répertoire courant interne pour le répertoire source du
paquet où le répertoire debian/ est situé. Ensuite, le répertoire de destination de l’archive téléchargée
et des autres fichiers est défini sur le répertoire parent ../ à partir de ce répertoire courant interne.
Le répertoire de destination par défaut peut être remplacé en définissant l’option --destdir vers un
chemin particulier. Si ce chemin est un chemin relatif, le répertoire de destination est déterminé
relativement au répertoire courant interne d’exécution d’uscan. Si ce chemin est un chemin absolu, le
répertoire de destination est fixé à cheminindépendamment du répertoire courant interne d’exécution
d’uscan.
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.
--package paquet
Indiquer le nom du paquet à contrôler plutôt qu’examiner debian/changelog ; cela nécessite les
options --upstream-version (à moins qu’une option ne soit précisée dans le fichier watch) et
--watchfile. De plus, aucun répertoire ne sera scanné et rien ne sera téléchargé. Cette option
configure automatiquement --no-download et --skip-signature ; elle est probablement la plus utile en
conjonction avec le système DEHS (et --dehs).
--upstream-version version-amont
Indiquer la version amont actuelle plutôt qu’examiner le fichier debian/watch ou le journal des
modifications de Debian pour le déterminer. C’est ignoré si un balayage de répertoire est fait et que
plus d’un fichier debian/watch est trouvé.
--vcs-export-uncompressed
Supprimer la compression d’archives exportées depuis un système de contrôle de versions (Git ou
Subversion). Cela occupe plus d’espace, mais permet de gagner du temps si mk-origtargz doit
réempaqueter l’archive pour exclure des fichiers. Force le réempaquetage de toutes les archives
exportées.
--watchfile watchfile
Indiquer le fichier watch plutôt que faire un balayage de répertoire pour le déterminer. Si cette
option est utilisée sans --package, uscan devra être appelé depuis l’arborescence du paquet Debian
source (de sorte que debian/changelog puisse être trouvé simplement par une recherche dans
l’arborescence).
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.
--bare
Désactiver tout le code "special code" spécifique au site pour réaliser les redirections d’URL et les
altérations de contenu de page.
--http-header
Ajoute l’en-tête spécifié dans les requêtes HTTP correspondant à l’url. Cette option peut être
multivaluée, les valeurs doivent être de la forme "baseUrl@NomEnTête=valeur". Exemple :
uscan --http-header https://example.org@My-Token=azertyuiop
Sécurité :
L’URL baseUrl doit exactement correspondre à l’URL de base avant "/". Exemples :
| 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 |
Il est vivement recommandé de ne pas utiliser cette fonctionnalité pour passer un jeton secret via
une connexion non chiffrée (http://)
On peut utiliser la variable "USCAN_HTTP_HEADER" (dans "~/.devscripts") pour masquer les jetons
secrets des scripts
--no-exclusion
Ne pas exclure automatiquement les fichiers mentionnés dans le champ Files-Excluded de
debian/copyright.
--pasv
Forcer le mode passif ("PASV") pour les connexions FTP.
--no-pasv
Ne pas utiliser le mode passif (PASV) pour les connexions FTP.
--no-symlink
Ne pas renommer ni rempaqueter l’archive amont.
--timeout N
Définir le temps d’attente à N secondes (20 secondes par défaut).
--user-agent, --useragent
Utiliser un champ "user agent" différent de celui par défaut.
--help
Afficher un bref message d’aide.
--version
Afficher les informations sur la version.
uscan accepte aussi les options suivantes et les passe à mk-origtargz :
--symlink
Faire des fichiers résultants orig.tar.gz (avec l’extension appropriée) des liens symboliques vers
les fichiers téléchargés (c’est le comportement par défaut).
--copy
Au lieu de créer des liens symboliques comme décrit précédemment, copier les fichiers téléchargés.
--rename
Au lieu de créer des liens symboliques comme décrit précédemment, renommer les fichiers téléchargés.
--repack
Après avoir téléchargé une archive lzma tar, xz tar, bzip tar, gz tar, lz tar, zip, jar, xpi, zstd,
la réempaqueter à la compression spécifiée (voir --compression).
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.
--compression [ gzip | bzip2 | lzma | xz ]
Au cas où les sources amont sont rempaquetés (soit parce que l’option --repack est donnée, soit parce
que debian/copyright contient le champ Files-Excluded), la méthode de compression peut être contrôlée
avec le paramètre comp. La méthode par défaut est gzip pour les archives normales, et xz pour les
archives générées directement à partir du dépôt git.
--copyright-file fichier_de_copyright
Exclure les fichiers mentionnés dans le champ Files-Excluded du fichier_de_copyright donné. C’est
utile lors de l’utilisation d’uscan en dehors d’un répertoire de paquet source.
VARIABLES DE CONFIGURATION DE DEVSCRIPT
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 :
USCAN_DOWNLOAD
Télécharger ou rapporter l’information seulement:
no : équivaut à --no-download, les nouveaux fichiers ne seront pas téléchargés.
yes: equivaut à --download, les nouveaux fichiers amont seront téléchargés. C’est le comportement par
défaut.
Voir aussi --force-download and --overwrite-download.
USCAN_SAFE
Si elle est définie à yes, alors uscan évite l’exécution de scripts non sécurisés en sautant à la
fois le rempaquetage du paquet téléchargé et la mise à jour de l’arborescence de la nouvelle source ;
c’est l’équivalent des options --safe ; cela définit aussi les options par défaut à --no-download et
--skip-signature.
USCAN_PASV
Si elle est définie à yes ou no, cela force respectivement à utiliser ou à ne pas utiliser le mode
passif pour les connexions FTP. Si elle est définie à default, alors Net::FTP(3) fait un choix (basé
principalement sur la variable d’environnement FTP_PASSIVE).
USCAN_TIMEOUT
Si cette option est définie à un nombre N, alors définir le temps limite à N secondes. C’est
équivalent à l’option --timeout.
USCAN_SYMLINK
Si cette option est mise à no, un lien symbolique vers paquet_version.orig.tar.{gz|bz2|lzma|xz} ne
sera pas créé (équivalent à l’option --no-symlink). Si elle est à yes ou symlink, les liens
symboliques seront créés. Si elle est à rename, les fichiers sont renommés (équivalent à l’option
--rename).
USCAN_DEHS_OUTPUT
Si cette option est à yes, alors la sortie sera de type DEHS, comme si l’option --dehs était
utilisée.
USCAN_VERBOSE
Si elle est définie à yes, alors la sortie sera verbeuse, comme si l’option --verbose était utilisée.
USCAN_USER_AGENT
Si elle est définie, elle spécifie la chaîne à utiliser pour annoncer le navigateur ("user agent") à
la place de la valeur par défaut. C’est équivalent à l’option --user-agent.
USCAN_DESTDIR
Si elle est définie, elle désigne le répertoire où les fichiers téléchargés seront placés. C’est
équivalent à l’option --destdir.
USCAN_REPACK
Si elle est définie à yes, alors après avoir téléchargé une archive tar compressée avec bzip, lzma,
xz ou zstd ou une archive ZIP, uscan recréera une archive compressée du type défini (voir
--compression). C’est équivalent à l’option --repack.
USCAN_EXCLUSION
Si elle est définie à no, les fichiers mentionnés dans le champ Files-Excluded de debian/copyright
seront ignorés et aucune exclusion de fichiers ne sera tentée. C’est équivalent à l’option
--no-exclusion.
USCAN_HTTP_HEADER
Si définie, l’en-tête spécifié sera utilisé pour toutes les URLs correspondantes. C’est équivalent à
l’option --http-header.
USCAN_VCS_EXPORT_UNCOMPRESSED
Si elle est définie à yes, les archives exportées depuis un système de contrôle de versions ne seront
pas compressées. C’est équivalent à l’option --vcs-export-uncompressed.
VALEURS DE RETOUR
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.
0 Soit les options --help ou --version ont été utilisées, soit une nouvelle version amont a été trouvée
pour un des fichiers watch examinés.
1 Aucune nouvelle version amont n’a été trouvée pour les fichiers watch examinés.
FONCTIONNALITÉS AVANCÉES
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.
Script personnalisé
Le paramètre optionnel script dans debian/watch signifie exécuter script avec des options après avoir
traité cette ligne si elle est spécifiée.
Voir "HISTORIQUE ET MISE À NIVEAU" pour voir comment uscan invoque le <script> personnalisé.
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.
Détournement d’URL
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.
• <http://sf.net>
• <http://pypi.python.org>
Vérification du nom du répertoire
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 :
0 Ne jamais vérifier le nom du répertoire.
1 Ne vérifie le nom du répertoire que s’il a fallu changer de répertoire pour trouver le fichier
debian/changelog, c’est-à-dire que le répertoire qui contient debian/changelog n’est pas le
répertoire dans lequel uscan a été invoqué. C’est le comportement par défaut.
2 Toujours vérifier le nom du répertoire.
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.
HISTORIQUE ET MISE À NIVEAU
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.
Versions antérieures à 2
La syntaxe du fichier watch était très différente à l’époque. Ne l’utilisez plus. Si vous mettez
votre fichier watch à niveau depuis une version antérieure à 2, il est recommandé de lire cette page
de manuel et de recommencer à zéro.
Version 2
devscripts version 2.6.90 : la première incarnation du style actuel de fichier watch. Cette version
est également dépréciée et sera rejetée dès la publication de Debian 11.
Version 3
devscripts version 2.8.12 a introduit les choses suivantes : manipulation correcte des expressions
rationnelles dans la partie du chemin, recherche de motif d’un répertoire/chemin, numéro de version
dans plusieurs parties, numéro de version modifiable. Les versions suivantes ont introduit la
modification des liens.
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 ( ... ).
• uscan invoque le script personnalisé comme ceci : script --upstream-version version
../spkg_version.orig.tar.gz.
• uscan invoque uupdate standard comme ceci : "uupdate --no-symlink --upstream-version version
../spkg_version.orig.tar.gz".
Version 4
devscripts version 2.15.10 : la première incarnation des fichiers watch prenant en charge les
archives amont multiples.
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.
• uscan invoque le script personnalisé comme ceci : "script --upstream-version version".
• uscan invoque uupdate standard comme ceci : "uupdate --find --upstream-version version".
Les restrictions pour --dehs sont levées en redirigeant les autres sorties sur la sortie d’erreur
standard lorsque elle est active.
VOIR AUSSI
dpkg(1), mk-origtargz(1), perlre(1), uupdate(1), devscripts.conf(5)
AUTEUR
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.
TRADUCTION
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
Utilitaires Debian 2025-06-16 USCAN.FR(1)