Capítulo 3. Port Rápido

Esta seção descreve como criar rapidamente um novo port. Para aplicativos em que esse método rápido não for adequado, o processo "Slow Porting" está descrito no Port Lento.

Primeiro, obtenha o tarball original e coloque-o em DISTDIR, que por padrão é o diretório /usr/ports/distfiles.

Estas etapas assumem que o software foi compilado de forma simples (out-of-the-box). Em outras palavras, não foi necessária absolutamente nenhuma mudança para o aplicativo funcionar em um sistema FreeBSD. Se alguma coisa teve que ser alterada, por favor consulte o Port Lento.

Recomenda-se definir a variável DEVELOPER do make(1) em /etc/make.conf antes de começar o trabalho com os ports.

# echo DEVELOPER=yes >> /etc/make.conf

Esta configuração habilita o "modo de desenvolvedor" que exibe avisos sobre a descontinuidade de comandos e ativa algumas verificações de qualidade adicionais nas execuções do comando make.

3.1. Escrevendo o Makefile

O Makefile mínimo seria algo assim:

# $FreeBSD: head/pt_BR.ISO8859-1/books/porters-handbook/book.xml 54410 2020-08-05 22:13:01Z dbaio $

PORTNAME=	oneko
DISTVERSION=	1.1b
CATEGORIES=	games
MASTER_SITES=	ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/

MAINTAINER=	youremail@example.com
COMMENT=	Cat chasing a mouse all over the screen

.include <bsd.port.mk>

Em alguns casos, o Makefile de um port existente pode conter linhas adicionais no cabeçalho, como o nome do port e a data em que foi criado. Esta informação adicional foi declarada obsoleta e está sendo eliminada.

Tente entender o exemplo. Não se preocupe com o conteúdo da linha $FreeBSD: head/pt_BR.ISO8859-1/books/porters-handbook/book.xml 54410 2020-08-05 22:13:01Z dbaio $, ela será preenchida automaticamente pelo Subversion quando o port for importado para nossa árvore de ports principais. Um exemplo mais detalhado é mostrado na seção exemplo de Makefile.

3.2. Escrevendo os Arquivos de Descrição

Existem dois arquivos de descrição que são necessários para qualquer port, independente deles estarem empacotados ou não. Eles são o pkg-descr e o pkg-plist. Seus prefixos pkg- distingue-os de outros arquivos.

3.2.1. pkg-descr

Esta é uma descrição mais longa do port. Um ou alguns parágrafos que explicam o que o port faz é suficiente.

Isto não é um manual ou uma descrição detalhada sobre como usar ou compilar o port! Por favor, tenha cuidado ao copiar do README ou manpage. Muitas vezes, eles não são uma descrição concisa do port ou estão em um formato estranho. Por exemplo, as páginas de manual têm espaçamento justificado, o que parece particularmente ruim com fontes monoespaçadas.

Por outro lado, o conteúdo de pkg-descr deve ser mais longo que a linha COMMENT do Makefile. Ele deve explicar com mais profundidade o que é o port.

Um pkg-descr bem escrito descreve o port completamente o suficiente para que os usuários não precisem consultar a documentação ou visitar o site para entender o que o software faz, como ele pode ser útil ou quais recursos particularmente legais ​​ele possui. A menção de certos requisitos, como um kit de ferramentas gráfico, dependências pesadas, ambiente de runtime ou linguagens de implementação, ajuda os usuários a decidir se este port funcionará para eles.

Inclua uma URL para a página Web oficial. Prefixe um dos sites (escolha o mais comum) com WWW: (seguido por um único espaço) para que as ferramentas automatizadas funcionem corretamente. Se a URI é a raiz do site ou diretório, ele deve ser terminado com uma barra.

Se a página web listada para um port não estiver disponível, tente pesquisar na Internet primeiro para ver se o site oficial foi movido, foi renomeado ou se está hospedado em outro lugar.

Este exemplo mostra como parece o pkg-descr:

This is a port of oneko, in which a cat chases a poor mouse all over
the screen.
 :
(etc.)

WWW: http://www.oneko.org/

3.2.2. pkg-plist

Este arquivo lista todos os arquivos instalados pelo port. Ele também é chamado de "packing list" (lista de empacotamento) porque o pacote é gerado empacotando os arquivos listados aqui. Os pathnames são relativos ao prefixo de instalação (geralmente /usr/local).

Aqui está um pequeno exemplo:

bin/oneko
man/man1/oneko.1.gz
lib/X11/app-defaults/Oneko
lib/X11/oneko/cat1.xpm
lib/X11/oneko/cat2.xpm
lib/X11/oneko/mouse.xpm

Consulte a manpage do pkg-create(8) para detalhes sobre a lista de empacotamento.

É recomendado manter todos os nomes de arquivos neste arquivo classificados em ordem alfabética. Isso tornará muito mais fácil verificar as alterações ao atualizar o port.

Criar uma lista de packing manualmente pode ser uma tarefa muito tediosa. Se o port instalar um grande número de arquivos, criar a lista de empacotamento automaticamente pode economizar tempo.

Há apenas um caso em que o pkg-plist pode ser omitido de um port. Se o port instalar apenas alguns arquivos, liste-os em PLIST_FILES, dentro do Makefile do port. Por exemplo, poderíamos passar sem o pkg-plist no port oneko acima, adicionando estas linhas para no Makefile:

PLIST_FILES=	bin/oneko \
		man/man1/oneko.1.gz \
		lib/X11/app-defaults/Oneko \
		lib/X11/oneko/cat1.xpm \
		lib/X11/oneko/cat2.xpm \
		lib/X11/oneko/mouse.xpm

Uso de PLIST_FILES não deve ser abusado. Ao procurar pela origem de um arquivo, as pessoas geralmente tentam usar o grep através do pkg-plist nos arquivos na árvore de ports. Listar os arquivos na variável PLIST_FILES dentro do Makefile torna esta busca mais difícil.

Se um port precisar criar um diretório vazio, ou criar diretórios fora do ${PREFIX} durante a instalação, consulte Limpando Diretórios Vazios para maiores informações.

Como PLIST_FILES é uma variavel do make(1), qualquer entrada com espaços deve ser envolvida por aspas. Por exemplo, se estiver usando palavras-chave descritas em pkg-create(8) e na Expandindo a Lista de Pacotes com Keywords, a entrada deve ser citada.

PLIST_FILES=	"@sample ${ETCDIR}/oneko.conf.sample"

Mais tarde vamos ver como o pkg-plist e a PLIST_FILES podem ser utilizados para executar tarefas mais sofisticadas.

3.3. Criando o Arquivo Checksum

Apenas digite make makesum. O framework do ports irá gerar automaticamente o distinfo. Não tente gerar o arquivo manualmente.

3.4. Testando o Port

Certifique-se de que as regras do port façam exatamente o que é desejado, incluindo o empacotamento do port. Estes são os pontos importantes a serem verificados:

  • pkg-plist não contém nada não instalado pelo port.

  • pkg-plist contém tudo o que é instalado pelo port.

  • O port pode ser instalado usando o target install. Isso verifica se o script de instalação está funcionando corretamente.

  • O port pode ser desinstalado adequadamente usando o target deinstall. Isso verifica se o script de desinstalação funciona corretamente.

  • O port só tem acesso aos recursos de rede durante a fase target fetch. Isto é importante para os construtores de pacotes, tais como o ports-mgmt/poudriere.

  • Certifique-se de que o comando make package pode ser executado como um usuário normal (ou seja, não como root). Se isso falhar, talvez seja necessário corrigir o software. Veja a fakeroot e também a uidfix.

Procedure: Ordem Recomendada de Teste

  1. make stage

  2. make stage-qa

  3. make package

  4. make install

  5. make deinstall

  6. make package (como usuário)

Certifique-se de que nenhum aviso é exibido em nenhum dos estágios.

Testes automatizados completos podem ser feitos com o ports-mgmt/poudriere da coleção do Ports, veja a Poudriere para maiores informações. Ele mantém jails onde todas as etapas mostradas acima podem ser testadas sem afetar o estado do sistema host.

3.5. Verificando o Port com portlint

Por favor, use o portlint para ver se o port está de acordo com as nossas diretrizes. O programa ports-mgmt/portlint faz parte da coleção de ports. Em particular, ele verifica se o Makefile está correto e se o pacote está nomeado apropriadamente.

Não siga cegamente a saída do portlint. Ela é uma ferramenta de lint estática e às vezes comete erros.

3.6. Enviando o Novo Port

Antes de enviar o novo port, leia a seção sobre o que fazer e o que não fazer.

Uma vez feliz com o port, a única coisa que resta é colocá-lo na árvore principal do FreeBSD e deixar todo mundo feliz também.

Nós não precisamos do diretório work ou do pacote pkgname.tgz, então exclua-os agora.

Em seguida, crie um patch(1). Assumindo que o port é chamado oneko e está na categoria games.

Exemplo 1. Criando um .diff para um Novo Port

Adicione todos os arquivos com svn add. Utilize o cd e vá para a base da árvore de ports, para que os caminhos completos dos arquivos alterados sejam incluídos no diff, então gere o diff com svn diff. Por exemplo:

% svn add .
% cd ../..
% svn diff games/oneko > oneko.diff

Para ser mais fácil para os committers aplicarem o patch em sua cópia de trabalho da árvore de ports, por favor, gere o .diff da base da sua árvore de ports.

Envie o oneko.diff com o formulário de submissão de bugs. Use product "Ports & Packages", component "Individual Port(s)" e siga as diretrizes mostradas lá. Adicione uma breve descrição do programa ao campo Description do PR (talvez uma versão curta do COMMENT), e lembre-se de adicionar o oneko.diff como um anexo.

Dar uma boa descrição no resumo do relatório de problema facilita muito o trabalho dos commiters de ports. Preferimos algo como "New port: `category/portname breve descrição do port`" para novos ports. Usar este esquema torna mais fácil e rápido começar o trabalho para fazer o commit de um novo port.

Depois de enviar o port, por favor, seja paciente. O tempo necessário para incluir um novo port no FreeBSD pode variar de alguns dias até alguns meses. Um formulário simples de pesquisa no banco de dados do Relatório de Problemas está disponível em https://bugs.freebsd.org/bugzilla/query.cgi.

Para obter uma listagem dos PRs abertos para os ports, selecione Open e Ports & Packages no formulário de pesquisa, clique em Search.

Depois de analisar o novo port, nós responderemos se necessário, e iremos adicioná-lo a árvore. O nome do remetente também será adicionado à lista de Contribuidores Adicionais do FreeBSD e outros arquivos.

Também é possível enviar ports usando um arquivo shar(1). Usando o exemplo anterior com o port oneko acima.

Exemplo 2. Criando um .shar para um Novo Port

vá para o diretório acima, onde o diretório do port está localizado, e use tar para criar o arquivo shar:

% cd ..
% tar cf oneko.shar --format shar oneko

oneko.shar pode ser enviado da mesma maneira que oneko.diff acima.


Última alteração em: 11 de dezembro de 2021 por Sergio Carlavilla Delgado