Capítulo 9. pkg-*

9.1. pkg-message

Para exibir uma mensagem quando o pacote é instalado, coloque a mensagem no pkg-message . Esse recurso é geralmente útil para exibir etapas adicionais de instalação a serem executadas após o pkg install ou pkg upgrade .

pkg-message deve conter apenas informações vitais de setup e operação no FreeBSD, e isso é único para o port em questão.
As informações de configuração devem ser mostradas apenas na instalação inicial. As instruções de atualização devem ser exibidas apenas ao atualizar a versão relevante.
Não coloque as mensagens entre espaços em branco ou linhas de símbolos (como ---------- , , ou ========== ). Deixe a formatação com o pkg(8) .
Os committers têm aprovação implícita para restringir as mensagens existentes na hora da instalação ou em intervalos de atualização, usando as especificações do formato UCL.

pkg-message suporta dois formatos:

raw: Um arquivo de texto simples comum. Sua mensagem é exibida apenas na instalação.
UCL: Se o arquivo começar com “[” será considerado como um arquivo UCL. O formato UCL é descrito na página libucl no GitHub .

Não adicione uma entrada para o pkg-message ao pkg-plist .

9.1.1. UCL no pkg-message

O formato é o seguinte. Deve ser uma matriz de objetos. Os objetos em si podem ter essas palavras-chave:

message: A mensagem atual a ser exibida. Esta palavra-chave é obrigatória.
type: Quando a mensagem deve ser exibida.
maximum_version: Somente se type for upgrade . Exibe se estiver atualizando de uma versão inferior que a versão especificada.
minimum_version: Somente se type for upgrade . Exibe se estiver atualizando de uma versão maior que a versão especificada.

As palavras-chave maximum_version e minimum_version podem ser combinadas.

A palavra-chave type pode ter três valores:

install: A mensagem só deve ser exibida quando o pacote é instalado.
remove: A mensagem só deve ser exibida quando o pacote é removido.
upgrade: a mensagem só deve ser exibida durante uma atualização do pacote.

Para preservar a compatibilidade com arquivos pkg-message não UCL, a primeira linha de um arquivo pkg-message UCL DEVE ter um simples “[”, e a última linha DEVE ter um simples “]”.

Exemplo 1. Strings Curtas UCL

A mensagem é delimitada por aspas duplas " , isto é utilizado em strings simples de linha única:

[
{ type: install
  message: "Simple message"
}
]

Exemplo 2. Strings de Múltiplas Linhas UCL

Strings de múltiplas linhas utiliza o padrão here de documento de notação. O delimitador de múltiplas linhas deve iniciar logo após os símbolos << sem espaço em branco, e ele deve ser apenas em letras maiúsculas. Para finalizar uma sequência de múltiplas linhas, adicione o delimitador em uma linha única, sem nenhum espaço em branco. A mensagem de Strings Curtas UCL pode ser escrita como:

[
{ type: install
  message: <<EOM
Simple message
EOM
}
]

Exemplo 3. Exibir uma Mensagem na Instalação/Desinstalação

Quando uma mensagem precisa ser exibida apenas na instalação ou na desinstalação, defina o tipo:

[
{
  type: remove
  message: "package being removed."
}
{ type: install, message: "package being installed."}
]

Exemplo 4. Exibir uma Mensagem na Atualização

Quando um port é atualizado, a mensagem exibida pode ser ainda mais adaptada às necessidades do port.

[
{
  type: upgrade
  message: "Package is being upgraded."
}
{
  type: upgrade
  maximum_version: "1.0"
  message: "Upgrading from before 1.0 need to do this."
}
{
  type: upgrade
  minimum_version: "1.0"
  message: "Upgrading from after 1.0 should do that."
}
{
  type: upgrade
  maximum_version: "3.0"
  minimum_version: "1.0"
  message: "Upgrading from > 1.0 and < 3.0 remove that file."
}
]

Ao exibir uma mensagem na atualização, é importante limitar até quando ela será mostrada ao usuário. Na maioria das vezes, é usado o maximum_version para limitar seu uso a atualizações anteriores a uma certa versão, quando algo específico precisa ser feito.

9.2. pkg-install

Se o port precisa executar comandos quando o pacote binário é instalado com o pkg add ou com o pkg install , use o pkg-install . Este script será automaticamente adicionado ao pacote. Será executado duas vezes pelo pkg , a primeira vez como ${SH} pkg-install ${PKGNAME} PRE-INSTALL antes que o pacote seja instalado e uma segunda vez como ${SH} pkg-install ${PKGNAME} POST-INSTALL depois dele ter sido instalado. O valor de $2 pode ser testado para determinar em que modo o script está sendo executado. A variável de ambiente PKG_PREFIX será definida para o diretório de instalação do pacote.

Este script está aqui para ajudá-lo a configurar o pacote para que ele esteja tão pronto quanto possível para ser usado. Ele não deve ser abusado para iniciar serviços, interromper serviços ou executar quaisquer outros comandos que modificarão o sistema em execução no momento.

9.3. pkg-deinstall

Este script é executado quando um pacote é removido.

Este script será executado duas vezes pelo pkg delete . A primeira vez como ${SH} pkg-deinstall ${PKGNAME} DEINSTALL antes que o port seja desinstalado e a segunda vez como ${SH} pkg-deinstall ${PKGNAME} POST-DEINSTALL após o port ter sido desinstalado. O valor de $2 pode ser testado para determinar em que modo o script está sendo executado. A variável de ambiente PKG_PREFIX será definida para o diretório de instalação do pacote

Este script está aqui para ajudá-lo a configurar o pacote para que ele esteja tão pronto quanto possível para ser usado. Ele não deve ser abusado para iniciar serviços, interromper serviços ou executar quaisquer outros comandos que modificarão o sistema em execução no momento.

9.4. Mudando os nomes dos pkg-*

Todos os nomes de pkg- são definidos usando variáveis que podem ser alteradas no Makefile se necessário. Isso é especialmente útil ao compartilhar os mesmos arquivos pkg- entre vários ports ou quando é necessário gravar em um desses arquivos. Veja escrevendo em lugares que não o WRKDIR para entender por que é uma má ideia escrever diretamente no diretório que contém os arquivos pkg-* .

Aqui está uma lista de nomes de variáveis e seus valores padrão. (O valor padrão do PKGDIR é ${MASTERDIR} .)

Variável Valor padrão

Variável	Valor padrão
`DESCR`	`${PKGDIR}/pkg-descr`
`PLIST`	`${PKGDIR}/pkg-plist`
`PKGINSTALL`	`${PKGDIR}/pkg-install`
`PKGDEINSTALL`	`${PKGDIR}/pkg-deinstall`
`PKGMESSAGE`	`${PKGDIR}/pkg-message`

DESCR

${PKGDIR}/pkg-descr

PLIST

${PKGDIR}/pkg-plist

PKGINSTALL

${PKGDIR}/pkg-install

PKGDEINSTALL

${PKGDIR}/pkg-deinstall

PKGMESSAGE

${PKGDIR}/pkg-message

9.5. Fazendo uso de `SUB_FILES` e `SUB_LIST`

O SUB_FILES e o SUB_LIST são úteis para valores dinâmicos em arquivos do port, como o PREFIX de instalação dentro do pkg-message .

A SUB_FILES especifica uma lista de arquivos a serem modificados automaticamente. Cada arquivo na lista SUB_FILES deve ter um arquivo.in correspondente presente no FILESDIR . Uma versão modificada será criada como ${WRKDIR}/arquivo . Os arquivos definidos como um valor de USE_RC_SUBR são automaticamente adicionados ao SUB_FILES . Para os arquivos pkg-message , pkg-install e pkg-deinstall , a variável Makefile correspondente é automaticamente definida para apontar para a versão processada.

A SUB_LIST é uma lista de pares VAR=VALUE . Para cada par, %%VAR%% será substituído por VALUE em cada arquivo listado em SUB_FILES . Vários pares comuns são definidos automaticamente: PREFIX , LOCALBASE , DATADIR , DOCSDIR , EXEMPLESDIR , WWWDIR e ETCDIR . Qualquer linha que comece com @Comment seguido por um espaço, será excluído dos arquivos resultantes após uma substituição de variável.

Este exemplo substitui %%ARCH%% com a arquitetura do sistema em um pkg-message :

SUB_FILES=	pkg-message
SUB_LIST=	ARCH=${ARCH}

Note que para este exemplo, o pkg-message.in deve existir no FILESDIR .

Exemplo de um bom pkg-message.in :

Now it is time to configure this package.
Copy %%PREFIX%%/shared/examples/putsy/%%ARCH%%.conf into your home directory
as .putsy.conf and edit it.