A primeira parte do Makefile
do port o nomeia, descreve seu número de versão e o lista na categoria correta.
Setar PORTNAME
ao nome base do software. Isso é usado como base para o pacote do FreeBSD, e para o DISTNAME
.
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
.
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 PORTVERSION
e não DISTVERSION
.
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
.
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.”.
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
<![]()
%
pkg version -t 1.2 1.2
=![]()
%
pkg version -t 1.2 1.2.0
=![]()
%
pkg version -t 1.2 1.2.p1
>![]()
%
pkg version -t 1.2.a1 1.2.b1
<![]()
%
pkg version -t 1.2 1.2p1
<
| |
| |
| |
| |
| |
|
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.
DISTVERSION
e de Derivações PORTVERSION
.DISTVERSION | PORTVERSION |
---|---|
0.7.1d | 0.7.1.d |
10Alpha3 | 10.a3 |
3Beta7-pre2 | 3.b7.p2 |
8:f_17 | 8f.17 |
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
.
DISTVERSION
Quando a Versão Começa com uma Letra ou um PrefixoQuando 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
.
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
<
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
>![]()
%
pkg version -t 1.2 1.2p4
<
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
”.
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.
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.
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).
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.
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
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.
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
.
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 d
, não yyyy
.mm
.dd
ou o não compatível com o formato Y2K dd
.mm
.yyyy
. É importante prefixar a versão com uma letra, aquiyy
.mm
.dd
d
(para data), no caso de uma versão com um número de versão real, que seria numericamente inferior a
.yyyy
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
:
Nome da Distribuição | PKGNAMEPREFIX | PORTNAME | PKGNAMESUFFIX | DISTVERSION | PORTVERSION | Razão ou comentário |
---|---|---|---|---|---|---|
mule-2.2.2 | (vazio) | mule | (vazio) | 2.2.2 | Nenhuma alteração é necessária | |
mule-1.0.1 | (vazio) | mule | 1 | 1.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.3 | O que diabos foi isso afinal? | |
tvtwm | (vazio) | tvtwm | (vazio) | p11 | Nenhuma 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.pl1 | Nesse caso,pl1 significa nível de patch, então usar DISTVERSION não é possível. | |
gawk-2.15.6 | ja- | gawk | (vazio) | 2.15.6 | Versão em japonês | |
psutils-1.13 | (vazio) | psutils | -letter | 1.13 | Tamanho do papel codificado no tempo de compilação do pacote | |
pkfonts | (vazio) | pkfonts | 300 | 1.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 (d
ou yyyy
.mm
.dd
d
) como a versão.yyyy
mm
dd
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>.