5.2. Nomeando

A primeira parte do Makefile do port o nomeia, descreve seu número de versão e o lista na categoria correta.

5.2.1. PORTNAME

Setar PORTNAME ao nome base do software. Isso é usado como base para o pacote do FreeBSD, e para o DISTNAME.

Importante:

O nome do pacote deve ser único em toda a árvore de ports. Certifique-se de que o PORTNAME já não está em uso por um port existente, e que nenhum outro port já tem o mesmo PKGBASE. Se o nome já tiver sido usado, adicione PKGNAMEPREFIX ou PKGNAMESUFFIX.

5.2.2. Versões, DISTVERSION ou PORTVERSION

Setar DISTVERSION para o número da versão do software.

PORTVERSION é a versão usada para o pacote do FreeBSD. Será automaticamente derivado de DISTVERSION para ser compatível com o esquema de versionamento de pacotes do FreeBSD. Se a versão contiver letras, pode ser necessário definir PORTVERSIONe não DISTVERSION.

Importante:

Não é possível utilizar PORTVERSION e DISTVERSION juntos, deve ser ser definido um de cada vez.

De tempos em tempos, alguns softwares usam um esquema de versão que não é compatível em como o DISTVERSION traduz a versão no PORTVERSION.

Dica:

Ao atualizar um port, é possível usar o pkg-version(8) -t para verificar se a nova versão é maior ou menor do que antes. Veja Exemplo 5.1, “Usando pkg-version(8) para comparar versões.”.

Exemplo 5.1. Usando pkg-version(8) para comparar versões.

pkg version -t recebe duas versões como argumentos, responderá com <, = ou > se a primeira versão for menor, igual ou maior que a segunda versão, respectivamente.

% pkg version -t 1.2 1.3
< 1
% pkg version -t 1.2 1.2
= 2
% pkg version -t 1.2 1.2.0
= 3
% pkg version -t 1.2 1.2.p1
> 4
% pkg version -t 1.2.a1 1.2.b1
< 5
% pkg version -t 1.2 1.2p1
< 6

1

1.2 é menor que 1.3.

3

1.2 e 1.2 são iguais, pois têm a mesma versão.

3

1.2 e 1.2.0 são iguais, pois valor vazio é igual a zero.

4

1.2 é maior que 1.2.p1 por causa do .p1, pense em pre-release 1.

4

1.2.a1 é menor que 1.2.b1, pense em alfa e beta e a é menor que b.

6

1.2 é menor que 1.2p1 por causa do 2p1, pense em 2, nível de patch 1 que é uma versão depois de qualquer 2.X mas antes de 3.

Nota:

Aqui, a, b e p são usados ​​como se significassem alfa, beta ou pre-release e nível de patch, mas elas são apenas letras e são classificados por ordem alfabética, portanto, qualquer letra pode ser utilizada, e elas serão ordenadas de forma adequada.


Tabela 5.1. Exemplos de DISTVERSION e de Derivações PORTVERSION
DISTVERSIONPORTVERSION
0.7.1d0.7.1.d
10Alpha310.a3
3Beta7-pre23.b7.p2
8:f_178f.17

Exemplo 5.2. Usando DISTVERSION

Quando a versão contém apenas números separados por pontos, traços ou sublinhados, use DISTVERSION.

PORTNAME=   nekoto
DISTVERSION=	1.2-4

Isso irá gerar um PORTVERSION 1.2.4.


Exemplo 5.3. Usando DISTVERSION Quando a Versão Começa com uma Letra ou um Prefixo

Quando a versão começa ou termina com uma letra, um prefixo ou um sufixo que não faz parte da versão, use DISTVERSIONPREFIX, DISTVERSION e DISTVERSIONSUFFIX.

Se a versão for v1.2-4:

PORTNAME=   nekoto
DISTVERSIONPREFIX=  v
DISTVERSION=	1_2_4

Algumas vezes, projetos usando GitHub usará seu nome em suas versões. Por exemplo, a versão pode ser nekoto-1.2-4:

PORTNAME=   nekoto
DISTVERSIONPREFIX=  nekoto-
DISTVERSION=	1.2_4

Esses projetos também usam algumas strings no final da versão, por exemplo,1.2-4_RELEASE:

PORTNAME=   nekoto
DISTVERSION=	1.2-4
DISTVERSIONSUFFIX=  _RELEASE

Ou eles fazem ambos, por exemplo,nekoto-1.2-4_RELEASE:

PORTNAME=   nekoto
DISTVERSIONPREFIX=  nekoto-
DISTVERSION=	1.2-4
DISTVERSIONSUFFIX=  _RELEASE

DISTVERSIONPREFIX e DISTVERSIONSUFFIX não serão usados durante a construção do PORTVERSION, mas usado apenas em DISTNAME.

Todos exemplos irão gerar um PORTVERSION com valor 1.2.4.


Exemplo 5.4. Usando DISTVERSION Quando a Versão Contém Letras Significando alpha, beta ou pre-release

Quando a versão contém números separados por pontos, traços ou underlines, e letras são usadas para significar alpha, beta ou pre-release, no sentido de que vem antes das versões sem letras, use DISTVERSION.

PORTNAME=   nekoto
DISTVERSION=	1.2-pre4
PORTNAME=   nekoto
DISTVERSION=	1.2p4

Ambos irão gerar um PORTVERSION com valor 1.2.p4 que é menor do que 1.2. pkg-version(8) pode ser usado para verificar esse fato:

% pkg version -t 1.2.p4 1.2
<

Exemplo 5.5. Não use DISTVERSION Quando a Versão Contém Letras que Significam "Nível de Patch"

Quando a versão contém letras que não significam alpha, beta ou pre, e estão mais para um nível de patch, no sentido de que vem depois da versão sem as letras, use PORTVERSION.

PORTNAME=   nekoto
PORTVERSION=	1.2p4

Neste caso, usar DISTVERSION não é possível porque geraria uma versão 1.2.p4 o que seria menor que 1.2 e não maior.pkg-version(8) irá constatar isso:

% pkg version -t 1.2 1.2.p4
> 1
% pkg version -t 1.2 1.2p4
< 2

1

1.2 é maior que 1.2.p4, o que é errado nesse caso.

2

1.2 é menor que 1.2p4, que é o que era necessário.


Para alguns exemplos mais avançados de configuração do PORTVERSION, quando a versão do software não é realmente compatível com o FreeBSD, ou DISTNAME quando o arquivo de distribuição não contém a versão em si, consulte Seção 5.4.1, “DISTNAME.

5.2.3. PORTREVISION e PORTEPOCH

5.2.3.1. PORTREVISION

PORTREVISION é um valor monotonicamente crescente que é redefinido para 0 com cada incremento de DISTVERSION, normalmente toda vez que houver uma nova versão oficial do fornecedor. E se PORTREVISION é diferente de zero, o valor é anexado ao nome do pacote. Mudanças em PORTREVISION são usadas ​​por ferramentas automatizadas como pkg-version(8) para determinar se um novo pacote está disponível.

PORTREVISION deve ser incrementado toda vez que uma alteração for feita no port onde se altera o pacote gerado de alguma forma. Isso inclui alterações que afetam apenas um pacote compilado com options não padrão.

Exemplos de quando PORTREVISION deve ser alterado:

  • Adição de correções para corrigir vulnerabilidades de segurança, bugs ou para adicionar novas funcionalidades ao port.

  • Alterações no Makefile do port para ativar ou desativar as opções de tempo de compilação no pacote.

  • Alterações na lista de empacotamento ou no comportamento de tempo de instalação do pacote. Por exemplo, uma alteração em um script que gera dados iniciais para o pacote, como chaves de host ssh(1).

  • Bump de versão da dependência de biblioteca compartilhada de um port (nesse caso, alguém tentando instalar o pacote antigo depois de instalar uma versão mais nova da dependência falhará, pois procurará a libfoo.x antiga em vez da libfoo.(x+1)).

  • Mudanças silenciosas no distfile do port que possuem diferenças funcionais significativas. Por exemplo, mudanças no distfile que requerem uma correção para distinfo sem alteração correspondente para DISTVERSION, onde umdiff -ru das versões antiga e nova mostra mudanças não triviais no código.

Exemplos de alterações que não requerem uma alteração no PORTREVISION:

  • Mudanças de estilo no esqueleto do port sem alteração funcional ao que aparece no pacote resultante.

  • Mudanças para MASTER_SITES ou outras alterações funcionais no port que não afetem o pacote resultante.

  • Patches triviais para o distfile, como correção de erros de digitação, que não são importantes o suficiente para que os usuários do pacote tenham que se dar ao trabalho de atualizar.

  • Correções de compilação que fazem com que um pacote se torne compilável onde antes estava falhando. Desde que as alterações não introduzam nenhuma mudança funcional em nenhuma outra plataforma na qual o port tenha sido compilado anteriormente. PORTREVISION reflete o conteúdo do pacote, se o pacote não foi compilado anteriormente, então não há necessidade de incrementar o PORTREVISION para registrar uma mudança.

Uma regra geral é decidir se a mudança em um port é algo que algumas pessoas se beneficiariam em ter. Por causa de um aprimoramento, conserto ou em virtude de que o novo pacote funcione de fato. Em seguida, pondere que, de fato, isso fará com que todos que regularmente atualizam sua árvore de ports sejam obrigados a atualiza-lo. Se sim, PORTREVISION deve ser incrementado.

Nota:

Pessoas usando pacotes binários nunca verão a atualização se PORTREVISION não for incrementado. Sem incrementar PORTREVISION, os package builders não têm como detectar a alteração e, portanto, não irão recompilar o pacote.

5.2.3.2. PORTEPOCH

De tempos em tempos, um fornecedor de software ou um mantenedor de port do FreeBSD fazem algo tolo e lançam uma versão de seu software que é numericamente menor que a versão anterior. Um exemplo disso é um port que vai de foo-20000801 para foo-1.0 ( o primeiro será incorretamente tratado como uma versão mais nova, já que 20000801 é um valor numericamente maior que 1).

Dica:

Os resultados das comparações de números de versão nem sempre são óbvios. pkg version (veja pkg-version(8)) pode ser usado para testar a comparação de duas sequências de números de versão. Por exemplo:

% pkg version -t 0.031 0.29
>

A saida > indica que a versão 0.031 é considerada maior que a versão 0.29, o que pode não ter sido óbvio para o mantenedor do port.

Em situações como essa, PORTEPOCH deve ser incrementado. E se PORTEPOCH é diferente de zero, ele é anexado ao nome do pacote conforme descrito na seção 0 acima. PORTEPOCH nunca deve ser diminuído ou redefinido para zero, porque isso faria com que a comparação com um pacote de uma época anterior falhasse. Por exemplo, o pacote não seria detectado como desatualizado. O novo número da versão, 1.0.1 no exemplo acima, ainda é numericamente menor que a versão anterior, 20000801, mas o sufixo 1 é tratado especialmente por ferramentas automatizadas e considerado maior que o sufixo 0 implícito no pacote anterior.

Remover ou resetar o PORTEPOCH incorretamente conduz ao luto eterno. Se a discussão acima não foi clara o suficiente, por favor consulte a Lista de discussão de ports do FreeBSD.

É esperado que PORTEPOCH não seja utilizado na maioria dos ports, e que seja feito o uso sensato do DISTVERSION, ou que o PORTVERSION seja usado com cuidado também, isso muitas vezes pode evitar que uma versão futura do software altere a estrutura da versão. No entanto, é necessário que os porters do FreeBSD tenham cuidado quando uma versão do fornecedor é feita sem um número de versão oficial - como um código de release snapshot. A tentação é rotular a release com a data de lançamento, o que causará problemas como no exemplo acima, quando um novo release oficial é feito.

Por exemplo, se um snapshot de release é feito na data 20000917 e a versão anterior do software era a versão 1.2, não use 20000917 no DISTVERSION. A maneira correta é um DISTVERSION com valor 1.2.20000917, ou similar, para que a próxima versão, digamos 1.3, ainda seja um valor numericamente maior.

5.2.3.3. Exemplo de Uso PORTREVISION e PORTEPOCH

O port gtkmumble, versão0.10 está comitado na coleção de ports:

PORTNAME=	gtkmumble
DISTVERSION=	0.10

PKGNAME torna-se gtkmumble-0.10.

Uma falha de segurança é descoberta, o que requer um patch local do FreeBSD. PORTREVISION é alterado de acordo.

PORTNAME=	gtkmumble
DISTVERSION=	0.10
PORTREVISION=	1

PKGNAME torna-se gtkmumble-0.10_1

Uma nova versão é lançada pelo fornecedor, numerada como 0.2 (acontece que o autor realmente pretendia que 0.10 significa-se realmente 0.1.0, não o que vem depois de 0.9 - oops, tarde demais agora). Como a nova versão secundária 2 é numericamente menor que a versão anterior 10, PORTEPOCH deve ser incrementado para forçar manualmente que o novo pacote seja detectado como mais recente. Como é uma nova versão do fornecedor, PORTREVISION é redefinido para 0 (ou removido doMakefile).

PORTNAME=	gtkmumble
DISTVERSION=	0.2
PORTEPOCH=	1

PKGNAME torna-se gtkmumble-0.2,1

O próximo lançamento é 0.3. Desde que PORTEPOCH nunca diminua, as variáveis ​​de versão são agora:

PORTNAME=	gtkmumble
DISTVERSION=	0.3
PORTEPOCH=	1

PKGNAME torna-se gtkmumble-0.3,1

Nota:

E se PORTEPOCH for redefinido para 0 com esta atualização, alguém que instalou o gtkmumble-0.10_1 não detectaria o gtkmumble-0.3 como pacote mais novo, desde que 3 ainda é numericamente menor que 10. Lembre-se, este é o ponto principal de PORTEPOCH em primeiro lugar.

5.2.4. PKGNAMEPREFIX e PKGNAMESUFFIX

Duas variáveis ​​opcionais, PKGNAMEPREFIX e PKGNAMESUFFIX, são combinadas com PORTNAME e PORTVERSION para formar PKGNAME como ${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}. Certifique-se de que isto está de acordo com as nossas diretrizes para um bom nome de pacote. Em particular, o uso de um hífen (-) dentro de PORTVERSION não é permitido. Além disso, se o nome do pacote tiver o language- ou a parte -compiled.specifics (veja abaixo), use PKGNAMEPREFIX e PKGNAMESUFFIX, respectivamente. Não os faça parte de PORTNAME.

5.2.5. Convenções de Nomenclatura de Pacotes

Estas são as convenções a serem seguidas ao nomear pacotes. Isso é para facilitar a varredura do diretório de pacotes, já que existem milhares de pacotes e os usuários irão pegar ranço se eles machucarem seus olhos!

Nomes de pacotes tomam a forma de language_region-name-compiled.specifics-version.numbers.

O nome do pacote é definido como ${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}. Certifique-se de definir as variáveis ​​para estar em conformidade com esse formato.

language_region-

O FreeBSD se esforça para suportar a linguagem nativa de seus usuários. A parte language- é uma abreviação de duas letras da linguagem natural definida pela ISO-639 quando o port é específico para um determinado idioma. Exemplos são ja para japonês, ru para russo,vi para vietnamita, zh para o chinês, ko para coreano e de para alemão.

Se o port for específico de uma determinada região dentro da área de idioma, adicione também o código do país de duas letras. Exemplos são en_US para Inglês dos EUA e fr_CH para o Francês Suíço.

A parte language- é definida em PKGNAMEPREFIX.

name

Certifique-se de que o nome e a versão do port estejam claramente separados e colocados em PORTNAME e DISTVERSION. A única razão para PORTNAME conter uma parte da versão é se a distribuição upstream é realmente chamada dessa forma, como no textproc/libxml2 ou japanese/kinput2-freewnn. De outra forma, PORTNAME não pode conter informações específicas da versão. É normal que vários ports tenham o mesmo PORTNAME, como os ports www/apache * fazem; Nesse caso, versões diferentes (e entradas de índice diferentes) são distinguidas por valores PKGNAMEPREFIX e PKGNAMESUFFIX.

Há uma tradição de nomear módulos Perl 5 com sufixo p5- e convertendo o separador de dois pontos para um hífen. Por exemplo, o modulo Data::Dumper torna-se p5-Data-Dumper.

-compiled.specifics

Se o port pode ser construído com diferentes padrões codificados (geralmente parte do nome do diretório em uma família de ports), a parte -compiled.specifics indica os padrões compilados. O hífen é opcional. Exemplos são tamanho de papel e unidades de fonte.

A parte -compiled.specifics é definida em PKGNAMESUFFIX.

-version.numbers

A string da versão segue um hífen (-) e é uma lista separada por pontos de números inteiros e letras minúsculas. Em particular, não é permitido ter outro hífen dentro da string de versão. A única exceção é a string pl (significando patchlevel), que pode ser usado apenas quando não há números de versão maiores e menores no software. Se a versão do software tiver sequências como alpha, beta, rc ou pre, use a primeira letra e coloque imediatamente após um ponto. Se a sequência da versão continuar após esses nomes, os números seguirão o alfabeto simples sem um ponto extra entre eles (por exemplo,1.0b2).

A ideia é facilitar a classificação dos ports observando a string de versão. Em particular, certifique-se de que os componentes do número da versão estejam sempre delimitados por um ponto e, se a data fizer parte da string, use o formato dyyyy.mm.dd, não dd.mm.yyyy ou o não compatível com o formato Y2K yy.mm.dd. É importante prefixar a versão com uma letra, aquid (para data), no caso de uma versão com um número de versão real, que seria numericamente inferior a yyyy.

Importante:

O nome do pacote deve ser único entre todos os ports, verifique se ainda não existe um port com o mesmo PORTNAME e se houver, adicione um dos PKGNAMEPREFIX ou PKGNAMESUFFIX.

Aqui estão alguns exemplos (reais) de como converter o nome como chamado pelos autores do software para um nome de pacote adequado, para cada linha, apenas um dos DISTVERSION ou PORTVERSION está definido, dependendo de qual seria usado no Makefile:

Tabela 5.2. Exemplos de Nomes de Pacotes
Nome da DistribuiçãoPKGNAMEPREFIXPORTNAMEPKGNAMESUFFIXDISTVERSIONPORTVERSIONRazão ou comentário
mule-2.2.2(vazio)mule(vazio)2.2.2 Nenhuma alteração é necessária
mule-1.0.1(vazio)mule11.0.1 Esta é a versão 1 do mule e a versão 2 já existe
EmiClock-1.0.2(vazio)emiclock(vazio)1.0.2 Sem nomes em maiúsculas para programas individuais
rdist-1.3alpha(vazio)rdist(vazio)1.3alfa Versão será 1.3.a
es-0.9-beta1(vazio)es(vazio)0.9-beta1 Versão será 0.9.b1
mailman-2.0rc3(vazio)mailman(vazio)2.0rc3 Versão será2.0.r3
v3.3beta021.src(vazio)tiff(vazio) 3.3O que diabos foi isso afinal?
tvtwm(vazio)tvtwm(vazio) p11Nenhuma versão no nome do arquivo, use o que o upstream diz que é
piewm(vazio)piewm(vazio)1.0 Nenhuma versão no nome do arquivo, use o que o upstream diz que é
xvgr-2.10pl1(vazio)xvgr(vazio) 2.10.pl1Nesse caso,pl1 significa nível de patch, então usar DISTVERSION não é possível.
gawk-2.15.6ja-gawk(vazio)2.15.6 Versão em japonês
psutils-1.13(vazio)psutils-letter1.13 Tamanho do papel codificado no tempo de compilação do pacote
pkfonts(vazio)pkfonts3001.0 Pacote para fontes de 300dpi

Se não houver absolutamente nenhum rastro de informações de versão co código fonte original e é improvável que o autor original vá liberar outra versão, basta definir a string de versão para 1.0 (como o exemplo piewm acima). Caso contrário, pergunte ao autor original ou use a string de data com valor de quando a código fonte foi lançado como (dyyyy.mm.dd ou dyyyymmdd) como a versão.

Dica:

Use qualquer letra. Aqui,d significa data, se o código for um repositório do Git, g seguido pela data de commit é normalmente utilizado, s para snapshot também é comum.

All FreeBSD documents are available for download at https://download.freebsd.org/ftp/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.