5.16. Instalando Arquivos

Importante:

O estágio install é muito importante para o usuário final porque ele adiciona arquivos ao sistema. Todos os comandos adicionais de estágios *-install dos Makefile's de port devem ser mostrados na tela. Não silencie esses comandos com @ ou .SILENT.

5.16.1. Macros INSTALL_*

Use as macros fornecidas em bsd.port.mk para garantir a propriedade correta dos arquivos nos targets *-install do port. Defina a propriedade diretamente em pkg-plist com as entradas correspondentes, como @(owner,group,), @owner owner, e @group group. Esses operadores funcionam até serem substituídos, ou até o final do pkg-plist, lembre-se de redefini-los depois que eles não forem mais necessários. O valor de propriedade padrão é root:wheel. Veja Seção 8.6.13, “Keywords Básicas” para maiores informações.

  • INSTALL_PROGRAM é um comando para instalar executáveis ​​binários.

  • INSTALL_SCRIPT é um comando para instalar scripts executáveis.

  • INSTALL_LIB é um comando para instalar bibliotecas compartilhadas (mas não bibliotecas estáticas).

  • INSTALL_KLD é um comando para instalar módulos carregáveis ​​do kernel. Algumas arquiteturas não gostam de ter os módulos otimizados (stripped), então use este comando em vez de INSTALL_PROGRAM.

  • INSTALL_DATA é um comando para instalar dados compartilháveis, incluindo bibliotecas estáticas.

  • INSTALL_MAN é um comando para instalar manpages e outras documentações (ele não realiza nenhuma compactação).

Estas variáveis ​​parametrizam o comando install(1) com as flags apropriadas para cada situação.

Importante:

Não use INSTALL_LIB para instalar bibliotecas estáticas, porque otimiza-las (strip) torna-as sem utilidade. Use INSTALL_DATA neste caso.

5.16.2. Otimizando (Stripping) Binários e Bibliotecas Compartilhadas

Os binários instalados devem ser otimizados (stripped). Não otimize (strip) os binários manualmente, a menos que seja absolutamente necessário. A macro INSTALL_PROGRAM instala e otimiza (strip) o binário ao mesmo tempo. A macro INSTALL_LIB faz o mesmo com as bibliotecas compartilhadas.

Quando um arquivo deve ser otimizado (stripped), mas as macros INSTALL_PROGRAM e INSTALL_LIB não são desejadas, ${STRIP_CMD} otimiza (strips) o programa ou a biblioteca compartilhada. Isso geralmente é feito no target post-install. Por exemplo:

post-install:
	${STRIP_CMD} ${STAGEDIR}${PREFIX}/bin/xdl

Quando vários arquivos precisam ser otimizados (stripped):

post-install:
.for l in geometry media body track world
	${STRIP_CMD} ${STAGEDIR}${PREFIX}/lib/lib${PORTNAME}-${l}.so.0
.endfor

Use file(1) em um arquivo para determinar se ele foi otimizado (stripped). Binários são relatados por file(1) como stripped ou not stripped. Além disso,strip(1) irá detectar programas que já foram otimizados (stripped) e retornar o comando sem erros.

Importante:

Quando WITH_DEBUG estiver definido, os arquivos elf não devem ser otimizados (stripped).

As variáveis ​​(STRIP_CMD, INSTALL_PROGRAM, INSTALL_LIB, ...) e USES fornecidas pelo framework lidam com isso automaticamente.

Alguns softwares, adicionam -s em seus LDFLAGS, neste caso, ou remova o -s se WITH_DEBUG estiver definido, ou remova o incondicionalmente e use STRIP_CMD em post-install.

5.16.3. Instalando uma Árvore Inteira de Arquivos

Às vezes, um grande número de arquivos devem ser instalados preservando sua organização hierárquica. Por exemplo, copiando de uma árvore de diretórios inteira do WRKSRC para um diretório de destino sob PREFIX. Observe que PREFIX, EXEMPLESDIR, DATADIR e outras variáveis ​​de caminho sempre devem ser precedidas por STAGEDIR para respeitar o staging (ver Seção 6.1, “Staging”).

Existem duas macros para essa situação. A vantagem de usar essas macros em vez de cp é que elas garantem a propriedade e permissão adequada dos arquivos nos arquivos de destino. A primeira macro, COPYTREE_BIN, irá definir todos os arquivos instalados como sendo executáveis, sendo assim, adequado para instalações em PREFIX/bin. A segunda macro,COPYTREE_SHARE, não define permissões de execução nos arquivos e, portanto, é adequado para instalar arquivos sob o destino PREFIX/share.

post-install:
	${MKDIR} ${STAGEDIR}${EXAMPLESDIR}
	(cd ${WRKSRC}/examples && ${COPYTREE_SHARE} .${STAGEDIR}${EXAMPLESDIR})

Este exemplo irá instalar o conteúdo do diretório exemples do distfile do fornecedor para o local de exemplos apropriado do port.

post-install:
	${MKDIR} ${STAGEDIR}${DATADIR}/summer
	(cd ${WRKSRC}/temperatures && ${COPYTREE_SHARE} "June July August" ${STAGEDIR}${DATADIR}/summer)

E este exemplo irá instalar os dados dos meses de verão no subdiretório summer de um DATADIR.

Argumentos find adicionais podem ser passados através do terceiro argumento para COPYTREE_*. Por exemplo, para instalar todos os arquivos do primeiro exemplo, exceto Makefiles, é possível usar esses comandos.

post-install:
	${MKDIR} ${STAGEDIR}${EXAMPLESDIR}
	(cd ${WRKSRC}/examples && \
	${COPYTREE_SHARE} .${STAGEDIR}${EXAMPLESDIR} "! -name Makefile")

Essas macros não adicionam os arquivos instalados em pkg-plist. Eles devem ser adicionados manualmente. Para documentação opcional (PORTDOCS, veja Seção 5.16.4, “Instalar Documentação Adicional”) e exemplos (PORTEXAMPLES), os prefixos %%PORTDOCS%% ou %%PORTEXAMPLES%% devem ser prefixados no pkg-plist.

5.16.4. Instalar Documentação Adicional

Se o software tiver alguma documentação diferente do manual padrão e páginas de informações úteis para o usuário, instale-os em DOCSDIR. Isso pode ser feito como no item anterior, no target post-install.

Crie um novo diretório para o port. O nome do diretório é DOCSDIR. Isso geralmente é igual a PORTNAME. No entanto, se o usuário desejar que versões diferentes do port sejam instaladas ao mesmo tempo, PKGNAME pode ser usado.

Já que apenas os arquivos listados no pkg-plist são instalados, é seguro sempre instalar documentações no STAGEDIR (veja Seção 6.1, “Staging”). Por isso, blocos .if são necessários apenas quando os arquivos forem grandes o suficiente para causarem sobrecarga significativa de I/O.

post-install:
	${MKDIR} ${STAGEDIR}${DOCSDIR}
	${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${STAGEDIR}${DOCSDIR}

Por outro lado, se houver uma opção DOCS no port, instale a documentação em um taget post-install-DOCS-on. Esses targets são descritos em Seção 5.13.3.12, “Targets Adicionais de Compilação, target-OPT-on e target-OPT-off.

Aqui estão algumas variáveis úteis e como elas são expandidas por padrão quando usadas no Makefile:

  • DATADIR é expandido para PREFIX/share/PORTNAME.

  • DATADIR_REL é expandido para share/PORTNAME.

  • DOCSDIR é expandido para PREFIX/share/doc/PORTNAME.

  • DOCSDIR_REL é expandido para share/doc/PORTNAME.

  • EXEMPLESDIR é expandido para PREFIX/share/examples/PORTNAME.

  • EXAMPLESDIR_REL é expandido para share/examples/PORTNAME.

Nota:

A opção DOCS controla apenas a documentação adicional instalada em DOCSDIR. Não se aplica a páginas de manual e páginas de informações padrão. Arquivos instalados em EXEMPLESDIR são controlados pela opção EXEMPLES.

Essas variáveis são exportadas para PLIST_SUB. Quando possível, seus valores aparecerão como nomes de caminho relativos ao PREFIX. Isso é, por padrão share/doc/PORTNAME será substituído por %%DOCSDIR%% na lista de empacotamento e assim por diante. (Saiba mais sobre substituições pkg-plist aqui.)

Todos os arquivos e diretórios de documentação instalados condicionalmente são incluídos no pkg-plist com o prefixo %%PORTDOCS%%, por exemplo:

%%PORTDOCS%%%%DOCSDIR%%/AUTHORS
%%PORTDOCS%%%%DOCSDIR%%/CONTACT

Como uma alternativa para listar os arquivos de documentação em pkg-plist, um port pode definir a variável PORTDOCS com uma lista de nomes de arquivo e padrões shell glob para adicionar à lista de empacotamento final. Os nomes serão relativos a DOCSDIR. Portanto, um port que utiliza PORTDOCS e usa um local não padrão para sua documentação, deve definir DOCSDIR adequadamente. Se um diretório estiver listado em PORTDOCS ou ser correspondido por um padrão glob dessa variável, toda a sub árvore de arquivos e diretórios contidos serão registrados na lista final de empacotamento. Se a opção DOCS estiver desmarcada, os arquivos e diretórios listados em PORTDOCS não serão instalados ou adicionados à lista de empacotamento do port. A instalação da documentação em PORTDOCS como mostrado acima fica a cargo do port. Um exemplo típico de utilização PORTDOCS:

PORTDOCS=	README.* ChangeLog docs/*

Nota:

O equivalente de PORTDOCS para arquivos instalados em DATADIR e EXEMPLESDIR são PORTDATA e PORTEXAMPLES, respectivamente.

O conteúdo de pkg-message é exibido na instalação. Veja a seção sobre o uso do pkg-message para mais detalhes. pkg-message não precisa ser adicionado ao pkg-plist.

5.16.5. Subdiretórios Sob PREFIX

Tente deixar o port colocar os arquivos nos subdiretórios corretos de PREFIX. Alguns ports juntam tudo e colocam os arquivos em um subdiretório com o nome do port, o que é incorreto. Além disso, muitos ports colocam todos arquivos, exceto binários, arquivos header e páginas de manual, em um subdiretório de lib, o que não funciona bem com o paradigma BSD. Muitos dos arquivos devem ser movidos para um desses diretórios: etc(setup/arquivos de configuração), libexec (executáveis ​​iniciados internamente), sbin (executáveis ​​para super-usuários/gerentes), info (documentação para o navegador de informações) ou share (arquivos independentes de arquitetura). Veja hier(7) para detalhes; as regras que regem /usr praticamente se aplicam a /usr/local também. A exceção são os ports que lidam com notícias USENET. Eles podem usar PREFIX/news como um destino para seus arquivos.

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