Free Press

Instalowanie celówś

install(TARGETS targets... ] ] ] )

Formularz TARGETS określa zasady instalowania celów z projektu. Istnieje kilka rodzajów docelowych artefaktów wyjściowych, które mogą zostać zainstalowane:

ARCHIVE

Do artefaktów docelowych tego rodzaju należą:

• Biblioteki statyczne(z wyjątkiem systemu macOS, gdy są oznaczone jako FRAMEWORK, patrz niżej);

• Biblioteki importuDLL(na wszystkich systemach opartych na Windows, w tym Cygwin; mają rozszerzenie.lib, w przeciwieństwie do bibliotek .dll, które trafiają do RUNTIME);

• Na systemie AIX, plik importu linkera tworzony dla plików wykonywalnych z włączoną opcjąENABLE_EXPORTS.

LIBRARY

Target artefakty tego rodzaju obejmują:

• Biblioteki współdzielone, z wyjątkiem

  • DLLs (te trafiają do RUNTIME, zobacz poniżej),

  • na macOS, gdy są oznaczone jako FRAMEWORK (zobacz poniżej).

RUNTIME

Docelowe artefakty tego rodzaju obejmują:

• Executables (z wyjątkiem systemu macOS, gdy są oznaczone jako MACOSX_BUNDLE, patrz BUNDLE poniżej);

• DLLs (na wszystkich systemach opartych na Windows, w tym Cygwin; zauważ, że towarzyszące im biblioteki importowe są z rodzaju ARCHIVE).

OBJECTS

Pliki obiektów powiązane z bibliotekami obiektów.

FRAMEWORK

Bywa statyczne i współdzielone biblioteki oznaczone właściwością FRAMEWORK są traktowane jako FRAMEWORK cele w systemie macOS.

BUNDLE

Biblioteki wykonawcze oznaczone właściwością MACOSX_BUNDLE są traktowane jako celeBUNDLE w systemie macOS.

PUBLIC_HEADER

Dowolne PUBLIC_HEADER pliki związane z biblioteką są instalowane w miejscu docelowym określonym przez argument PUBLIC_HEADER na platformach innych niż Apple. Reguły zdefiniowane przez ten argument są ignorowane dla FRAMEWORKbibliotek na platformach Apple, ponieważ powiązane z nimi pliki są instalowane w odpowiednich lokalizacjach wewnątrz folderu frameworka. ZobaczPUBLIC_HEADER po szczegóły.

PRIVATE_HEADER

Podobne do PUBLIC_HEADER, ale dla plików PRIVATE_HEADER. ZobaczPRIVATE_HEADER po szczegóły.

RESOURCE

Podobne do PUBLIC_HEADER i PRIVATE_HEADER, ale dlaRESOURCE plików. Zobacz RESOURCE po szczegóły.

Dla każdego z tych podanych argumentów argumenty następujące po nich odnoszą się tylko do celu lub typu pliku określonego w argumencie. Jeśli nie podano żadnego, właściwości instalacyjne dotyczą wszystkich typów docelowych. Jeśli podano tylko jeden, to zainstalowane zostaną tylko cele tego typu (co może być użyte do zainstalowania tylko biblioteki DLL lub tylko biblioteki importu.)

Dla zwykłych plików wykonywalnych, bibliotek statycznych i współdzielonych, argumentDESTINATION nie jest wymagany. Dla tych typów celów, gdyDESTINATION jest pominięte, domyślne miejsce docelowe zostanie pobrane z odpowiedniej zmiennej z GNUInstallDirs, lub ustawione na wartość domyślną wbudowaną, jeśli ta zmienna nie jest zdefiniowana. To samo dotyczy publicznych i prywatnych nagłówków związanych z zainstalowanymi celami poprzez właściwościPUBLIC_HEADER i PRIVATE_HEADER target.Miejsce docelowe musi być zawsze podane dla bibliotek modułowych, Apple bundles iframeworks. Miejsce docelowe może być pominięte dla bibliotek interfejsowych i obiektowych, ale są one traktowane inaczej (zobacz dyskusję na ten temat pod koniec tego rozdziału).

Poniższa tabela pokazuje typy docelowe z przypisanymi do nich zmiennymi i wbudowanymi domyślnymi, które mają zastosowanie, gdy nie podano miejsca docelowego:

Projekty, które chcą podążać za powszechną praktyką instalowania nagłówków w podkatalogu aproject- specificbędą musiały podać miejsce docelowe, zamiast polegać na powyższym.

Aby uczynić pakiety zgodnymi z zasadami rozmieszczenia systemu plików w dystrybucji, jeśli projekty muszą określić DESTINATION, zalecane jest użycie ścieżki, która zaczyna się od odpowiedniej zmiennej GNUInstallDirs. Poniższy przykład pokazuje statyczną bibliotekę zainstalowaną w domyślnym miejscu docelowym, ale z nagłówkami zainstalowanymi w podkatalogu specyficznym dla projektu, który jest zgodny z powyższymi zaleceniami:

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)

W dodatku do wspólnych opcji wymienionych powyżej, każdy cel może zaakceptować następujące dodatkowe argumenty:

NAMELINK_COMPONENT

Na niektórych platformach wersjonowana biblioteka współdzielona ma dowiązanie symboliczne, takie jak:

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

gdzie lib<name>.so.1 jest nazwą synonimiczną biblioteki, a lib<name>.so jest „namelinkiem” umożliwiającym linkerom znalezienie biblioteki, gdy podano-l<name>. Opcja NAMELINK_COMPONENT jest podobna do opcjiCOMPONENT, ale zmienia składnik instalacyjny namelink biblioteki współdzielonej, jeśli taki zostanie wygenerowany. Jeśli nie zostanie podana, domyślnie przyjmuje wartość COMPONENT. Błędem jest używanie tego parametru poza blokiemLIBRARY.

Rozważmy następujący przykład:

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

W tym scenariuszu, jeśli wybierzesz instalację tylko Developmentkomponentu, zarówno nagłówki jak i namelink zostaną zainstalowane bez biblioteki. (Jeśli nie zainstalujesz również komponentu Libraries, to namelink będzie nieobsługiwanym łączem symlinkowym, a projekty łączące się z biblioteką będą miały błędy kompilacji). Jeśli zainstalujesz tylko komponent Libraries, zostanie zainstalowana tylko biblioteka, bez nagłówków i namelink.

Ta opcja jest zwykle używana w menedżerach pakietów, które mają oddzielne pakiety czasowe i rozwojowe. Na przykład, w systemach Debian, biblioteka powinna być w pakiecie runtime, a nagłówki inamelink powinny być w pakiecie developerskim.

Zobacz VERSION i SOVERSION właściwości celu, aby uzyskać szczegóły na temat tworzenia wersjonowanych bibliotek współdzielonych.

NAMELINK_ONLY

Ta opcja powoduje instalację tylko namelink, gdy instalowany jest librarytarget. Na platformach, gdzie wersjonowane biblioteki współdzielone nie mają namelinków lub gdy biblioteka nie jest wersjonowana, opcja NAMELINK_ONLY nie instaluje niczego. Błędem jest użycie tego parametru poza blokiemLIBRARY.

Gdy podano NAMELINK_ONLY, można użyć albo NAMELINK_COMPONENT alboCOMPONENT do określenia składnika instalacyjnego thenamelink, ale COMPONENT powinno być ogólnie preferowane.

NAMELINK_SKIP

Podobna do NAMELINK_ONLY, ale ma odwrotny skutek: powoduje instalację plików biblioteki innych niż namelink, gdy jest instalowana biblioteka docelowa. Gdy nie podano ani NAMELINK_ONLY ani NAMELINK_SKIP, instalowane są obie części. Na platformach, gdzie wersjonowane biblioteki współdzielone nie mają dowiązań symlinkowych lub gdy biblioteka nie jest wersjonowana, NAMELINK_SKIP instaluje bibliotekę. Błędem jest użycie tego parametru poza blokiemLIBRARY.

Jeśli podano NAMELINK_SKIP, NAMELINK_COMPONENT nie ma żadnego efektu. Nie zaleca się używania NAMELINK_SKIP w połączeniu zNAMELINK_COMPONENT.

Polecenie install(TARGETS) może również przyjmować następujące opcje na poziomie top:

EXPORT

Ta opcja kojarzy zainstalowane pliki docelowe z eksportem o nazwie<export-name>. Musi się ona pojawić przed wszystkimi opcjami celu. Aby faktycznie zainstalować sam plik eksportu, wywołaj polecenie install(EXPORT), udokumentowane poniżej.Zobacz dokumentację właściwości target EXPORT_NAME, aby zmienić nazwę eksportowanego celu.

INCLUDES DESTINATION

Opcja ta określa listę katalogów, które zostaną dodane do właściwości targetINTERFACE_INCLUDE_DIRECTORIES pliku<targets>, gdy zostanie on wyeksportowany poleceniem install(EXPORT). Jeśli podano ścieżkę względną, jest ona traktowana jako względna w stosunku do$<INSTALL_PREFIX>.

Jedna lub więcej grup właściwości może być określona w pojedynczym wywołaniu formy TARGETS tego polecenia. Cel może być zainstalowany więcej niż jeden raz w różnych miejscach. Rozważmy hipotetyczne cele myExe, mySharedLib i myStaticLib. Kod:

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

zainstaluje myExe na <prefix>/bin i myStaticLib na<prefix>/lib/static. Na platformach bez bibliotek DLL plik mySharedLib zostanie zainstalowany do <prefix>/lib i /some/full/path. Na platformach DLL mySharedLib DLL zostanie zainstalowana do <prefix>/bin i/some/full/path, a jej biblioteka importowa zostanie zainstalowana do<prefix>/lib/static i /some/full/path.

Biblioteki interfejsów mogą być wymienione wśród celów do zainstalowania.Instalują one żadnych artefaktów, ale będą zawarte w powiązanym EXPORT.Jeśli biblioteki obiektów są wymienione, ale nie podano miejsca docelowego dla plików obiektów, zostaną one wyeksportowane jako biblioteki interfejsów.Jest to wystarczające, aby spełnić wymagania użytkowania przechodniego innych celów, które łączą się z bibliotekami obiektów w swojej implementacji.

Instalowanie celu z właściwością EXCLUDE_FROM_ALL target ustawioną na TRUE ma niezdefiniowane zachowanie.