Contents
debian/watch
O arquivo watch localizado no diretório debian serve para fins de monitoramento de atualizações de software upstream e, se disponível, iniciar seu download. Este processo de download é facilitado pelo programa uscan, que faz parte do pacote devscripts. uscan pode ser invocado com o caminho para o diretório debian contendo o arquivo watch como um argumento, ou pode atravessar através de diretórios abaixo do diretório de trabalho atual para localizar os arquivos necessários.
Por favor, veja também o Manual de Políticas Debian sobre debian/watch.
Basicamente, um arquivo watch terá este formato:
version=4 http://somesite.com/dir/filenamewithversion.tar.gz
Para permitir que a versão permaneça não especificada, ela é expressa como um curinga usando expressão regular no formato Perl:
version=4 http://somesite.com/dir/filename_(.+).tar.gz
O programa uscan executará então um comando "dir" e verificará, para todos os arquivos nesse diretório, o número de versão mais alto.
uscan também suporta o protocolo FTP. Infelizmente, ao trabalhar com HTTP, as páginas HTML nem sempre contêm uma listagem de diretórios com arquivos. O caminho completo (ou relativo) do arquivo .tar.gz a ser baixado aparecerá como um hiperlink dentro da página web. Portanto, precisamos de dois tipos de informações, o caminho para a página anunciando o arquivo e uma expressão regular para fazer um "grep" para o link certo:
version=4 http://somesite.com/path link_from_href-1.0.tar.gz
"http://somesite.com/path" é o site de onde você está baixando a fonte, e "link_from_href.1.0.tar.gz" é obtido do código-fonte HTML (das tags "<a href=").
Se o código HTML http://somesite.com/path possui "<a href=foo/program-1.0.tar.gz>" dentro dele, por exemplo, você usará
http://somesite.com/dir foo/program-(.+)\.tar\.gz
Arquivos watch com erros geralmente estão errados nesta segunda parte.
Geralmente você quer um regex um pouco mais flexível para o nome do tarball, de modo que, se o(a) upstream muda para esquemas de nomenclatura de tarball ou formatos de compressão, você está coberto(a):
http://somesite.com/dir foo/program-(.+)\.(?:zip|tgz|tbz|txz|(?:tar\.(?:gz|bz2|xz)))
Para sites FTP muda um pouco, mas é basicamente a mesma coisa (man uscan poderá ajudar).
Mas a parte legal é testar:
uscan --no-download --verbose
Se não estiver funcionando como esperado, você pode usar o debug para ver o que está encontrando e o que não é compatível:
uscan --no-download --verbose --debug
- Uma boa explicação escrita pelo João Eriberto
Erros comuns
Não escapar pontos, que correspondem a qualquer caractere. A solução é \. em vez de . no regex.
Uma regex de extensão de arquivo que não é flexível o suficiente. A solução é \.(?:zip|tgz|tbz|txz|(?:tar\.(?:gz|bz2|xz)))
Não ancorar o grupo de versão no lugar certo. A solução é incluir algo antes de (\d\S+), como fooproj-(\d\S+)\.tar\.gz
Não iniciar a parte da versão do regex com um dígito. A solução é usar \d em vez de .
Não ser flexível o suficiente no caminho para o arquivo. A solução é usar http://example.com/someproject/ .*/program-(\d\S+)\.tar\.gz em vez de http://example.com/someproject/ /path/to/program/downloads/program-(\d\S+)\.tar\.gz
Não alterar versões upstream que são alfas, betas ou candidatas a lançamento para fazê-las classificar antes da versão final. A solução é usar uversionmangle como este opts=uversionmangle=s/(\d)[_\.\-\+]?((RC|rc|pre|dev|beta|alpha)\d*)$/$1~$2/
Não alterar versões Debian para remover o sufixo +dfsg.1 ou +dfsg1. A solução é usar dversionmangle como este opts=dversionmangle=s/\+(debian|dfsg|ds|deb)(\.?\d+)?$//
Não habilitar a verificação de assinatura criptográfica quando seu(sua) upstream assinar os lançamentos com OpenPGP.
Dicas para números de versões
Para upstreams que lançam versões alpha, beta e candidatas, é comum usar versões como 1.0-alpha, 1.0-rc1, ... antes da 1.0. Sem uma extração adequada, isso quebrará as comparações de versão do dpkg:
dpkg --compare-versions '1.0-1' gt '1.0-alpha-1' # false dpkg --compare-versions '1.0-1' gt '1.0~alpha-1' # true (notice the ~)
A solução é usar o uversionmangle como este opts=uversionmangle=s/(\d)[_\.\-\+]?((RC|rc|pre|dev|beta|alpha)\d*)$/$1~$2/ antes de importar novas versões.
Se você já fez upload um número de versão "quebrado", às vezes você pode usar o sufixo de reempacotamento ds<n>, por exemplo, '1.0-ds1-1' ou '1.0.ds1-1'.
Consulte https://codesearch.debian.net/search?q=repacksuffix%3D%2Bds1&literal=1
Verificação de assinatura criptográfica
Se o(a) upstream fornecer assinaturas criptográficas para os pacotes no mesmo local em que os pacotes estão disponíveis para download, e você sabe qual a chave ou as chaves OpenPGP serão usadas para assinar esses pacotes, uscan pode verificar essas assinaturas se você passar a opção pgpsigurlmangle.
Por exemplo, para o OpenSSH (que usa um sufixo .asc para as assinaturas do pacote), você colocaria a chave pública do Damien Miller em ascii-armored ascii-ardrot.org em debian/upstream/signing-key.asc:
gpg --armor --export-options export-minimal --export '59C2 118E D206 D927 E667 EBE3 D3E5 F56B 6D92 0D30' >> debian/upstream/signing-key.asc
e então atualizaria o debian/watch:
version=4 opts=pgpsigurlmangle=s/$/.asc/ ftp://ftp.openbsd.org/pub/OpenBSD/OpenSSH/portable/openssh-(.+)\.tar\.gz
Isso permite que você garanta que o pacote não foi adulterado em trânsito e que veio do(a) desenvolvedor(a) o(a) qual você esperava que viesse. Uma assinatura válida não significa que o conteúdo do pacote seja de alguma forma magicamente perfeito, e conforme com as DFSG e com a política, é claro!
Muitas vezes, quando o(a) upstream usa git, ele(a) não assina seus lançamentos, mas assina suas tags. Aqui está um exemplo de um arquivo debian/watch usando mode=git para recuperar versões e verificar assinaturas de tags:
version=4 opts="mode=git,pgpmode=gittag" \ https://mygitlabinstance.tld/myusername/myproject.git refs/tags/v([\d\.]+)
Sites com fontes upstream
GitHub
Se o projeto usar tags em versões:
version=4 https://github.com/<REPONAME>/tags .*/v?(\d.*)@ARCHIVE_EXT@
Se o projeto oferecer uma seção Release:
version=4 https://github.com/<REPONAME>/releases/download/v(\d+).(\d+).(\d+).tar.gz
Se upstream lançar tarballs beta/alfa, você precisará fazer uso de uversionmangle.
version=4 opts="searchmode=plain,\ filenamemangle=s%v?@ANY_VERSION@%@PACKAGE@-$1.tar.gz%,\ uversionmangle=s/(\d)[_\.\-\+]?((RC|rc|pre|dev|beta|alpha|a|b)\d*)$/$1~$2/" \ https://api.github.com/repos/<user>/<project>/releases?per_page=50 \ https://github.com/<user>/<project>/releases/download/@ANY_VERSION@/@PACKAGE@-@ANY_VERSION@.tar.gz
Se seu arquivo d/watch estiver falhando para encontrar os tarballs, pode analisar a página em:
https://api.github.com/repos/<user>/<project>/releases?per_page=50
E identificar uma regex que possa ser usada para buscar o tarball corretamente.
A partir de 02-10-2022, o ?GitHub alterou a forma como sua página de lançamentos/tags é processada. Os links são carregados dinamicamente em ?JavaScript em vez de texto estático. Veja tópico para as discussões: https://lists.debian.org/debian-devel/2022/09/msg00224.html.
Exemplo usando a API do Github:
Embora seja possível obter um tarball de outra maneira, a API também funciona e cabe ao(à) mantenedor(a) qual das opções usar.
version=4 opts="searchmode=plain,\ filenamemangle=s%v?@ANY_VERSION@%@PACKAGE@-$1.tar.xz%" \ https://api.github.com/repos/<user>/<project>/releases?per_page=100 \ https://api.github.com/repos/[^/]+/[^/]+/tarball/v?@ANY_VERSION@
Manipulação usando v1.0.0 (exemplo) e tarballs assinados (por razões de segurança como verificação de integridade, é altamente recomendado, e veja como posso verificar um código-fonte tor?):
version=4 opts=downloadurlmangle=s/archive\/refs\/tags\/v(.*)\.tar\.gz/releases\/download\/v$1\/@PACKAGE@-$1\.tar\.xz/,\ pgpsigurlmangle=s/$/.asc/ \ https://github.com/<user>/@PACKAGE@/tags \ (?:.*?/)?v?@ANY_VERSION@@ARCHIVE_EXT@
GitLab
Desde 2024/03 os pacotes que recebem tarballs do GitLab precisam ser alterados (mostrando o erro debian/watch nomatching files para watch), a solução abaixo foi testada e outras soluções anteriores não funcionarão. O GitLab alterou a ordem das tages e o debian/watch terá que ser atualizado pelas sugestões abaixo:
version=4 opts="searchmode=plain" \ https://gitlab.com/<user>/@PACKAGE@/tags?sort=updated_desc -/archive/v?\d[\d.]+/@PACKAGE@-@ANY_VERSION@@ARCHIVE_EXT@ debian uupdate
ou
version=4 opts="searchmode=plain" \ https://gitlab.com/<user>/@PACKAGE@/tags?sort=updated_desc -/archive/v?\d[\d.]+/@PACKAGE@-@ANY_VERSION@@ARCHIVE_EXT@
Você também pode usar filenamemangle seguindo o exemplo da Salsa. Veja https://lists.debian.org/debian-mentors/2024/03/msg00259.html
Fay Stegerman descobriu como obter tarball usando o upload URL em vez do arquivo URL, e ela explica sobre isso aqui: https://lists.debian.org/debian-mentors/2024/04/msg00013.html e exemplifica como trocar para um novo esquema de versão. Veja também uscan (wget) não apresentou mais o mesmo HTML que um navegador normal para lançamentos.
Se o(a) upstream usar apenas tags e não lançamentos, é preciso forjar os URLs da página da API:
version=4 opts="pagemangle=s!"name":"(v?@ANY_VERSION@)"!<a href="https://gitlab.com/@PACKAGE@/@PACKAGE@/-/archive/$1/@PACKAGE@-$1.tar.bz2">!g" \ https://gitlab.com/api/v4/projects/@PACKAGE@%2F@PACKAGE@/repository/tags \ https://gitlab.com/@PACKAGE@/@PACKAGE@/.*/@PACKAGE@-v?@ANY_VERSION@@ARCHIVE_EXT@
Salsa (Gitlab)
Por favor, certifique-se de que as tags estão estritamente em formato numérico. Por exemplo, a tag de versão deve ser escrita como 1.4.5.
version=4 opts=filenamemangle=s/.*?\/(\d\S+)\/archive\.tar\.gz/<project>-$1\.tar\.gz/ \ https://salsa.debian.org/<user>/<project>/tags .*?(\d\S+)/archive\.tar\.gz
Gitea / Forgejo / Codeberg.org
Se o projeto usa tags de lançamento como v1.2.3.
version=4 https://codeberg.org/<user>/<project>/tags .*/v@ANY_VERSION@@ARCHIVE_EXT@
Bitbucket
version=4 https://bitbucket.org/<user>/<project>/downloads?tab=tags .*/(\d\S+)\.tar\.gz
A segunda regexp corresponde geralmente às tags usadas, como '0.1.2' ou 'v0.1.2'. Pode ser necessário adaptar se o(a) upstream usar outras etiquetas de versão.
Launchpad
version=4 opts=pgpsigurlmangle=s/$/.asc/ \ https://launchpad.net/<project>/ \ https://launchpad.net/.*download/<project>-([.\d]+)\.tar\.xz
PyPI
O site PyPI é difícil de trabalhar diretamente, pois inclui md5sums para os downloads nas URLs, o que cria regexps verdadeiramente horríveis. O redirecionador pypi.debian.net torna muito mais fácil trabalhar com PyPI:
version=4 opts=pgpsigurlmangle=s/$/.asc/ \ https://pypi.debian.net/<project>/<project>-(.+)\.(?:zip|tgz|tbz|txz|(?:tar\.(?:gz|bz2|xz)))
Há também um (pouco mais avançado) arquivo watch autogerado que você pode baixar dehttp://pypi.debian.net/<project>/watch
Se você quiser trabalhar diretamente com o PyPI, use a nova Simple API:
https://pypi.python.org/simple/<project>/
Observe que o uso direto das páginas de listagem da PyPI para pacotes (como https://pypi.python.org/pypi/<package>/) é desencorajado pelos(as) administradores(as) da PyPI. O uso automatizado de páginas de listagem de pacotes não é suportado e é susceptível de quebrar; a Simple API é fornecida precisamente por esse motivo.
SourceForge
version=4 # qa.debian.org runs a redirector which allows a simpler form of URL # for SourceForge based projects. The format below will automatically # be rewritten to use the redirector. http://sf.net/audacity/audacity-src-(\d\S+)\.(?:zip|tgz|tbz|txz|(?:tar\.(?:gz|bz2|xz)))
Veja também: https://salsa.debian.org/qa/qa/tree/master/wml/watch/
KDE
version=4 opts=pgpsigurlmangle=s/$/.sig/ https://download.kde.org/stable/release-service/([\d.]+)/src/@PACKAGE@-([\d.]+)\.tar\.xz
Sites pouco comuns
Se você tem um site que tem números de versão de alguma forma, mas não tem hrefs contendo-os, e os recursos de URL do uscan não são suficientes, você pode criar um redirecionador. O pessoal do Debian QA executa um redirecionador chamado fakeupstream.cgi (git) para muitos sites. Se você quiser adicionar um novo, por favor envie um relatório de bugs assinado para qa.debian.org como wishlist, com ou sem um patch.
Os arquivos hospedados em vários sites de hospedagem de projetos grandes podem ser especificados com as URLs abaixo. SourceForge tem uma URL especial de "redirecionador" (veja mais detalhes em 'man uscan'). Isso permite que as URLs upstream mudem sem a necessidade de adaptar os arquivos watch dos pacotes afetados.
Autogerados
Um script gerador de debian/watch está disponível.
Mais informações
Uma postagem de blog explicativo sobre como escrever uma linha regexp útil: http://eriberto.pro.br/blog/2013/10/07/how-to-write-a-good-debianwatch-easily/
Ignore algumas versões upstream, como a upstream alterada de v20190101 para v1.2.3: https://lists.debian.org/debian-mentors/2020/08/msg00025.html
Outras distribuições
Fedora também tem um projeto de monitoramento de lançamentos upstream (mais informações).