Free Press

Installazione dei target¶

install(TARGETS targets... ] ] ] )

La forma TARGETS specifica le regole per l’installazione dei target da un progetto. Ci sono diversi tipi di target Output Artifactsthat che possono essere installati:

ARCHIVE

Gli artefatti target di questo tipo includono:

• Biblioteche statiche (eccetto su macOS quando marcate come FRAMEWORK, vedi sotto);

• Biblioteche di importazioneDLL (su tutti i sistemi basati su Windows incluso Cygwin; hanno estensione.lib, in contrasto con le librerie .dll che vanno in RUNTIME);

• Su AIX, il file di importazione del linker creato per gli eseguibili conENABLE_EXPORTS attivato.

LIBRARY

Gli artefatti target di questo tipo includono:

• Biblioteche condivise, eccetto

  • DLLs (queste vanno in RUNTIME, vedi sotto),

  • su macOS quando marcate come FRAMEWORK (vedi sotto).

RUNTIME

Gli artefatti target di questo tipo includono:

• Eseguibili (eccetto su macOS quando contrassegnati come MACOSX_BUNDLE, vedi BUNDLE sotto);

• DLLs (su tutti i sistemi basati su Windows incluso Cygwin; nota che le librerie di importazione che le accompagnano sono del tipo ARCHIVE).

OBJECTS

File oggetto associati alle librerie oggetto.

FRAMEWORK

Sia le librerie statiche che quelle condivise contrassegnate dalla proprietà FRAMEWORK sono trattate come obiettivi FRAMEWORK su macOS.

BUNDLE

Gli eseguibili marcati con la proprietà MACOSX_BUNDLE sono trattati come obiettivi BUNDLE su macOS.

PUBLIC_HEADER

Qualsiasi file PUBLIC_HEADER associato a una libreria è installato nella destinazione specificata dall’argomento PUBLIC_HEADER su piattaforme non-Apple. Le regole definite da questo argomento sono ignorate per le FRAMEWORKlibrerie su piattaforme Apple perché i file associati sono installati nelle posizioni appropriate all’interno della cartella del framework. VediPUBLIC_HEADER per i dettagli.

PRIVATE_HEADER

Simile a PUBLIC_HEADER, ma per i file PRIVATE_HEADER. VediPRIVATE_HEADER per i dettagli.

RESOURCE

Simile a PUBLIC_HEADER e PRIVATE_HEADER, ma per i file RESOURCE. Vedere RESOURCE per i dettagli.

Per ognuno di questi argomenti dati, gli argomenti che li seguono si applicano solo all’obiettivo o al tipo di file specificato nell’argomento. Se non ne viene dato nessuno, le proprietà di installazione si applicano a tutti i tipi di destinazione. Se ne viene dato solo uno, allora saranno installati solo i target di quel tipo (che può essere usato per installare solo una DLL o solo una libreria di importazione.)

Per i normali eseguibili, le librerie statiche e le librerie condivise, l’argomentoDESTINATION non è richiesto. Per questi tipi di destinazione, quandoDESTINATION è omesso, una destinazione predefinita sarà presa dalla variabile appropriata da GNUInstallDirs, o impostata su un valore predefinito se tale variabile non è definita. Lo stesso vale per le intestazioni pubbliche e private associate ai target installati attraverso le proprietàPUBLIC_HEADER e PRIVATE_HEADER target.Una destinazione deve sempre essere fornita per le librerie di moduli, i bundle Apple e i framework. Una destinazione può essere omessa per le librerie di interfacce e di oggetti, ma sono gestite diversamente (vedere la discussione di questo argomento verso la fine di questa sezione).

La seguente tabella mostra i tipi di destinazione con le loro variabili associate e le impostazioni predefinite che si applicano quando non viene data alcuna destinazione:

I progetti che desiderano seguire la pratica comune di installare le intestazioni in una sottodirectory specifica per il progettospecifico del progetto, dovranno fornire una destinazione piuttosto che affidarsi a quanto sopra.

Per rendere i pacchetti compatibili con le politiche di layout del filesystem della distribuzione, se i progetti devono specificare un DESTINATION, si raccomanda di usare un percorso che inizi con la variabile GNUInstallDirs appropriata. Il seguente esempio mostra una libreria statica installata nella destinazione predefinita fornita daGNUInstallDirs, ma con i suoi header installati in una sottodirectory specifica del progetto che segue la raccomandazione di cui sopra:

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)

In aggiunta alle opzioni comuni elencate sopra, ogni destinazione può accettare i seguenti argomenti aggiuntivi:

NAMELINK_COMPONENT

Su alcune piattaforme una libreria condivisa versionata ha un collegamento simbolico come:

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

dove lib<name>.so.1 è il nome della libreria e lib<name>.soè un “namelink” che permette ai linker di trovare la libreria quando viene data-l<name>. L’opzione NAMELINK_COMPONENT è simile all’opzioneCOMPONENT, ma cambia il componente di installazione di un namelink di una libreria condivisa, se ne viene generato uno. Se non è specificata, ha come valore predefinito quello di COMPONENT. È un errore usare questo parametro al di fuori di un bloccoLIBRARY.

Considerate il seguente esempio:

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

In questo scenario, se scegliete di installare solo il componente Development, sia gli header che il namelink saranno installati senza la libreria. (Se non installate anche il componente Libraries, il namelink sarà un link simbolico non funzionante, e i progetti che si collegano alla libreria avranno errori di compilazione). Se si installa solo il componente Libraries, verrà installata solo la libreria, senza gli header e namelink.

Questa opzione è tipicamente usata per i gestori di pacchetti che hanno pacchetti di sviluppo e di runtime separati. Per esempio, sui sistemi Debian, ci si aspetta che la libreria sia nel pacchetto di runtime, e che gli header e il namelink siano nel pacchetto di sviluppo.

Vedi le proprietà VERSION e SOVERSION dell’obiettivo per i dettagli sulla creazione di librerie condivise versionate.

NAMELINK_ONLY

Questa opzione causa l’installazione del solo namelink quando viene installato un obiettivo di libreria. Sulle piattaforme in cui le librerie condivise versionate non hanno namelink o quando una libreria non è versionata, l’opzione NAMELINK_ONLY non installa nulla. È un errore usare questo parametro al di fuori di un bloccoLIBRARY.

Quando viene dato NAMELINK_ONLY, o NAMELINK_COMPONENT oCOMPONENT possono essere usati per specificare il componente di installazione di thenamelink, ma COMPONENT dovrebbe essere generalmente preferito.

NAMELINK_SKIP

Simile a NAMELINK_ONLY, ma ha l’effetto opposto: causa l’installazione di file di libreria diversi dal namelink quando viene installato un target di libreria. Quando non vengono dati né NAMELINK_ONLY né NAMELINK_SKIP, vengono installate entrambe le porzioni. Sulle piattaforme in cui le librerie condivise in versione non hanno symlink o quando una libreria non è in versione, NAMELINK_SKIP installa la libreria. È un errore usare questo parametro al di fuori di un bloccoLIBRARY.

Se NAMELINK_SKIP è specificato, NAMELINK_COMPONENT non ha effetto. Non è raccomandato usare NAMELINK_SKIP insieme aNAMELINK_COMPONENT.

Il comando install(TARGETS) può anche accettare le seguenti opzioni al livello superiore:

EXPORT

Questa opzione associa i file target installati con un’esportazione chiamata<export-name>. Deve apparire prima di qualsiasi opzione di destinazione. Per installare effettivamente il file di esportazione stesso, chiamare install(EXPORT), documentato di seguito.Vedere la documentazione della proprietà EXPORT_NAME target per cambiare il nome del target esportato.

INCLUDES DESTINATION

Questa opzione specifica una lista di directory che sarà aggiunta alla proprietàINTERFACE_INCLUDE_DIRECTORIES target di<targets> quando viene esportata dal comando install(EXPORT). Se viene specificato un percorso relativo, esso viene trattato come relativo a$<INSTALL_PREFIX>.

Uno o più gruppi di proprietà possono essere specificati in una singola chiamata alla forma TARGETS di questo comando. Un target può essere installato più di una volta in posizioni diverse. Considerate gli ipotetici obiettivi myExe,mySharedLib e myStaticLib. Il codice:

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

installerà myExe in <prefix>/bin e myStaticLib in<prefix>/lib/static. Sulle piattaforme non-DLL mySharedLib sarà installato su <prefix>/lib e /some/full/path. Su piattaforme DLL la DLL mySharedLib sarà installata in <prefix>/bin e/some/full/path e la sua libreria di importazione sarà installata in<prefix>/lib/static e /some/full/path.

Le librerie di interfaccia possono essere elencate tra gli obiettivi da installare.Non installano artefatti ma saranno incluse in un EXPORT associato.Se le librerie di oggetti sono elencate ma non viene data alcuna destinazione per i file dell’oggetto, saranno esportate come librerie di interfaccia.Questo è sufficiente a soddisfare i requisiti d’uso transitivi di altri target che si collegano alle librerie di oggetti nella loro implementazione.

Installare un target con la proprietà EXCLUDE_FROM_ALL target impostata a TRUE ha un comportamento non definito.