VCS package guidelines (Português) - ArchWiki

Jump to content
From ArchWiki
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.

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-gitAUR: `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
    }

Category:

- Arch package guidelines (Português)