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的项目可以轻松地获取它们。

准备工作

源代码与之前的示例一致，项目结构如下:

.
├── 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库，可以重用之前示例中的代码：

  2. 接下来，设置动态库目标并生成导出头文件：

  3. 为目标设置了PUBLIC和INTERFACE编译定义。注意$<INSTALL_INTERFACE:...>生成器表达式的使用：

  4. 链接库和目标属性与前一个示例一样：

  5. 可执行文件的生成，与前一个示例中使用的命令完全相同：

现在，来看看安装规则：

  1. 因为CMake可以正确地将每个目标放在正确的地方，所以把目标的安装规则都列在一起。这次，添加了EXPORT关键字，这样CMake将为目标生成一个导出的目标文件：

  2. 自动生成的导出目标文件称为messageTargets.cmake，需要显式地指定它的安装规则。这个文件的目标是INSTALL_CMAKEDIR，在主CMakeLists.txt文件中定义:

  3. 最后，需要生成正确的CMake配置文件。这些将确保下游项目能够找到消息库导出的目标。为此，首先包括CMakePackageConfigHelpers.cmake标准模块：

  4. 让CMake为我们的库，生成一个包含版本信息的文件:

  5. 使用configure_package_config_file函数，我们生成了实际的CMake配置文件。这是基于模板cmake/messageConfig.cmake.in文件:

  6. 最后，为这两个自动生成的配置文件设置了安装规则:

cmake/messageConfig.cmake的内容是什么？该文件的顶部有相关的说明，可以作为用户文档供使用者查看。让我们看看实际的CMake命令:

  1. 占位符将使用configure_package_config_file命令进行替换:

  2. 包括为目标自动生成的导出文件:

  3. 检查静态库和动态库，以及两个“Hello, World”可执行文件是否带有CMake提供的check_required_components函数：

  4. 检查目标PkgConfig::UUID是否存在。如果没有，我们再次搜索UUID库(只在非Windows操作系统下有效):

测试一下：

安装树应该如下所示：

出现了一个share子目录，其中包含我们要求CMake自动生成的所有文件。现在开始，消息库的用户可以在他们自己的CMakeLists.txt文件中找到消息库，只要他们设置message_DIR的CMake变量，指向安装树中的share/cmake/message目录:

工作原理

这个示例涵盖了很多领域。对于构建系统将要执行的操作，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文件中设置的:

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进行简单的修改，就能找到消息库：

客户可以用以下方式配置他们的项目:

我们示例中包含的测试，显示了如何检查目标的安装是否按照计划进行。看看tests文件夹的结构，我们注意到use_target子目录：

这个目录包含一个使用导出目标的小项目。有趣的部分是在CMakeLists.txt文件中指定的测试:

  1. 我们测试小项目，可以配置为使用已安装的库。这是use-target测试固件的设置步骤，可以参考第4章第10节:

  2. 测试了小项目可以构建:

  3. 小项目的测试也会运行:

  4. 最后，我们拆除固件:

注意，这些测试只能在项目安装之后运行。

Previous10.2 生成输出头文件Next10.4 安装超级构建

Last updated

Was this helpful?