Free Press

Installation des cibles¶

install(TARGETS targets... ] ] ] )

Le formulaire TARGETS spécifie les règles d’installation des cibles d’un projet. Il existe plusieurs types d’artefacts de sortie de cible qui peuvent être installés :

ARCHIVE

Les artefacts de cible de ce type comprennent :

• Les bibliothèques statiques(sauf sur macOS lorsqu’elles sont marquées comme FRAMEWORK, voir ci-dessous);

• Les bibliothèques d’importation de DLL(sur tous les systèmes basés sur Windows, y compris Cygwin ; elles ont l’extension.lib, contrairement aux bibliothèques .dll qui vont dans RUNTIME);

• Sur AIX, le fichier d’importation de l’éditeur de liens créé pour les exécutables avecENABLE_EXPORTS activé.

LIBRARY

Les artefacts cibles de ce type comprennent :

• Les bibliothèques partagées, sauf

  • les DLL (celles-ci vont dans RUNTIME, voir ci-dessous),

  • sur macOS lorsqu’elles sont marquées comme FRAMEWORK (voir ci-dessous).

RUNTIME

Les artefacts cibles de ce type incluent :

• Exécutables (sauf sur macOS lorsqu’ils sont marqués comme MACOSX_BUNDLE, voir BUNDLE ci-dessous) ;

• DLL (sur tous les systèmes basés sur Windows, y compris Cygwin ; notez que les bibliothèques d’importation accompagnantes sont du type ARCHIVE).

OBJECTS

Fichiers objets associés aux bibliothèques d’objets.

FRAMEWORK

Les bibliothèques statiques et partagées marquées par la propriété FRAMEWORK sont traitées comme des cibles FRAMEWORK sur macOS.

BUNDLE

Les exécutables marqués avec la propriété MACOSX_BUNDLE sont traités comme des ciblesBUNDLE sur macOS.

PUBLIC_HEADER

Tous les fichiers PUBLIC_HEADER associés à une bibliothèque sont installés dans la destination spécifiée par l’argument PUBLIC_HEADER sur les plates-formes non-Apple. Les règles définies par cet argument sont ignorées pour les FRAMEWORKlibrairies sur les plates-formes Apple car les fichiers associés sont installés dans les emplacements appropriés à l’intérieur du dossier du framework. VoirPUBLIC_HEADER pour plus de détails.

PRIVATE_HEADER

Similaire à PUBLIC_HEADER, mais pour les fichiers PRIVATE_HEADER. VoirPRIVATE_HEADER pour les détails.

RESOURCE

Similaire à PUBLIC_HEADER et PRIVATE_HEADER, mais pour les fichiersRESOURCE. Voir RESOURCE pour les détails.

Pour chacun de ces arguments donnés, les arguments qui les suivent ne s’appliquent qu’à la cible ou au type de fichier spécifié dans l’argument. Si aucun n’est donné, les propriétés d’installation s’appliquent à tous les types de cible. Si un seul est donné, alors seules les cibles de ce type seront installées (ce qui peut être utilisé pour installerjuste une DLL ou juste une bibliothèque d’importation.)

Pour les exécutables réguliers, les bibliothèques statiques et les bibliothèques partagées, l’argumentDESTINATION n’est pas nécessaire. Pour ces types de cibles, lorsqueDESTINATION est omis, une destination par défaut sera prise dans la variable appropriée de GNUInstallDirs, ou fixée à une valeur par défaut intégrée si cette variable n’est pas définie. Il en va de même pour les en-têtes publics et privés associés aux cibles installées à travers les propriétésPUBLIC_HEADER et PRIVATE_HEADER de la cible.Une destination doit toujours être fournie pour les bibliothèques de modules, les bundles Apple et lesframeworks. Une destination peut être omise pour les bibliothèques d’interfaces et d’objets,mais elles sont traitées différemment (voir la discussion de ce sujet vers la fin de cette section).

Le tableau suivant montre les types de cibles avec leurs variables associées et les valeurs par défaut intégrées qui s’appliquent lorsqu’aucune destination n’est donnée :

Les projets souhaitant suivre la pratique courante d’installation des en-têtes dans un sous-répertoire spécifique à un projet devront avoir recours à des outils de gestion de projet.specific subdirectory devront fournir une destination plutôt que de se contenter de ce qui précède.

Pour que les paquets soient conformes aux politiques de disposition des systèmes de fichiers des distributions, si lesprojets doivent spécifier un DESTINATION, il est recommandé d’utiliser un apath qui commence par la variable GNUInstallDirs appropriée.Cela permet aux mainteneurs de paquets de contrôler la destination de l’installation en définissant les variables de cache appropriées. L’exemple suivant montre une bibliothèque statique installée dans la destination par défaut fournie parGNUInstallDirs, mais avec ses en-têtes installés dans un sous-répertoire spécifique au projet qui suit la recommandation ci-dessus:

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)

En plus des options communes listées ci-dessus, chaque cible peut accepter les arguments supplémentaires suivants:

NAMELINK_COMPONENT

Sur certaines plates-formes, une bibliothèque partagée versionnée possède un lien symbolique tel que:

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

où lib<name>.so.1 est le soname de la bibliothèque et lib<name>.soest un « namelink » permettant aux linkers de trouver la bibliothèque lorsqu’il est donné-l<name>. L’option NAMELINK_COMPONENT est similaire à l’optionCOMPONENT, mais elle change le composant d’installation d’un namelink de bibliothèque partagée si un est généré. Si elle n’est pas spécifiée, elle prend par défaut la valeur de COMPONENT. C’est une erreur d’utiliser ce paramètre en dehors d’un blocLIBRARY.

Considérez l’exemple suivant :

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

Dans ce scénario, si vous choisissez d’installer uniquement le composant Development, les en-têtes et le namelink seront installés sans la bibliothèque. (Si vous n’installez pas également le composant Libraries, alors le namelink sera un lien symbolique suspendu, et les projets qui se lient à la bibliothèque auront des erreurs de construction). Si vous n’installez que le composant Libraries,seule la bibliothèque sera installée, sans les en-têtes et le namelink.

Cette option est typiquement utilisée pour les gestionnaires de paquets qui ont des paquets séparésuntime et développement. Par exemple, sur les systèmes Debian, la bibliothèque est censée être dans le paquet d’exécution, et les en-têtes et le namelink sont censés être dans le paquet de développement.

Voir les propriétés de cible VERSION et SOVERSION pour des détails sur la création de bibliothèques partagées versionnées.

NAMELINK_ONLY

Cette option provoque l’installation du namelink uniquement lorsqu’une cible de bibliothèque est installée. Sur les plates-formes où les bibliothèques partagées versionnées n’ont pas de namelinks ou lorsqu’une bibliothèque n’est pas versionnée, l’option NAMELINK_ONLYn’installe rien. C’est une erreur d’utiliser ce paramètre en dehors d’un blocLIBRARY.

Lorsque NAMELINK_ONLY est donné, NAMELINK_COMPONENT ouCOMPONENT peuvent être utilisés pour spécifier le composant d’installation de thenamelink, mais COMPONENT devrait généralement être préféré.

NAMELINK_SKIP

Similaire à NAMELINK_ONLY, mais il a l’effet inverse : il provoque l’installation de fichiers de bibliothèque autres que le namelink lorsqu’une bibliothèque cible est installée. Lorsque ni NAMELINK_ONLY ni NAMELINK_SKIP ne sont donnés, les deux parties sont installées. Sur les plateformes où les bibliothèques partagées versionnées n’ont pas de liens symboliques ou lorsqu’une bibliothèque n’est pas versionnée, NAMELINK_SKIPinstalle la bibliothèque. C’est une erreur d’utiliser ce paramètre en dehors d’un blocLIBRARY.

Si NAMELINK_SKIPest spécifié, NAMELINK_COMPONENTn’a aucun effet. Il n’est pas recommandé d’utiliser NAMELINK_SKIP en conjonction avecNAMELINK_COMPONENT.

La commande install(TARGETS) peut également accepter les options suivantes au niveau supérieur :

EXPORT

Cette option associe les fichiers cibles installés à une exportation appelée<export-name>. Elle doit apparaître avant toute option de cible. Pour installer réellement le fichier d’exportation lui-même, appelez install(EXPORT), documenté ci-dessous.Voir la documentation de la propriété EXPORT_NAME target pour changer le nom de la cible exportée.

INCLUDES DESTINATION

Cette option spécifie une liste de répertoires qui seront ajoutés à la propriétéINTERFACE_INCLUDE_DIRECTORIES target de la<targets> lorsqu’elle sera exportée par la commande install(EXPORT). Si un chemin latif est spécifié, il est traité comme relatif à la$<INSTALL_PREFIX>.

Un ou plusieurs groupes de propriétés peuvent être spécifiés dans un seul appel à la forme TARGETS de cette commande. Une cible peut être installée plus d’une fois à différents endroits. Considérons les cibles hypothétiques myExe,mySharedLib, et myStaticLib. Le code:

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

installera myExe à <prefix>/bin et myStaticLib à<prefix>/lib/static. Sur les plates-formes non-DLL, mySharedLib sera installé sur <prefix>/lib et /some/full/path. Sur les plates-formes DLL, la DLL mySharedLib sera installée sur <prefix>/bin et/some/full/path et sa bibliothèque d’importation sera installée sur<prefix>/lib/static et /some/full/path.

Les bibliothèques d’interface peuvent être listées parmi les cibles à installer.Elles n’installent aucun artefact mais seront incluses dans une EXPORT associée.Si les bibliothèques d’objets sont listées mais qu’aucune destination n’est donnée pour les fichiers d’objets, elles seront exportées en tant que bibliothèques d’interface.Ceci est suffisant pour satisfaire les exigences d’utilisation transitive des autres cibles qui se lient aux bibliothèques d’objets dans leur implémentation.

L’installation d’une cible avec la propriété EXCLUDE_FROM_ALL target réglée sur TRUE a un comportement non défini.