VCS package guidelines (Português)

Status de tradução:
Esse artigo é uma tradução de
VCS package guidelines
. Data da última tradução: 2023-11-08. Você pode ajudar a sincronizar a tradução, se houver
alterações
na versão em inglês.
Diretrizes de pacotes do Arch
32-bit
–
CLR
–
CMake
–
Cross
–
DKMS
–
Eclipse
–
Electron
–
Fonte
–
Free Pascal
–
GNOME
–
Go
–
Haskell
–
Java
–
KDE
–
Kernel
–
Lisp
–
Meson
–
MinGW
–
Node.js
–
Nonfree
–
OCaml
–
Perl
–
PHP
–
Python
–
R
–
Ruby
–
Rust
–
Shell
–
VCS
–
Web
–
Wine
Sistema de controle de versões
pode ser usado para obter o código-fonte para tanto pacotes versionados estaticamente quanto a última versão (
trunk
) de um ramo de desenvolvimento. Esse artigo cobre ambos casos.
Protótipos
Use apenas os protótipos de PKGBUILD fornecidos pelo pacote
pacman
(
PKGBUILD-split.proto
,
PKGBUILD-vcs.proto
e
PKGBUILD.proto
em
/usr/share/pacman
).
Diretrizes
Nomenclatura de pacote
Adicione um sufixo a
pkgname
com
-cvs
,
-svn
,
-hg
,
-darcs
,
-bzr
,
-git
etc. a menos que o pacote obtenha uma versão específica.
Versionamento
Se o pacote resultante for diferente depois de alterar, por exemplo, as dependências, URL ou fontes, atualize o
pkgrel
para a versão mais recente. Se o
pkgver
não tiver alterado desde a última atualização do
PKGBUILD
, aumente o
pkgrel
.
Dica
--holdver
pode ser usado para evitar que
makepkg
atualize o
pkgver
(veja:
makepkg(8)
)
Conflitos e dependências
Inclua o que o pacote conflita com e fornece (p.ex. para
fluxbox-git
AUR
:
conflicts=('fluxbox')
e
provides=('fluxbox')
).
replaces=()
geralmente causa problemas desnecessários e deve ser evitado.
Inclua a ferramenta de VCS apropriada em
makedepends=()
(
cvs
,
subversion
,
git
, ...).
Autenticação e segurança
Ao usar o cvsroot, use
anonymous:@
em vez de
anonymous@
para evitar ter que digitar uma senha em branco ou
anonymous:senha@
, se uma for exigida.
Porque os fontes não são estáticos, ignore a verificação de soma em
sha256sums=()
adicionando
'SKIP'
.
Fontes VCS
Nota
O uso de clones esparsos ou rasos (
shallow
) é intencionalmente não suportado (veja
FS#34677
e a
lista de discussão
).
A partir do
pacman
4.1, os fontes VCS devem ser especificados no vetor
source=()
e será tratado como qualquer outro fonte.
makepkg
vai realizar
clone
/
checkout
/
branch
do repositório para
$SRCDEST
(mesmo que
$startdir
se não definido no
makepkg.conf(5)
) e vai copiá-lo para
$srcdir
(em uma forma específica para cada VCS). O repositório local é deixado intocado, portanto passando a ser desnecessário ter um diretório
-build
.
O formato geral de um vetor
source=()
de VCS é:
source=('[pasta::][vcs+]url[#fragmento]')
pasta
(opcional) é usada para alterar o nome do repositório padrão para algo mais relevante (p. ex., do que
trunk
) ou para preservar os fontes anteriores.
vcs+
é necessário para URLs que não refletem o tipo VCS, p. ex.,
git+http://algum_repo
.
url
é o URL para o repositório distante ou local.
#fragmento
(opcional) é necessário para fazer
pull
um
branch
ou
commit
específico. Veja
PKGBUILD(5) § USING VCS SOURCES
para uma lista de VCS suportados e os respectivos fragmentos disponíveis.
Um exemplo de vetor fonte de Git:
source=('nome_projeto::git+https://url_projeto#branch=ramo_projeto')
Atenção
Certifique-se de não usar a variável
pkgver
no campo
folder
, pois a variável pode ser alterada durante a chamada da função
pkgver()
, o que vai tornar impossível acessar a pasta criada nas funções subsequentes.
A função pkgver()
O autoincremento de
pkgver
agora é alcançado através de uma função
pkgver()
dedicada. Isso permite um melhor controle sobre o
pkgver
, e os mantenedores devem favorecer um
pkgver
que faça sentido. Para usar
pkgver()
, você ainda precisa declarar a variável
pkgver
com o valor mais recente. O makepkg irá invocar a função
pkgver()
e atualizar a variável
pkgver
de acordo.
Recomenda-se ter o seguinte formato de versão:
LANÇAMENTO.rREVISÃO
onde
REVISÃO
é um número monotonicamente crescente que identifica exclusivamente a árvore de fonte (revisões VCS fazem isso). Se não houver lançamentos públicos e nenhuma tag de repositório, o zero pode ser usado como um número de release ou você pode descartar
LANÇAMENTO
e usar o número da versão que se parece com
rREVISÃO
. Se houver lançamentos públicos, mas o repositório não tiver tags, o desenvolvedor deve obter a versão de lançamento de alguma forma, por exemplo, analisando os arquivos do projeto.
O delimitador do número de revisão ("r" logo antes da REVISÃO) é importante. Esse delimitador permite evitar problemas caso o upstream decida fazer seu primeiro lançamento ou use versões com diferentes números de componentes. Por exemplo, se na revisão "455" o upstream decidir lançar a versão 0.1, o delimitador de revisão preservará a monotonicidade da versão -
0.1.r456 > r454
. Sem o delimitador, a monotonicidade falha -
0.1.456 < 454
.
Veja
PKGBUILD-vcs.proto
para exemplos genéricos mostrando a saúde visada.
Git
Usando a tag anotada mais recente alcançável do último commit:
pkgver() {
  cd "$pkgname"
  git describe --long --abbrev=7 | sed 's/\([^-]*-g\)/r\1/;s/-/./g'
}
2.0.r6.ga17a017
Usando a tag não anotada mais recente alcançável do último commit:
pkgver() {
  cd "$pkgname"
  git describe --long --tags --abbrev=7 | sed 's/\([^-]*-g\)/r\1/;s/-/./g'
}
0.71.r115.gd95ee07
No caso, se a tag git não contém traços, então pode-se usar uma expressão sed mais simples, como
sed 's/-/.r/;s/-/./'
.
Se a tag contiver um prefixo, como
v
ou o nome do projeto, ele deverá ser cortado:
pkgver() {
  cd "$pkgname"
  # cortando o prefixo "foo-" apresentado na tag do git
  git describe --long --abbrev=7 | sed 's/^foo-//;s/\([^-]*-g\)/r\1/;s/-/./g'
}
6.1.r3.gd77e105
Se não houver tags, use o número de revisões desde o início do histórico:
pkgver() {
  cd "$pkgname"
  printf "r%s.%s" "$(git rev-list --count HEAD)" "$(git rev-parse --short=7 HEAD)"
}
r1142.a17a017
Versão e somente o commit/número da revisão (SHA1 omitido; no entanto, sem uma referência rápida SHA1 de uma revisão exata, ela é perdida se não estiver atento ao controle de versão):
git describe --long --abbrev=7 --tags | sed 's/\([^-]*\)-g.*/r\1/;s/-/./g'
Ambos os métodos também podem ser combinados, para suportar repositórios que iniciam sem uma tag, mas são marcados mais tarde (use um "bashismo"):
pkgver() {
  cd "$pkgname"
  ( set -o pipefail
    git describe --long --abbrev=7 2>/dev/null | sed 's/\([^-]*-g\)/r\1/;s/-/./g' ||
    printf "r%s.%s" "$(git rev-list --count HEAD)" "$(git rev-parse --short=7 HEAD)"
  )
}
0.9.9.r27.g2b039da  # se tags existirem
r1581.2b039da       # do contrário
Subversion
pkgver() {
  cd "$pkgname"
  local ver="$(svnversion)"
  printf "r%s" "${ver//[[:alpha:]]}"
}
r8546
Nota
Se o projeto tiver lançamentos, você deve usá-los em vez do
0.
.
Mercurial
pkgver() {
  cd "$pkgname"
  printf "r%s.%s" "$(hg identify -n)" "$(hg identify -i)"
}
r2813.75881cc5391e
Bazaar
pkgver() {
  cd "$pkgname"
  printf "r%s" "$(bzr revno)"
}
r830
Reserva
Caso nenhum
pkgver
satisfatório possa ser extraído do repositório, a data atual pode ser usada:
pkgver() {
  date +%Y%m%d
}
20130408
Embora não identifique o estado da árvore de fonte de forma exclusiva, então evite-o, se possível.
Dicas e truques
Submódulos git
Submódulos de Git são um pouco complicados de se fazer. A ideia é adicionar as URLs dos submódulos diretamente ao vetor de fontes e, em seguida, referenciá-las durante o
prepare()
.
Os desenvolvedores de projetos downstream podem não nomear seu submódulo com o mesmo nome do repositório do módulo upstream. Para visualizar o nome dos submódulos git, acesse o arquivo
.gitmodules
no repositório do projeto e visualize-o. Por exemplo, um repositório denominado
biblioteca-dependência
pelos desenvolvedores upstream pode ser registrado como um submódulo denominado
libs/libdep
no
.gitmodules
do downstream.
[submodule "lib/libdep"]
  path = lib/libdep
  url = https://example.org/biblioteca-dependência/biblioteca-dependência.git
source=("git+https://example.org/projeto-principal/projeto-principal.git"
        "git+https://example.org/biblioteca-dependência/biblioteca-dependência.git")

prepare() {
  cd projeto-principal
  git submodule init
  git config submodule.libs/libdep.url "$srcdir/biblioteca-dependência"
  git -c protocol.file.allow=always submodule update
}