10.3 輸出目標 · cmake-cookbook

# 10.3 輸出目標 **NOTE**:*此示例代碼可以在 https://github.com/dev-cafe/cmake-cookbook/tree/v1.0/chapter-10/recipe-03 中找到，其中有一個C++示例。該示例在CMake 3.6版(或更高版本)中是有效的，并且已經在GNU/Linux、macOS和Windows上進行過測試。* 可以假設，消息庫在開源社區取得了巨大的成功。人們非常喜歡它，并在自己的項目中使用它將消息打印到屏幕上。用戶特別喜歡每個打印的消息都有惟一的標識符。但用戶也希望，當他們編譯并安裝了庫，庫就能更容易找到。這個示例將展示CMake如何讓我們導出目標，以便其他使用CMake的項目可以輕松地獲取它們。 ## 準備工作源代碼與之前的示例一致，項目結構如下: ```shell . ├── cmake │ └── messageConfig.cmake.in ├── CMakeLists.txt ├── src │ ├── CMakeLists.txt │ ├── hello- world.cpp │ ├── Message.cpp │ └── Message.hpp └── tests ├── CMakeLists.txt └── use_target ├── CMakeLists.txt └── use_message.cpp ``` 注意，cmake子目錄中添加了一個`messageConfig.cmake.in`。這個文件將包含導出的目標，還添加了一個測試來檢查項目的安裝和導出是否按預期工作。 ## 具體實施同樣，主`CMakeLists.txt`文件相對于前一個示例來說沒有變化。移動到包含我們的源代碼的子目錄`src`中： 1. 需要找到UUID庫，可以重用之前示例中的代碼： ```cmake # Search for pkg-config and UUID find_package(PkgConfig QUIET) if(PKG_CONFIG_FOUND) pkg_search_module(UUID uuid IMPORTED_TARGET) if(TARGET PkgConfig::UUID) message(STATUS "Found libuuid") set(UUID_FOUND TRUE) endif() endif() ``` 2. 接下來，設置動態庫目標并生成導出頭文件： ```cmake add_library(message-shared SHARED "") include(GenerateExportHeader) generate_export_header(message-shared BASE_NAME "message" EXPORT_MACRO_NAME "message_EXPORT" EXPORT_FILE_NAME "${CMAKE_BINARY_DIR}/${INSTALL_INCLUDEDIR}/messageExport.h" DEPRECATED_MACRO_NAME "message_DEPRECATED" NO_EXPORT_MACRO_NAME "message_NO_EXPORT" STATIC_DEFINE "message_STATIC_DEFINE" NO_DEPRECATED_MACRO_NAME "message_NO_DEPRECATED" DEFINE_NO_DEPRECATED ) target_sources(message-shared PRIVATE ${CMAKE_CURRENT_LIST_DIR}/Message.cpp ) ``` 3. 為目標設置了`PUBLIC`和`INTERFACE`編譯定義。注意`$<INSTALL_INTERFACE:...> `生成器表達式的使用： ```cmake target_compile_definitions(message-shared PUBLIC $<$<BOOL:${UUID_FOUND}>:HAVE_UUID> INTERFACE $<INSTALL_INTERFACE:USING_message> ) ``` 4. 鏈接庫和目標屬性與前一個示例一樣： ```cmake target_link_libraries(message-static PUBLIC $<$<BOOL:${UUID_FOUND}>:PkgConfig::UUID> ) set_target_properties(message-static PROPERTIES POSITION_INDEPENDENT_CODE 1 ARCHIVE_OUTPUT_NAME "message" DEBUG_POSTFIX "_sd" RELEASE_POSTFIX "_s" PUBLIC_HEADER "Message.hpp;${CMAKE_BINARY_DIR}/${INSTALL_INCLUDEDIR}/messageExport.h" ) ``` 5. 可執行文件的生成，與前一個示例中使用的命令完全相同： ```cmake add_executable(hello-world_wDSO hello-world.cpp) target_link_libraries(hello-world_wDSO PUBLIC message-shared ) # Prepare RPATH file(RELATIVE_PATH _rel ${CMAKE_INSTALL_PREFIX}/${INSTALL_BINDIR} ${CMAKE_INSTALL_PREFIX}) if(APPLE) set(_rpath "@loader_path/${_rel}") else() set(_rpath "\$ORIGIN/${_rel}") endif() file(TO_NATIVE_PATH "${_rpath}/${INSTALL_LIBDIR}" message_RPATH) set_target_properties(hello-world_wDSO PROPERTIES MACOSX_RPATH ON SKIP_BUILD_RPATH OFF BUILD_WITH_INSTALL_RPATH OFF INSTALL_RPATH "${message_RPATH}" INSTALL_RPATH_USE_LINK_PATH ON ) add_executable(hello-world_wAR hello-world.cpp) target_link_libraries(hello-world_wAR PUBLIC message-static ) ``` 現在，來看看安裝規則： 1. 因為CMake可以正確地將每個目標放在正確的地方，所以把目標的安裝規則都列在一起。這次，添加了`EXPORT`關鍵字，這樣CMake將為目標生成一個導出的目標文件： ```cmake install( TARGETS message-shared message-static hello-world_wDSO hello-world_wAR EXPORT messageTargets ARCHIVE DESTINATION ${INSTALL_LIBDIR} COMPONENT lib RUNTIME DESTINATION ${INSTALL_BINDIR} COMPONENT bin LIBRARY DESTINATION ${INSTALL_LIBDIR} COMPONENT lib PUBLIC_HEADER DESTINATION ${INSTALL_INCLUDEDIR}/message COMPONENT dev ) ``` 2. 自動生成的導出目標文件稱為` messageTargets.cmake`，需要顯式地指定它的安裝規則。這個文件的目標是`INSTALL_CMAKEDIR`，在主`CMakeLists.txt`文件中定義: ```cmake install( EXPORT messageTargets NAMESPACE "message::" DESTINATION ${INSTALL_CMAKEDIR} COMPONENT dev ) ``` 3. 最后，需要生成正確的CMake配置文件。這些將確保下游項目能夠找到消息庫導出的目標。為此，首先包括`CMakePackageConfigHelpers.cmake`標準模塊： ```cmake include(CMakePackageConfigHelpers) ``` 4. 讓CMake為我們的庫，生成一個包含版本信息的文件: ```cmake write_basic_package_version_file( ${CMAKE_CURRENT_BINARY_DIR}/messageConfigVersion.cmake VERSION ${PROJECT_VERSION} COMPATIBILITY SameMajorVersion ) ``` 5. 使用`configure_package_config_file`函數，我們生成了實際的CMake配置文件。這是基于模板`cmake/messageConfig.cmake.in`文件: ```cmake configure_package_config_file( ${PROJECT_SOURCE_DIR}/cmake/messageConfig.cmake.in ${CMAKE_CURRENT_BINARY_DIR}/messageConfig.cmake INSTALL_DESTINATION ${INSTALL_CMAKEDIR} ) ``` 6. 最后，為這兩個自動生成的配置文件設置了安裝規則: ```cmake install( FILES ${CMAKE_CURRENT_BINARY_DIR}/messageConfig.cmake ${CMAKE_CURRENT_BINARY_DIR}/messageConfigVersion.cmake DESTINATION ${INSTALL_CMAKEDIR} ) ``` `cmake/messageConfig.cmake`的內容是什么？該文件的頂部有相關的說明，可以作為用戶文檔供使用者查看。讓我們看看實際的CMake命令: 1. 占位符將使用`configure_package_config_file`命令進行替換: ```cmake @PACKAGE_INIT@ ``` 2. 包括為目標自動生成的導出文件: ```cmake include("${CMAKE_CURRENT_LIST_DIR}/messageTargets.cmake") ``` 3. 檢查靜態庫和動態庫，以及兩個“Hello, World”可執行文件是否帶有CMake提供的`check_required_components`函數： ```cmake check_required_components( "message-shared" "message-static" "message-hello-world_wDSO" "message-hello-world_wAR" ) ``` 4. 檢查目標`PkgConfig::UUID`是否存在。如果沒有，我們再次搜索UUID庫(只在非Windows操作系統下有效): ```cmake if(NOT WIN32) if(NOT TARGET PkgConfig::UUID) find_package(PkgConfig REQUIRED QUIET) pkg_search_module(UUID REQUIRED uuid IMPORTED_TARGET) endif() endif() ``` 測試一下： ```shell $ mkdir -p build $ cd build $ cmake -DCMAKE_INSTALL_PREFIX=$HOME/Software/recipe-03 .. $ cmake --build . --target install ``` 安裝樹應該如下所示： ```shell $HOME/Software/recipe-03/ ├── bin │ ├── hello-world_wAR │ └── hello-world_wDSO ├── include │ └── message │ ├── messageExport.h │ └── Message.hpp ├── lib64 │ ├── libmessage_s.a │ ├── libmessage.so -> libmessage.so.1 │ └── libmessage.so.1 └── share └── cmake └── recipe-03 ├── messageConfig.cmake ├── messageConfigVersion.cmake ├── messageTargets.cmake └── messageTargets-release.cmake ``` 出現了一個`share`子目錄，其中包含我們要求CMake自動生成的所有文件。現在開始，消息庫的用戶可以在他們自己的`CMakeLists.txt`文件中找到消息庫，只要他們設置`message_DIR `的CMake變量，指向安裝樹中的`share/cmake/message`目錄: ```cmake find_package(message 1 CONFIG REQUIRED) ``` ## 工作原理這個示例涵蓋了很多領域。對于構建系統將要執行的操作，CMake目標是一個非常有用的抽象概念。使用`PRIVATE`、`PUBLIC`和`INTERFACE`關鍵字，我們可以設置項目中的目標進行交互。在實踐中，這允許我們定義目標A的依賴關系，將如何影響目標B(依賴于A)。如果庫維護人員提供了適當的CMake配置文件，那么只需很少的CMake命令就可以輕松地解決所有依賴關系。這個問題可以通過遵循` message-static `、` message-shared `、`hello-world_wDSO`和`hello-world_wAR`目標概述的模式來解決。我們將單獨分析`message-shared`目標的CMake命令，這里只是進行一般性討論： 1. 生成目標在項目構建中列出其依賴項。對UUID庫的鏈接是 `message-shared `的`PUBLIC`需求，因為它將用于在項目中構建目標和在下游項目中構建目標。編譯時宏定義和包含目錄需要在`PUBLIC`級或`INTERFACE`級目標上進行設置。它們實際上是在項目中構建目標時所需要的，其他的只與下游項目相關。此外，其中一些只有在項目安裝之后才會相關聯。這里使用了` $<BUILD_INTERFACE:...>`和`$<INSTALL_INTERFACE:...>`生成器表達式。只有消息庫外部的下游目標才需要這些，也就是說，只有在安裝了目標之后，它們才會變得可見。我們的例子中，應用如下: * 只有在項目中使用了` message-shared`庫，那么`$<BUILD_INTERFACE:${CMAKE_BINARY_DIR}/${INSTALL_INCLUDEDIR}>`才會擴展成`${CMAKE_BINARY_DIR}/${INSTALL_INCLUDEDIR} ` * 只有在` message-shared`庫在另一個構建樹中，作為一個已導出目標，那么`$<INSTALL_INTERFACE:${INSTALL_INCLUDEDIR}> `將會擴展成`${INSTALL_INCLUDEDIR}` 2. 描述目標的安裝規則，包括生成文件的名稱。 3. 描述CMake生成的導出文件的安裝規則`messageTargets.cmake`文件將安裝到`INSTALL_CMAKEDIR`。目標導出文件的安裝規則的名稱空間選項，將把給定字符串前置到目標的名稱中，這有助于避免來自不同項目的目標之間的名稱沖突。`INSTALL_CMAKEDIR`變量是在主`CMakeLists.txt`文件中設置的: ```cmake if(WIN32 AND NOT CYGWIN) set(DEF_INSTALL_CMAKEDIR CMake) else() set(DEF_INSTALL_CMAKEDIR share/cmake/${PROJECT_NAME}) endif() set(INSTALL_CMAKEDIR ${DEF_INSTALL_CMAKEDIR} CACHE PATH "Installation directory for CMake files") ``` `CMakeLists.txt`的最后一部分生成配置文件。包括` CMakePackageConfigHelpers.cmake`模塊，分三步完成: 1. 調用`write_basic_package_version_file`函數生成一個版本文件包。宏的第一個參數是版本控制文件的路徑：` messageConfigVersion.cmake`。版本格式為`Major.Minor.Patch`，并使用`PROJECT_VERSION`指定版本，還可以指定與庫的新版本的兼容性。例子中，當庫具有相同的主版本時，為了保證兼容性，使用了相同的`SameMajorVersion`參數。 2. 接下來，配置模板文件`messageConfig.cmake.in `，該文件位于`cmake`子目錄中。 3. 最后，為新生成的文件設置安裝規則。兩者都將安裝在`INSTALL_CMAKEDIR`下。 ## 更多信息消息庫的客戶現在非常高興，因為終于可以在自己的系統上安裝這個庫，對自己的`CMakeLists.txt`進行簡單的修改，就能找到消息庫： ```cmake find_package(message VERSION 1 REQUIRED) ``` 客戶可以用以下方式配置他們的項目: ```shell $ cmake -Dmessage_DIR=/path/to/message/share/cmake/message .. ``` 我們示例中包含的測試，顯示了如何檢查目標的安裝是否按照計劃進行。看看`tests`文件夾的結構，我們注意到`use_target`子目錄： ```shell tests/ ├── CMakeLists.txt └── use_target ├── CMakeLists.txt └── use_message.cpp ``` 這個目錄包含一個使用導出目標的小項目。有趣的部分是在CMakeLists.txt文件中指定的測試: 1. 我們測試小項目，可以配置為使用已安裝的庫。這是`use-target`測試固件的設置步驟，可以參考第4章第10節: ```cmake add_test( NAME use-target_configure COMMAND ${CMAKE_COMMAND} -H${CMAKE_CURRENT_LIST_DIR}/use_target -B${CMAKE_CURRENT_BINARY_DIR}/build_use-target -G${CMAKE_GENERATOR} -Dmessage_DIR=${CMAKE_INSTALL_PREFIX}/${ INSTALL_CMAKEDIR} -DCMAKE_BUILD_TYPE=$<CONFIGURATION> ) set_tests_properties(use-target_configure PROPERTIES FIXTURES_SETUP use-target ) ``` 2. 測試了小項目可以構建: ```cmake add_test( NAME use-target_build COMMAND ${CMAKE_COMMAND} --build ${CMAKE_CURRENT_BINARY_DIR}/build_use-target --config $<CONFIGURATION> ) set_tests_properties(use-target_build PROPERTIES FIXTURES_REQUIRED use-target ) ``` 3. 小項目的測試也會運行: ```cmake set(_test_target) if(MSVC) set(_test_target "RUN_TESTS") else() set(_test_target "test") endif() add_test( NAME use-target_test COMMAND ${CMAKE_COMMAND} --build ${CMAKE_CURRENT_BINARY_DIR}/build_use-target --target ${_test_target} --config $<CONFIGURATION> ) set_tests_properties(use-target_test PROPERTIES FIXTURES_REQUIRED use-target ) unset(_test_target) ``` 4. 最后，我們拆除固件: ```cmake add_test( NAME use-target_cleanup COMMAND ${CMAKE_COMMAND} -E remove_directory ${CMAKE_CURRENT_BINARY_DIR}/build_use-target ) set_tests_properties(use-target_cleanup PROPERTIES FIXTURES_CLEANUP use-target ) ``` 注意，這些測試只能在項目安裝之后運行。