Free Press

Installing Targets ¶

install(TARGETS targets... ] ] ] )

O formulário TARGETS especifica regras para instalar alvos a partir de aproject. Há vários tipos de artefatos de saída de alvo que podem ser instalados:

ARCHIVE

Os artefatos de saída de alvo deste tipo incluem:

• Bibliotecas estáticas (exceto em macOS quando marcado como FRAMEWORK, veja abaixo);

• Bibliotecas de importação deDLL(em todos os sistemas baseados em Windows incluindo Cygwin; elas têm extensão.lib, em contraste com as bibliotecas .dll que vão para RUNTIME);

• >

  No AIX, o arquivo de importação de linker criado para executáveis comENABLE_EXPORTS habilitado.

LIBRARY

Artigos-alvo deste tipo incluem:

• Bibliotecas compartilhadas, exceto

  • DLLs (estas vão para RUNTIME, veja abaixo),

  • em macOS quando marcado como FRAMEWORK (veja abaixo).

RUNTIME

Os artefatos-alvo deste tipo incluem:

• Executables(except on macOS when marked as MACOSX_BUNDLE, see BUNDLE below);

• DLLs (on all Windows-based systems including Cygwin; note que as bibliotecas de importação acompanhantes são do tipo ARCHIVE).

OBJECTS

Arquivos objeto associados a bibliotecas de objetos.

FRAMEWORK

Bambas bibliotecas estáticas e compartilhadas marcadas com o FRAMEWORKpropriedade são tratadas como FRAMEWORK alvos em macOS.

BUNDLE

Os executáveis marcados com a propriedade MACOSX_BUNDLE são tratados comoBUNDLE alvos em macOS.

PUBLIC_HEADER

Any PUBLIC_HEADERficheiros associados a uma biblioteca são instalados no destino especificado pelo argumento PUBLIC_HEADER em não-Appleplatforms. As regras definidas por este argumento são ignoradas para FRAMEWORKlibraries em plataformas Apple porque os arquivos associados são instalados nos locais apropriados dentro da pasta framework. VejaPUBLIC_HEADER para detalhes.

PRIVATE_HEADER

similar a PUBLIC_HEADER, mas para arquivos PRIVATE_HEADER. VejaPRIVATE_HEADER para detalhes.

RESOURCE

Similiar a PUBLIC_HEADER e PRIVATE_HEADER, mas para RESOURCE ficheiros. Veja RESOURCE para detalhes.

Para cada um destes argumentos dados, os argumentos seguintes só se aplicam ao alvo ou ao tipo de ficheiro especificado no argumento. Se nenhum for dado, as propriedades de instalação se aplicam a todos os tipos de destino. Se apenas um for dado, apenas alvos desse tipo serão instalados (que podem ser usados para instalar apenas uma DLL ou apenas uma biblioteca de importação.)

Para executáveis regulares, bibliotecas estáticas e bibliotecas compartilhadas, o argumentoDESTINATION não é necessário. Para estes tipos de destino, quandoDESTINATION é omitido, um destino padrão será retirado da variável apropriada de GNUInstallDirs, ou definido para um valor por defeito se essa variável não estiver definida. O mesmo é válido para os cabeçalhos públicos e privados associados aos alvos instalados através das propriedadesPUBLIC_HEADER e PRIVATE_HEADER alvo. Um destino deve sempre ser fornecido para bibliotecas de módulos, pacotes Apple e frameworks. Um destino pode ser omitido para bibliotecas de interface e objetos, mas elas são tratadas de forma diferente (veja a discussão deste tópico no final desta seção).

A tabela a seguir mostra os tipos de destino com suas variáveis associadas e os padrões incorporados que se aplicam quando nenhum destino é dado:

Projectos que desejem seguir a prática comum de instalação de cabeçalhos em aproject-subdiretório específico precisará fornecer um destino em vez de apenas o acima mencionado.

Para tornar os pacotes compatíveis com as políticas de layout do sistema de arquivos da distribuição, se os projetos precisam especificar um DESTINATION, é recomendado que eles usem o apath que começa com a variável GNUInstallDirs apropriada. O exemplo a seguir mostra uma biblioteca estática sendo instalada no destino padrão fornecido porGNUInstallDirs, mas com seus cabeçalhos instalados em um subdiretório específico do projeto que segue a recomendação acima:

add_library(mylib STATIC ...)set_target_properties(mylib PROPERTIES PUBLIC_HEADER mylib.h)include(GNUInstallDirs)install(TARGETS mylib PUBLIC_HEADER DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj)

Além das opções comuns listadas acima, cada alvo pode aceitar os seguintes argumentos adicionais:

NAMELINK_COMPONENT

Em algumas plataformas uma biblioteca compartilhada versionada tem um link simbólico como:

lib<name>.so -> lib<name>.so.1

onde lib<name>.so.1 é o soname da biblioteca e lib<name>.so é um “namelink” que permite aos linkers encontrar a biblioteca quando dado-l<name>. A opção NAMELINK_COMPONENT é semelhante à opçãoCOMPONENT, mas muda o componente de instalação de um namelink de biblioteca compartilhada, se um for gerado. Se não especificado, este valor padrão é de COMPONENT. É um erro usar este parâmetro fora de um blocoLIBRARY

Considere o seguinte exemplo:

install(TARGETS mylib LIBRARY COMPONENT Libraries NAMELINK_COMPONENT Development PUBLIC_HEADER COMPONENT Development )

Neste cenário, se você optar por instalar apenas o componente Development, tanto os cabeçalhos quanto o namelink serão instalados sem a biblioteca. (Se você também não instalar o componente Libraries, então o namelink será um link simbólico pendente, e projetos que se ligam à biblioteca terão erros de compilação). Se você instalar somente o componente Libraries, somente a biblioteca será instalada, sem os cabeçalhos e namelink.

Esta opção é tipicamente usada para gerentes de pacotes que têm separateruntime e pacotes de desenvolvimento. Por exemplo, em sistemas Debian, espera-se que a biblioteca esteja no pacote runtime, e que os cabeçalhos e namelink estejam no pacote de desenvolvimento.

Veja as propriedades de destino VERSION e SOVERSION para detalhes sobre a criação de bibliotecas compartilhadas versionadas.

NAMELINK_ONLY

Esta opção causa a instalação apenas do namelink quando uma biblioteca alvo é instalada. Em plataformas onde bibliotecas compartilhadas versionadas não possuem namelinks ou quando uma biblioteca não está versionada, a opção NAMELINK_ONLYopção não instala nada. É um erro usar este parâmetro fora de umLIBRARY bloco.

Quando NAMELINK_ONLY é dado, ou NAMELINK_COMPONENT ou COMPONENT pode ser usado para especificar o componente de instalação do namelink, mas COMPONENT geralmente deve ser preferido.

NAMELINK_SKIP

Similiar a NAMELINK_ONLY, mas tem o efeito oposto: causa a instalação de arquivos de biblioteca diferentes do namelink quando uma biblioteca targetis é instalada. Quando nenhum deles NAMELINK_ONLY ou NAMELINK_SKIP é dado, ambas as porções são instaladas. Em plataformas onde bibliotecas compartilhadas com versões não possuem links simbólicos ou quando uma biblioteca não é versionada, NAMELINK_SKIPinstala a biblioteca. É um erro usar este parâmetro fora de um blocoLIBRARY

Se NAMELINK_SKIP estiver especificado, NAMELINK_COMPONENT não tem efeito. Não é recomendado usar NAMELINK_SKIP em conjunto comNAMELINK_COMPONENT.

O comando install(TARGETS) também pode aceitar as seguintes opções no nível superior:

EXPORT

Esta opção associa os arquivos de destino instalados com uma exportação chamada<export-name>. Ela deve aparecer antes de qualquer opção de destino. Para realmente instalar o arquivo de exportação em si, chame install(EXPORT), documentado abaixo. Veja a documentação da propriedade EXPORT_NAME target para alterar o nome do target exportado.

INCLUDES DESTINATION

Esta opção especifica uma lista de diretórios que serão adicionados à propriedadeINTERFACE_INCLUDE_DIRECTORIES target do comando<targets> quando exportados pelo comando install(EXPORT). Se o caminho arelativo for especificado, ele é tratado como relativo a$<INSTALL_PREFIX>.

Um ou mais grupos de propriedades podem ser especificados em uma única chamada para a forma TARGETS deste comando. Um alvo pode ser instalado mais do que uma vez em diferentes locais. Considere alvos hipotéticos myExe,mySharedLib, e myStaticLib. O código:

install(TARGETS myExe mySharedLib myStaticLib RUNTIME DESTINATION bin LIBRARY DESTINATION lib ARCHIVE DESTINATION lib/static)install(TARGETS mySharedLib DESTINATION /some/full/path)

irá instalar myExe a <prefix>/bin e myStaticLib a <prefix>/lib/static. Em plataformas não-DLL mySharedLib será instalado até <prefix>/lib e /some/full/path. Em plataformas DLL-mySharedLib DLL será instalado para <prefix>/bin e /some/full/path e sua biblioteca de importação será instalada para <prefix>/lib/static e /some/full/path.

Bibliotecas de Interface podem ser listadas entre os alvos a instalar. Elas não instalam artefatos mas serão incluídas em um associado EXPORT.Se as Bibliotecas de Objetos forem listadas mas não tiverem destino para os arquivos theirobject, elas serão exportadas como Bibliotecas de Interface.Isto é suficiente para satisfazer os requisitos de uso transitivo de outros alvos que se ligam às bibliotecas de objetos em sua implementação.

Instalando um alvo com o conjunto EXCLUDE_FROM_ALL target propertyset para TRUE tem comportamento indefinido.