Installing Targets¶
install(TARGETS targets... ] ] ] )
Den TARGETS formular angiver regler for installation af mål fra et projekt. Der er flere typer af mål Output artefakter, der kan installeres:
ARCHIVE
Målartefakter af denne type omfatter:
-
Statiske biblioteker(undtagen på macOS, når de er markeret som
FRAMEWORK, se nedenfor); -
DLL-importbiblioteker(på alle Windows-baserede systemer, herunder Cygwin; de har filtypenavnet
.lib, i modsætning til.dll-biblioteker, der går tilRUNTIME); -
På AIX, linkerimportfilen, der er oprettet for eksekverbare filer med
ENABLE_EXPORTSaktiveret.
LIBRARY
Målartefakter af denne type omfatter:
-
Delte biblioteker, undtagen
-
DLL’er (disse går til
RUNTIME, se nedenfor), -
på macOS, når de er markeret som
FRAMEWORK(se nedenfor).
-
RUNTIME
Målartefakter af denne type omfatter:
-
Executables(undtagen på macOS, når de er markeret som
MACOSX_BUNDLE, seBUNDLEnedenfor); -
DLL’er (på alle Windows-baserede systemer, herunder Cygwin; bemærk, at de ledsagende importbiblioteker er af typen
ARCHIVE).
OBJECTS
Nyt i version 3.9.
Objektfiler, der er tilknyttet objektbiblioteker.
FRAMEWORK
Både statiske og delte biblioteker, der er markeret med FRAMEWORKegenskaben, behandles som FRAMEWORK-mål på macOS.
BUNDLE
Eksekverbare filer markeret med MACOSX_BUNDLE-egenskaben behandles som BUNDLE-mål på macOS.
PUBLIC_HEADER
Alle PUBLIC_HEADER-filer, der er tilknyttet et bibliotek, installeres i den destination, der er angivet med PUBLIC_HEADER-argumentet på ikke-Apple-platforme. Regler, der er defineret med dette argument, ignoreres for FRAMEWORKbiblioteker på Apple-platforme, fordi de tilknyttede filer installeres på de relevante steder i rammemappen. SePUBLIC_HEADER for nærmere oplysninger.
PRIVATE_HEADER
Samme som PUBLIC_HEADER, men for PRIVATE_HEADER-filer. SePRIVATE_HEADER for yderligere oplysninger.
RESOURCE
Lignende PUBLIC_HEADER og PRIVATE_HEADER, men forRESOURCE filer. Se RESOURCE for nærmere oplysninger.
For hvert af disse angivne argumenter gælder de efterfølgende argumenter kun for det mål eller den filtype, der er angivet i argumentet. Hvis der ikke er angivet nogen, gælder installationsegenskaberne for alle måltyper. Hvis der kun er angivet et, vil kun mål af denne type blive installeret (hvilket kan bruges til at installere kun en DLL eller kun et importbibliotek.)
For almindelige eksekverbare filer, statiske biblioteker og delte biblioteker erDESTINATION-argumentet ikke påkrævet. For disse måltyper, nårDESTINATION er udeladt, vil en standarddestination blive taget fra den passende variabel fra GNUInstallDirs, eller sat til en indbygget standardværdi, hvis denne variabel ikke er defineret. Det samme gælder for depublic og private headers, der er tilknyttet de installerede mål gennemPUBLIC_HEADER og PRIVATE_HEADER målegenskaberne.Der skal altid angives en destination for modulbiblioteker, Apple bundles ogframeworks. Der kan udelades en destination for grænseflade- og objektbiblioteker, men de håndteres anderledes (se diskussionen om dette emne mod slutningen af dette afsnit).
Den følgende tabel viser måltyperne med deres tilknyttede variabler og indbyggede standardindstillinger, der gælder, når der ikke er angivet nogen destination:
|
Måltype |
GNUInstallDirs Variabel |
Built-I Standard |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Projekter, der ønsker at følge den almindelige praksis med at installere headers i en projekt-specifik undermappe, skal angive en destination i stedet for at nøjes med ovenstående.
For at gøre pakker kompatible med politikker for distributionens filsystemlayout, anbefales det, hvisprojekter skal angive en DESTINATION, at de bruger en sti, der begynder med den passende GNUInstallDirs-variabel.Dette giver pakkevedligeholdere mulighed for at kontrollere installationsdestinationen ved at indstille de passende cache-variable. Følgende eksempel viser et statisk bibliotek, der installeres til standarddestinationen, som leveres afGNUInstallDirs, men med dets headers installeret til en projektspecifik undermappe, der følger ovenstående anbefaling:
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)
Ud over de almindelige indstillinger, der er anført ovenfor, kan hvert mål acceptere følgende yderligere argumenter:
NAMELINK_COMPONENT
Nyt i version 3.12.
På nogle platforme har et versioneret delt bibliotek et symbolsk link som:
lib<name>.so -> lib<name>.so.1
hvor lib<name>.so.1 er bibliotekets sonavn og lib<name>.soer et “namelink”, der gør det muligt for linkere at finde biblioteket, når det er givet-l<name>. Indstillingen NAMELINK_COMPONENT svarer til indstillingenCOMPONENT, men den ændrer installationskomponenten i et navnelink til et sharedlibrary-bibliotek, hvis der genereres et sådant. Hvis den ikke er angivet, er standardværdien af COMPONENT. Det er en fejl at bruge denne parameter uden for enLIBRARY-blok.
Se på følgende eksempel:
install(TARGETS mylib LIBRARY COMPONENT Libraries NAMELINK_COMPONENT Development PUBLIC_HEADER COMPONENT Development )
I dette scenario, hvis du vælger kun at installere Developmentkomponenten, vil både headers og namelink blive installeret udenelibraryet. (Hvis du ikke også installerer Libraries-komponenten, vilamelink være et hængende symlelink, og projekter, der linker til biblioteket, vil få byggefejl). Hvis du kun installerer Libraries-komponenten, vil kun biblioteket blive installeret, uden headers og namelink.
Denne indstilling bruges typisk til pakkehåndtere, der har separate untime- og udviklingspakker. På Debian-systemer forventes biblioteket f.eks. at være i runtime-pakken, og headers og namelink forventes at være i udviklingspakken.
Se VERSION og SOVERSION target-egenskaberne for detaljer om oprettelse af versionerede delte biblioteker.
NAMELINK_ONLY
Denne indstilling bevirker, at kun namelinket installeres, når et librarytarget er installeret. På platforme, hvor versionerede delte biblioteker ikke har namelinks, eller når et bibliotek ikke er versioneret, installerer NAMELINK_ONLYindstillingen intet. Det er en fejl at bruge denne parameter uden for enLIBRARY blok.
Når NAMELINK_ONLY er angivet, kan enten NAMELINK_COMPONENT ellerCOMPONENT bruges til at angive installationskomponenten af den pågældendeamelink, men COMPONENT bør generelt foretrækkes.
NAMELINK_SKIP
Ligner NAMELINK_ONLY, men har den modsatte effekt: den forårsager installation af andre biblioteksfiler end namelinket, når et biblioteksmål er installeret. Når hverken NAMELINK_ONLY eller NAMELINK_SKIP er angivet, installeres begge dele. På platforme, hvor versionerede delte biblioteker ikke har symlinks, eller når et bibliotek ikke er versioneret, installerer NAMELINK_SKIP biblioteket. Det er en fejl at bruge denne parameter uden for enLIBRARY blok.
Hvis NAMELINK_SKIP er angivet, har NAMELINK_COMPONENT ingen virkning. Det anbefales ikke at bruge NAMELINK_SKIP sammen medNAMELINK_COMPONENT.
Kommandoen install(TARGETS) kan også acceptere følgende indstillinger på topniveau:
EXPORT
Denne indstilling forbinder de installerede målfiler med en eksport kaldet<export-name>. Den skal vises før alle målindstillinger. For at installere selve eksportfilen skal du kalde install(EXPORT), som er dokumenteret nedenfor.Se dokumentationen af EXPORT_NAME target-egenskaben for at ændre navnet på det eksporterede mål.
INCLUDES DESTINATION
Denne indstilling angiver en liste over mapper, som vil blive tilføjet tilINTERFACE_INCLUDE_DIRECTORIES target-egenskaben for<targets>, når den eksporteres med kommandoen install(EXPORT). Hvis der er angivet en relativ sti, behandles den som relativ til$<INSTALL_PREFIX>.
En eller flere grupper af egenskaber kan angives i et enkelt kald til TARGETS-formen af denne kommando. Et mål kan installeres mere end én gang på forskellige steder. Tag de hypotetiske mål myExe,mySharedLib og myStaticLib. Koden:
install(TARGETS myExe mySharedLib myStaticLib RUNTIME DESTINATION bin LIBRARY DESTINATION lib ARCHIVE DESTINATION lib/static)install(TARGETS mySharedLib DESTINATION /some/full/path)
vil installere myExe til <prefix>/bin og myStaticLib til<prefix>/lib/static. På ikke-DLL-platforme vil mySharedLib blive installeret til <prefix>/lib og /some/full/path. På DLL-platforme vil mySharedLib DLL’en blive installeret på <prefix>/bin og /some/full/path og dens importbibliotek vil blive installeret på <prefix>/lib/static og /some/full/path.
Interface Libraries kan være opført blandt de mål, der skal installeres.De installerer ingen artefakter, men vil blive inkluderet i en tilknyttet EXPORT.Hvis Object Libraries er opført, men der ikke er angivet nogen destination for deres objektfiler, vil de blive eksporteret som Interface Libraries.Dette er tilstrækkeligt til at opfylde kravene om transitiv brug af andre mål, der linker til objektbibliotekerne i deres implementering.
Installation af et mål med EXCLUDE_FROM_ALL target-egenskaben sat til TRUE har udefineret adfærd.
Nyt i version 3.3: En installationsdestination givet som et DESTINATION-argument kan bruge “generatorudtryk” med syntaksen $<...>. Se cmake-generator-expressions(7)manualen for tilgængelige udtryk.
Nyt i version 3.13: install(TARGETS) kan installere mål, der blev oprettet i andre mapper. Når man bruger sådanne regler for installation på tværs af mapper, vil det ikke garantere, at mål fra andre mapper er opdaterede, hvis man kørermake install (eller lignende) fra en undermappe. Du kan brugetarget_link_libraries() eller add_dependencies() til at sikre, at sådanne mål uden for mappen er bygget, før de undermappespecifikke installationsregler køres.