Free Press

Targets installieren¶

install(TARGETS targets... ] ] ] )

Das Formular TARGETS gibt Regeln für die Installation von Targets aus einem Projekt an. Es gibt verschiedene Arten von Ziel-Ausgabe-Artefakten, die installiert werden können:

ARCHIVE

Ziel-Artefakte dieser Art sind:

• Statische Bibliotheken (außer unter macOS, wenn sie als FRAMEWORK markiert sind, siehe unten);

• DLL-Importbibliotheken (auf allen Windows-basierten Systemen, einschließlich Cygwin; sie haben die Endung.lib, im Gegensatz zu den .dll-Bibliotheken, die unter RUNTIME abgelegt werden);

• Unter AIX wird die Linker-Importdatei für ausführbare Dateien erstellt, bei denenENABLE_EXPORTS aktiviert ist.

LIBRARY

Zielartefakte dieser Art sind:

• Gemeinsame Bibliotheken, außer

  • DLLs (diese gehen nach RUNTIME, siehe unten),

  • auf macOS, wenn als FRAMEWORK markiert (siehe unten).

RUNTIME

Zielartefakte dieser Art sind:

• Ausführbare Dateien (außer unter macOS, wenn sie als MACOSX_BUNDLE markiert sind, siehe BUNDLE unten);

• DLLs (auf allen Windows-basierten Systemen, einschließlich Cygwin; beachten Sie, dass die begleitenden Importbibliotheken vom Typ ARCHIVE sind).

OBJECTS

Objektdateien, die mit Objektbibliotheken verbunden sind.

FRAMEWORK

Sowohl statische als auch gemeinsam genutzte Bibliotheken, die mit der FRAMEWORKEigenschaft gekennzeichnet sind, werden unter macOS als FRAMEWORKZiele behandelt.

BUNDLE

Ausführbare Dateien, die mit der MACOSX_BUNDLE-Eigenschaft gekennzeichnet sind, werden unter macOS als BUNDLE-Ziele behandelt.

PUBLIC_HEADER

Alle PUBLIC_HEADER-Dateien, die mit einer Bibliothek verbunden sind, werden auf Nicht-Apple-Plattformen in das durch das PUBLIC_HEADER-Argument angegebene Ziel installiert. Regeln, die durch dieses Argument definiert sind, werden für FRAMEWORKBibliotheken auf Apple-Plattformen ignoriert, da die zugehörigen Dateien an den entsprechenden Stellen innerhalb des Framework-Ordners installiert werden. SiehePUBLIC_HEADER für Details.

PRIVATE_HEADER

Ähnlich wie PUBLIC_HEADER, aber für PRIVATE_HEADER-Dateien. SiehePRIVATE_HEADER für Details.

RESOURCE

Ähnlich wie PUBLIC_HEADER und PRIVATE_HEADER, aber fürRESOURCE Dateien. Siehe RESOURCE für Details.

Für jedes dieser Argumente gelten die nachfolgenden Argumente nur für das im Argument angegebene Ziel oder den Dateityp. Wenn keines angegeben wird, gelten die Installationseigenschaften für alle Zieltypen. Wenn nur ein Argument angegeben wird, werden nur Ziele dieses Typs installiert (dies kann verwendet werden, um nur eine DLL oder nur eine Importbibliothek zu installieren)

Für reguläre ausführbare Dateien, statische Bibliotheken und gemeinsam genutzte Bibliotheken ist das ArgumentDESTINATION nicht erforderlich. Für diese Zieltypen wird, wennDESTINATION weggelassen wird, ein Standardziel aus der entsprechenden Variable aus GNUInstallDirs genommen oder auf einen eingebauten Standardwert gesetzt, wenn diese Variable nicht definiert ist. Dasselbe gilt für diepublic und private Header, die mit den installierten Zielen über diePUBLIC_HEADER und PRIVATE_HEADER Zieleigenschaften verbunden sind.Für Modulbibliotheken, Apple-Bundles undFrameworks muss immer ein Ziel angegeben werden. Ein Ziel kann für Schnittstellen- und Objektbibliotheken weggelassen werden, aber sie werden anders behandelt (siehe die Diskussion dieses Themas am Ende dieses Abschnitts).

Die folgende Tabelle zeigt die Zieltypen mit ihren zugehörigen Variablen und eingebauten Standardwerten, die gelten, wenn kein Ziel angegeben wird:

Projekte, die der üblichen Praxis folgen wollen, Header in ein projektspezifisches Unterverzeichnis zu installieren, müssenspezifischen Unterverzeichnis zu installieren, müssen ein Ziel angeben und dürfen sich nicht auf die obigen Angaben verlassen.

Wenn Projekte ein DESTINATION angeben müssen, wird empfohlen, dass sie einen Pfad verwenden, der mit der entsprechenden GNUInstallDirs-Variable beginnt, damit die Paketbetreuer das Installationsziel durch Setzen der entsprechenden Cache-Variablen kontrollieren können. Das folgende Beispiel zeigt eine statische Bibliothek, die in das von GNUInstallDirs bereitgestellte Standardziel installiert wird, deren Header jedoch in ein projektspezifisches Unterverzeichnis installiert werden, das der obigen Empfehlung folgt:

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)

Zusätzlich zu den oben aufgeführten allgemeinen Optionen kann jedes Ziel die folgenden zusätzlichen Argumente akzeptieren:

NAMELINK_COMPONENT

Auf einigen Plattformen hat eine versionierte Shared Library einen symbolischen Link wie:

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

wobei lib<name>.so.1 der Name der Bibliothek ist und lib<name>.soein „namelink“ ist, der es Linkern ermöglicht, die Bibliothek zu finden, wenn sie-l<name> angegeben wird. Die Option NAMELINK_COMPONENT ist ähnlich wie die OptionCOMPONENT, aber sie ändert die Installationskomponente eines Shared-Library-Namelinks, wenn einer erzeugt wird. Wenn sie nicht angegeben wird, ist dies der Standardwert von COMPONENT. Es ist ein Fehler, diesen Parameter außerhalb einesLIBRARY-Blocks zu verwenden.

Betrachten Sie das folgende Beispiel:

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

Wenn Sie in diesem Szenario nur die DevelopmentKomponente installieren, werden sowohl die Header als auch der Namelink ohne dieLibrary installiert. (Wenn Sie die LibrariesKomponente nicht mitinstallieren, wird Namelink ein „Dangling Symlink“ sein, und Projekte, die auf die Bibliothek verweisen, werden Build-Fehler haben). Wenn Sie nur die Libraries-Komponente installieren, wird nur die Bibliothek installiert, ohne die Header und namelink.

Diese Option wird typischerweise bei Paketmanagern verwendet, die über getrennte Laufzeit- und Entwicklungspakete verfügen. Auf Debian-Systemen wird zum Beispiel erwartet, dass sich die Bibliothek im Laufzeitpaket befindet und die Header und der Namelink im Entwicklungspaket.

Siehe die VERSION und SOVERSION Zieleigenschaften für Details zum Erstellen von versionierten Shared Libraries.

NAMELINK_ONLY

Diese Option bewirkt, dass nur der Namelink installiert wird, wenn ein Librarytarget installiert wird. Auf Plattformen, auf denen versionierte Shared Libraries keine Namelinks haben, oder wenn eine Library nicht versioniert ist, wird mit der Option NAMELINK_ONLY nichts installiert. Es ist ein Fehler, diesen Parameter außerhalb einesLIBRARY-Blocks zu verwenden.

Wenn NAMELINK_ONLY angegeben wird, kann entweder NAMELINK_COMPONENT oderCOMPONENT verwendet werden, um die Installationskomponente des Namelinks zu spezifizieren, aber COMPONENT sollte im Allgemeinen bevorzugt werden.

NAMELINK_SKIP

Ähnlich wie NAMELINK_ONLY, aber es hat den gegenteiligen Effekt: Es bewirkt die Installation von anderen Bibliotheksdateien als dem Namelink, wenn ein Bibliotheksziel installiert wird. Wenn weder NAMELINK_ONLY noch NAMELINK_SKIP angegeben werden, werden beide Teile installiert. Auf Plattformen, auf denen versionierte Shared Libraries keine Symlinks haben, oder wenn eine Library nicht versioniert ist, installiert NAMELINK_SKIP die Library. Es ist ein Fehler, diesen Parameter außerhalb einesLIBRARY-Blocks zu verwenden.

Wenn NAMELINK_SKIP angegeben wird, hat NAMELINK_COMPONENT keine Wirkung. Es wird nicht empfohlen, NAMELINK_SKIP in Verbindung mitNAMELINK_COMPONENT zu verwenden.

Der install(TARGETS)-Befehl kann auch die folgenden Optionen auf der obersten Ebene akzeptieren:

EXPORT

Diese Option verknüpft die installierten Zieldateien mit einem Export namens<export-name>. Sie muss vor allen Zieloptionen stehen. Um die Exportdatei selbst zu installieren, rufen Sie install(EXPORT) auf, das weiter unten dokumentiert ist. Siehe Dokumentation der EXPORT_NAME target-Eigenschaft, um den Namen des exportierten Ziels zu ändern.

INCLUDES DESTINATION

Diese Option gibt eine Liste von Verzeichnissen an, die derINTERFACE_INCLUDE_DIRECTORIES target-Eigenschaft von<targets> hinzugefügt werden, wenn sie durch den install(EXPORT)-Befehl exportiert werden. Wenn ein relativer Pfad angegeben wird, wird er als relativ zum$<INSTALL_PREFIX> behandelt.

Eine oder mehrere Gruppen von Eigenschaften können in einem einzigen Aufruf der TARGETS-Form dieses Befehls angegeben werden. Ein Ziel kann mehr als einmal an verschiedenen Stellen installiert werden. Betrachten Sie die hypothetischen Ziele myExe,mySharedLib und myStaticLib. Der Code:

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

installiert myExe nach <prefix>/bin und myStaticLib nach<prefix>/lib/static. Auf Nicht-DLL-Plattformen wird mySharedLib auf <prefix>/lib und /some/full/path installiert. Auf DLL-Plattformen wird die DLL mySharedLib nach <prefix>/bin und /some/full/path und ihre Importbibliothek nach <prefix>/lib/static und /some/full/path installiert.

Schnittstellenbibliotheken können unter den zu installierenden Zielen aufgelistet werden.Sie installieren keine Artefakte, werden aber in ein zugehöriges EXPORT aufgenommen.Wenn Objektbibliotheken aufgelistet sind, aber kein Ziel für die Objektdateien angegeben ist, werden sie als Schnittstellenbibliotheken exportiert.Dies ist ausreichend, um die Anforderungen der transitiven Verwendung anderer Ziele zu erfüllen, die in ihrer Implementierung auf die Objektbibliotheken verweisen.

Die Installation eines Ziels mit der EXCLUDE_FROM_ALL Zieleigenschaft TRUE hat ein undefiniertes Verhalten.