Free Press

Instalación de objetivos¶

install(TARGETS targets... ] ] ] )

El formulario TARGETS especifica las reglas para instalar objetivos de un proyecto. Hay varios tipos de artefactos de salida de destino que pueden ser instalados:

ARCHIVE

Los artefactos de destino de este tipo incluyen:

• Librerías estáticas(excepto en macOS cuando se marcan como FRAMEWORK, ver más abajo);

• Librerías de importación DLL(en todos los sistemas basados en Windows, incluyendo Cygwin; tienen extensión.lib, en contraste con las bibliotecas .dll que van a RUNTIME);

• En AIX, el archivo de importación del enlazador creado para los ejecutables conENABLE_EXPORTS activado.

LIBRARY

Los artefactos de destino de este tipo incluyen:

• Librerías compartidas, excepto

  • DLLs (éstas van a RUNTIME, ver abajo),

  • en macOS cuando se marcan como FRAMEWORK (ver abajo).

RUNTIME

Los artefactos objetivo de este tipo incluyen:

• Ejecutables (excepto en macOS cuando se marcan como MACOSX_BUNDLE, véase BUNDLE más abajo);

• DLLs (en todos los sistemas basados en Windows, incluido Cygwin; tenga en cuenta que las bibliotecas de importación que las acompañan son del tipo ARCHIVE).

OBJECTS

Ficheros de objetos asociados a bibliotecas de objetos.

FRAMEWORK

Tanto las bibliotecas estáticas como las compartidas marcadas con la propiedad FRAMEWORKse tratan como objetivos FRAMEWORKen macOS.

BUNDLE

Los ejecutables marcados con la propiedad MACOSX_BUNDLE se tratan como objetivos BUNDLE en macOS.

PUBLIC_HEADER

Todos los archivos PUBLIC_HEADER asociados a una biblioteca se instalan en el destino especificado por el argumento PUBLIC_HEADER en plataformas que no son de Apple. Las reglas definidas por este argumento se ignoran para las bibliotecas en plataformas Apple porque los archivos asociados se instalan en las ubicaciones apropiadas dentro de la carpeta del framework. VerPUBLIC_HEADER para más detalles.

PRIVATE_HEADER

Similar a PUBLIC_HEADER, pero para archivos PRIVATE_HEADER. VerPRIVATE_HEADER para más detalles.

RESOURCE

Similar a PUBLIC_HEADER y PRIVATE_HEADER, pero paraRESOURCE archivos. Ver RESOURCE para más detalles.

Para cada uno de estos argumentos dados, los argumentos que les siguen sólo se aplican al objetivo o tipo de archivo especificado en el argumento. Si no se da ninguno, las propiedades de instalación se aplican a todos los tipos de destino. Si sólo se da uno, sólo se instalarán los objetivos de ese tipo (que se puede utilizar para instalar sólo una DLL o sólo una biblioteca de importación.)

Para los ejecutables normales, las bibliotecas estáticas y las bibliotecas compartidas, el argumentoDESTINATION no es necesario. Para estos tipos de destino, cuandoDESTINATION se omite, se tomará un destino por defecto de la variable apropiada de GNUInstallDirs, o se establecerá un valor por defecto incorporado si esa variable no está definida. Lo mismo ocurre con las cabeceras públicas y privadas asociadas a los objetivos instalados a través de las propiedades de destinoPUBLIC_HEADER y PRIVATE_HEADER. Se puede omitir un destino para las bibliotecas de interfaz y de objetos, pero se manejan de manera diferente (ver la discusión de este tema hacia el final de esta sección).

La siguiente tabla muestra los tipos de destino con sus variables asociadas y los valores predeterminados incorporados que se aplican cuando no se da ningún destino:

Los proyectos que deseen seguir la práctica común de instalar las cabeceras en un subdirectorio específico del proyectosubdirectorio específico tendrán que proporcionar un destino en lugar de basarse en lo anterior.

Para que los paquetes cumplan con las políticas de distribución del sistema de archivos, si los proyectos deben especificar un DESTINATION, se recomienda que utilicen una ruta que comience con la variable GNUInstallDirs apropiada. El siguiente ejemplo muestra una biblioteca estática que se instala en el destino predeterminado proporcionado por GNUInstallDirs, pero con sus cabeceras instaladas en un subdirectorio específico del proyecto que sigue la recomendación anterior:

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)

Además de las opciones comunes enumeradas anteriormente, cada objetivo puede aceptar los siguientes argumentos adicionales:

NAMELINK_COMPONENT

En algunas plataformas una biblioteca compartida versionada tiene un enlace simbólico como:

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

donde lib<name>.so.1 es el nombre de la biblioteca y lib<name>.so es un «namelink» que permite a los enlazadores encontrar la biblioteca cuando se les da-l<name>. La opción NAMELINK_COMPONENT es similar a la opciónCOMPONENT, pero cambia el componente de instalación de un namelink de biblioteca compartida si se genera uno. Si no se especifica, el valor por defecto es el de COMPONENT. Es un error utilizar este parámetro fuera de un bloqueLIBRARY.

Considere el siguiente ejemplo:

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

En este escenario, si elige instalar sólo el componente Development, tanto las cabeceras como el namelink se instalarán sin la biblioteca. (Si no instala también el componente Libraries, entoncesamelink será un symlink colgante, y los proyectos que se vinculen a la biblioteca tendrán errores de compilación). Si instala sólo el componente Libraries, sólo se instalará la biblioteca, sin las cabeceras ni el namelink.

Esta opción se utiliza normalmente para los gestores de paquetes que tienen separados los paquetes de tiempo real y de desarrollo. Por ejemplo, en los sistemas Debian, se espera que la biblioteca esté en el paquete de tiempo de ejecución, y que las cabeceras y el namelink estén en el paquete de desarrollo.

Vea las propiedades de objetivo VERSION y SOVERSION para obtener detalles sobre la creación de bibliotecas compartidas versionadas.

NAMELINK_ONLY

Esta opción hace que se instale sólo el namelink cuando se instala un objetivo de biblioteca. En plataformas donde las bibliotecas compartidas versionadas no tienen namelinks o cuando una biblioteca no está versionada, la opción NAMELINK_ONLY no instala nada. Es un error utilizar este parámetro fuera de un bloqueLIBRARY.

Cuando se da NAMELINK_ONLY, se puede utilizar NAMELINK_COMPONENT oCOMPONENT para especificar el componente de instalación de thenamelink, pero generalmente se debe preferir COMPONENT.

NAMELINK_SKIP

Similar a NAMELINK_ONLY, pero tiene el efecto contrario: provoca lainstalación de archivos de biblioteca distintos del namelink cuando se instala un objetivo de biblioteca. Cuando no se da ni NAMELINK_ONLY ni NAMELINK_SKIP, se instalan ambas partes. En las plataformas donde las bibliotecas compartidas versionadas no tienen enlaces simbólicos o cuando una biblioteca no está versionada, NAMELINK_SKIP instala la biblioteca. Es un error utilizar este parámetro fuera de un bloqueLIBRARY.

Si se especifica NAMELINK_SKIP, NAMELINK_COMPONENT no tiene efecto. No se recomienda utilizar NAMELINK_SKIP junto conNAMELINK_COMPONENT.

El comando install(TARGETS) también puede aceptar las siguientes opciones en el nivel superior:

EXPORT

Esta opción asocia los archivos de destino instalados con una exportación llamada<export-name>. Debe aparecer antes de cualquier opción de destino. Para instalar realmente el archivo de exportación, llame a install(EXPORT), que se documenta más adelante.Consulte la documentación de la propiedad EXPORT_NAME target para cambiar el nombre del objetivo exportado.

INCLUDES DESTINATION

Esta opción especifica una lista de directorios que se añadirán a la propiedad INTERFACE_INCLUDE_DIRECTORIES target del<targets> cuando se exporte mediante el comando install(EXPORT). Si se especifica una ruta lativa, se trata como relativa a la $<INSTALL_PREFIX>.

Se pueden especificar uno o más grupos de propiedades en una sola llamada a la forma TARGETS de este comando. Un objetivo puede ser instalado más de una vez en diferentes lugares. Considere los objetivos hipotéticos myExe,mySharedLib y myStaticLib. El código:

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

instalará myExe en <prefix>/bin y myStaticLib en<prefix>/lib/static. En las plataformas sin DLL, mySharedLib se instalará en <prefix>/lib y /some/full/path. En plataformas DLL, la DLL mySharedLib se instalará en <prefix>/bin y /some/full/path y su biblioteca de importación se instalará en <prefix>/lib/static y /some/full/path.

Las Bibliotecas de Interfaz pueden aparecer en la lista de objetivos a instalar.No instalan artefactos pero se incluirán en un EXPORT asociado.Si las Bibliotecas de Objetos aparecen en la lista pero no se les da ningún destino para los archivos de objetos, se exportarán como Bibliotecas de Interfaz.Esto es suficiente para satisfacer los requisitos de uso transitivo de otros objetivos que enlazan con las bibliotecas de objetos en su implementación.

La instalación de un objetivo con la propiedad de objetivo EXCLUDE_FROM_ALL establecida en TRUE tiene un comportamiento indefinido.