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.

Nota:

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.

Nota:

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.

Nota:

É 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.

Dica:

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

Nota:

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.

Dica:

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

Dica:

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 Seção 8.6, “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.

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>.