Free Press

Installing van targets¶

install(TARGETS targets... ] ] ] )

Het TARGETS formulier specificeert regels voor het installeren van targets van een project. Er zijn verschillende soorten uitvoerartefacten van targets die kunnen worden geïnstalleerd:

ARCHIVE

Dit soort artefacten van targets zijn onder andere:

• Statische bibliotheken(behalve op macOS wanneer ze zijn gemarkeerd als FRAMEWORK, zie hieronder);

• DLL-importbibliotheken(op alle Windows-gebaseerde systemen, inclusief Cygwin; ze hebben extensie.lib, in tegenstelling tot de .dll-bibliotheken die naar RUNTIME gaan);

• Op AIX wordt het linker-importbestand gemaakt voor uitvoerbare bestanden metENABLE_EXPORTS ingeschakeld.

LIBRARY

Target artefacten van dit type zijn onder andere:

• Gedeelde bibliotheken, behalve

  • DLL’s (deze gaan naar RUNTIME, zie hieronder),

  • op macOS wanneer deze zijn gemarkeerd als FRAMEWORK (zie hieronder).

RUNTIME

Target artefacten van dit type zijn onder andere:

• Executables (behalve op macOS wanneer deze zijn gemarkeerd als MACOSX_BUNDLE, zie BUNDLE hieronder);

• DLL’s (op alle Windows-gebaseerde systemen inclusief Cygwin; merk op dat de bijbehorende importbibliotheken van het type ARCHIVE zijn).

OBJECTS

Objectbestanden die zijn gekoppeld aan objectbibliotheken.

FRAMEWORK

Zowel statische als gedeelde bibliotheken die zijn gemarkeerd met de eigenschap FRAMEWORK worden op macOS behandeld als FRAMEWORK-doelwitten.

BUNDLE

Executables gemarkeerd met de MACOSX_BUNDLE eigenschap worden behandeld alsBUNDLE targets op macOS.

PUBLIC_HEADER

Alle PUBLIC_HEADER bestanden geassocieerd met een bibliotheek worden geïnstalleerd in de bestemming gespecificeerd door het PUBLIC_HEADER argument op niet-Apple platformen. Regels gedefinieerd met dit argument worden genegeerd voor FRAMEWORKbibliotheken op Apple-platforms omdat de bijbehorende bestanden worden geïnstalleerd op de juiste locaties binnen de map Framework. ZiePUBLIC_HEADER voor details.

PRIVATE_HEADER

Zoals PUBLIC_HEADER, maar dan voor PRIVATE_HEADER bestanden. ZiePRIVATE_HEADER voor details.

RESOURCE

Gelijk aan PUBLIC_HEADER en PRIVATE_HEADER, maar voorRESOURCE bestanden. Zie RESOURCE voor details.

Voor elk van deze argumenten geldt dat de argumenten die erop volgen alleen van toepassing zijn op het doel of bestandstype dat in het argument is opgegeven. Als er geen is gegeven, gelden de installatie-eigenschappen voor alle doeltypen. Als er slechts één wordt gegeven, worden alleen targets van dat type geïnstalleerd (wat kan worden gebruikt om alleen een DLL of alleen een importbibliotheek te installeren.)

Voor gewone uitvoerbare bestanden, statische bibliotheken en gedeelde bibliotheken is hetDESTINATION argument niet nodig. WanneerDESTINATION is weggelaten, wordt voor deze doeltypen een standaard bestemming genomen uit de betreffende variabele uit GNUInstallDirs, of ingesteld op een ingebouwde standaardwaarde als die variabele niet is gedefinieerd. Hetzelfde geldt voor de publieke en private headers die geassocieerd zijn met de geïnstalleerde targets via de target eigenschappenPUBLIC_HEADER en PRIVATE_HEADER. Een bestemming moet altijd worden opgegeven voor module libraries, Apple bundles en frameworks. Een bestemming kan weggelaten worden voor interface en object bibliotheken, maar deze worden anders behandeld (zie de discussie over dit onderwerp aan het einde van deze sectie).

De volgende tabel toont de doeltypen met hun bijbehorende variabelen en ingebouwde standaardwaarden die van toepassing zijn wanneer geen bestemming is opgegeven:

Projecten die de gebruikelijke praktijk willen volgen om headers te installeren in een project-specifieke subdirectory te installeren, zullen een bestemming moeten opgeven in plaats van alleen op het bovenstaande te vertrouwen.

Om ervoor te zorgen dat pakketten voldoen aan het beleid voor de indeling van het bestandssysteem van de distributie, wordt aanbevolen dat projecten die een DESTINATION moeten opgeven, een pad gebruiken dat begint met de juiste GNUInstallDirs variabele. Dit stelt pakketbeheerders in staat om de installatiebestemming te bepalen door de juiste cache-variabelen in te stellen. Het volgende voorbeeld toont een statische bibliotheek die wordt geïnstalleerd op de standaardbestemming van GNUInstallDirs, maar met de headers geïnstalleerd in een projectspecifieke submap die de bovenstaande aanbeveling volgt:

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)

Naast de algemene opties die hierboven zijn opgesomd, kan elk doel de volgende bijkomende argumenten aanvaarden:

NAMELINK_COMPONENT

Op sommige platformen heeft een geversioneerde gedeelde bibliotheek een symbolische link zoals:

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

waar lib<name>.so.1 de sonaam van de bibliotheek is en lib<name>.so een “namelink” is die linkers in staat stelt om de bibliotheek te vinden als-l<name> wordt gegeven. De NAMELINK_COMPONENT optie is gelijkaardig aan deCOMPONENT optie, maar het verandert de installatie component van een sharedlibrary namelink als er een wordt gegenereerd. Als deze niet wordt opgegeven, wordt standaard de waarde van COMPONENT gebruikt. Het is een fout om deze parameter buiten eenLIBRARY-blok te gebruiken.

Zie het volgende voorbeeld:

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

In dit scenario, als u ervoor kiest om alleen de Development-component te installeren, zullen zowel de headers als de namelink worden geïnstalleerd zonder de bibliotheek. (Als u niet ook de Libraries component installeert, dan zal de namelink een bungelende symlink zijn, en projecten die linken naar de library zullen fouten vertonen bij het bouwen). Als u alleen de Libraries component installeert, wordt alleen de bibliotheek geïnstalleerd, zonder de headers en namelink.

Deze optie wordt typisch gebruikt voor pakketbeheerders die pakketten voor deuntime en voor ontwikkeling gescheiden hebben. Bijvoorbeeld, op Debian systemen, wordt verwacht dat de library in het runtime pakket zit, en de headers en namelink in het development pakket.

Zie de VERSION en SOVERSION target eigenschappen voor details over het maken van versioned shared libraries.

NAMELINK_ONLY

Deze optie zorgt ervoor dat alleen de namelink wordt geïnstalleerd wanneer een librarytarget wordt geïnstalleerd. Op platformen waar gedeelde bibliotheken met versiebeheer geen namelinks hebben of wanneer een bibliotheek niet met versiebeheer is uitgerust, installeert de optie NAMELINK_ONLY niets. Het is een fout om deze parameter buiten eenLIBRARY blok te gebruiken.

Wanneer NAMELINK_ONLY is gegeven, kan ofwel NAMELINK_COMPONENT of COMPONENT worden gebruikt om de installatie component van thenamelink te specificeren, maar COMPONENT zou over het algemeen de voorkeur moeten hebben.

NAMELINK_SKIP

Gelijk aan NAMELINK_ONLY, maar het heeft het tegenovergestelde effect: het veroorzaakt de installatie van bibliotheek bestanden anders dan de namelink wanneer een bibliotheek target is geïnstalleerd. Wanneer noch NAMELINK_ONLY noch NAMELINK_SKIP zijn gegeven, worden beide delen geïnstalleerd. Op platformen waar geversioneerde gedeelde bibliotheken geen symlinks hebben of wanneer een bibliotheek niet geversioneerd is, installeert NAMELINK_SKIP de bibliotheek. Het is een fout om deze parameter buiten eenLIBRARY blok te gebruiken.

Als NAMELINK_SKIP is opgegeven, heeft NAMELINK_COMPONENT geen effect. Het is niet aangeraden om NAMELINK_SKIP te gebruiken in combinatie metNAMELINK_COMPONENT.

Het install(TARGETS) commando kan ook de volgende opties aanvaarden op het top niveau:

EXPORT

Deze optie associeert de geïnstalleerde doelbestanden met een export genaamd<export-name>. Ze moet voor alle doelopties staan. Om het exportbestand zelf te installeren, roept u install(EXPORT) aan, hieronder gedocumenteerd. Zie de documentatie van de EXPORT_NAME doel eigenschap om de naam van het geëxporteerde doel te veranderen.

INCLUDES DESTINATION

Deze optie specificeert een lijst van mappen die zullen worden toegevoegd aan deINTERFACE_INCLUDE_DIRECTORIES doel eigenschap van de<targets> wanneer geëxporteerd door het install(EXPORT) commando. Als een alternatief pad wordt opgegeven, wordt het behandeld als relatief ten opzichte van de$<INSTALL_PREFIX>.

Een of meer groepen eigenschappen kunnen worden opgegeven in een enkele oproep tot de TARGETS vorm van dit commando. Een doel kan meer dan eens op verschillende plaatsen worden geïnstalleerd. Neem de hypothetische targets myExe,mySharedLib, en myStaticLib. De code:

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

zal myExe installeren naar <prefix>/bin en myStaticLib naar<prefix>/lib/static. Op niet-DLL-platforms zal mySharedLib worden geïnstalleerd op <prefix>/lib en /some/full/path. Op DLL platformen zal de mySharedLib DLL geïnstalleerd worden op <prefix>/bin en/some/full/path en de import bibliotheek zal geïnstalleerd worden op<prefix>/lib/static en /some/full/path.

Interface Bibliotheken kunnen vermeld worden onder de te installeren targets. Ze installeren geen artefacten maar zullen opgenomen worden in een geassocieerde EXPORT.Als Object Bibliotheken vermeld worden maar geen bestemming krijgen voor deirobject bestanden, dan zullen ze geëxporteerd worden als Interface Bibliotheken.Dit is voldoende om te voldoen aan de transitieve gebruiksvereisten van andere doelen die linken naar de objectbibliotheken in hun implementatie.

Installeren van een doel met de EXCLUDE_FROM_ALL doel eigenschap ingesteld op TRUE heeft ongedefinieerd gedrag.