10.4 安装超级构建

NOTE:此示例代码可以在 https://github.com/dev-cafe/cmake-cookbook/tree/v1.0/chapter-10/recipe-04 中找到，其中有一个C++示例。该示例在CMake 3.6版(或更高版本)中是有效的，并且已经在GNU/Linux、macOS和Windows上进行过测试。

我们的消息库取得了巨大的成功，许多其他程序员都使用它，并且非常满意。也希望在自己的项目中使用它，但是不确定如何正确地管理依赖关系。可以用自己的代码附带消息库的源代码，但是如果该库已经安装在系统上了应该怎么做呢？第8章，展示了超级构建的场景，但是不确定如何安装这样的项目。本示例将带您了解安装超级构建的安装细节。

准备工作

此示例将针对消息库，构建一个简单的可执行链接。项目布局如下:

├── cmake
│    ├── install_hook.cmake.in
│    └── print_rpath.py
├── CMakeLists.txt
├── external
│    └── upstream
│        ├── CMakeLists.txt
│        └── message
│            └── CMakeLists.txt
└── src
    ├── CMakeLists.txt
    └── use_message.cpp

主CMakeLists.txt文件配合超级构建，external子目录包含处理依赖项的CMake指令。cmake子目录包含一个Python脚本和一个模板CMake脚本。这些将用于安装方面的微调，CMake脚本首先进行配置，然后调用Python脚本打印use_message可执行文件的RPATH:

import shlex
import subprocess
import sys

def main():
  patcher = sys.argv[1]
  elfobj = sys.argv[2]
  tools = {'patchelf': '--print-rpath', 'chrpath': '--list', 'otool': '-L'}
  if patcher not in tools.keys():
  raise RuntimeError('Unknown tool {}'.format(patcher))
  cmd = shlex.split('{:s} {:s} {:s}'.format(patcher, tools[patcher], elfobj))
  rpath = subprocess.run(
      cmd,
      bufsize=1,
      stdout=subprocess.PIPE,
      stderr=subprocess.PIPE,
      universal_newlines=True)
  print(rpath.stdout)

if __name__ == "__main__":
  main()

使用平台原生工具可以轻松地打印RPATH，稍后我们将在本示例中讨论这些工具。

最后，src子目录包含项目的CMakeLists.txt和源文件。use_message.cpp源文件包含以下内容:

具体实施

我们将从主CMakeLists.txt文件开始，它用来协调超级构建:

  1. 与之前的示例相同。首先声明一个C++11项目，设置了默认安装路径、构建类型、目标的输出目录，以及安装树中组件的布局:

  2. 设置了EP_BASE目录属性，这将为超构建中的子项目设置布局。所有子项目都将在CMAKE_BINARY_DIR的子项目文件夹下生成:

  3. 然后，声明STAGED_INSTALL_PREFIX变量。这个变量指向构建目录下的stage子目录，项目将在构建期间安装在这里。这是一种沙箱安装过程，让我们有机会检查整个超级构建的布局:

  4. 添加external/upstream子目录。其中包括使用CMake指令来管理我们的上游依赖关系，在我们的例子中，就是消息库:

  5. 然后，包含ExternalProject.cmake标准模块:

  6. 将自己的项目作为外部项目添加，调用ExternalProject_Add命令。SOURCE_DIR用于指定源位于src子目录中。我们会选择适当的CMake参数来配置我们的项目。这里，使用STAGED_INSTALL_PREFIX作为子项目的安装目录:

  7. 现在，为use_message添加一个测试，并由recipe-04_core构建。这将运行use_message可执行文件的安装，即位于构建树中的安装:

  8. 最后，可以声明安装规则。因为所需要的东西都已经安装在暂存区域中，我们只要将暂存区域的内容复制到安装目录即可:

  9. 使用SCRIPT参数声明一个附加的安装规则。CMake脚本的install_hook.cmake将被执行，但只在GNU/Linux和macOS上执行。这个脚本将打印已安装的可执行文件的RPATH，并运行它。我们将在下一节详细地讨论这个问题：

-Dmessage_DIR=${message_DIR}已作为CMake参数传递给项目，这将正确设置消息库依赖项的位置。message_DIR的值在external/upstream/message目录下的CMakeLists.txt文件中定义。这个文件处理依赖于消息库，让我们看看是如何处理的:

  1. 首先，搜索并找到包。用户可能已经在系统的某个地方安装了，并在配置时传递了message_DIR:

  2. 如果找到了消息库，我们将向用户报告目标的位置和版本，并添加一个虚拟的message_external目标。这里，需要虚拟目标来正确处理超构建的依赖关系:

  3. 如果没有找到这个库，我们将把它添加为一个外部项目，从在线Git存储库下载它，然后编译它。安装路径、构建类型和安装目录布局都是由主CMakeLists.txt文件设置，C++编译器和标志也是如此。项目将安装到STAGED_INSTALL_PREFIX下，然后进行测试:

  4. 最后，将message_DIR目录进行设置，为指向新构建的messageConfig.cmake文件指明安装路径。注意，这些路径被保存到CMakeCache中:

我们终于准备好编译我们自己的项目，并成功地将其链接到消息库(无论是系统上已有的消息库，还是新构建的消息库)。由于这是一个超级构建，src子目录下的代码是一个完全独立的CMake项目:

  1. 声明一个C++11项目：

  2. 尝试找到消息库。超级构建中，正确设置message_DIR:

  3. 添加可执行目标use_message，该目标由use_message.cpp源文件创建，并连接到message::message-shared目标:

  4. 为use_message设置目标属性。再次对RPATH进行设置:

  5. 最后，为use_message目标设置了安装规则:

现在瞧瞧CMake脚本模板install_hook.cmake.in的内容：

  1. CMake脚本在我们的主项目范围之外执行，因此没有定义变量或目标的概念。因此，需要设置变量来保存已安装的use_message可执行文件的完整路径。注意使用@INSTALL_BINDIR@，它将由configure_file解析：

  2. 需要找到平台本机可执行工具，使用该工具打印已安装的可执行文件的RPATH。我们将搜索chrpath、patchelf和otool。当找到已安装的程序时，向用户提供有用的状态信息，并且退出搜索：

  3. 检查_patcher变量是否为空，这意味着PatchELF工具是否可用。当为空时，我们要进行的操作将会失败，所以会发出一个致命错误，提醒用户需要安装PatchELF工具:

  4. 当PatchELF工具找到了，则继续。我们调用Python脚本print_rpath.py，将_executable变量作为参数传递给execute_process：

  5. 检查_res变量的返回代码。如果执行成功，将打印_out变量中捕获的标准输出流。否则，打印退出前捕获的标准输出和错误流:

  6. 再使用execute_process来运行已安装的use_message可执行目标:

  7. 最后，向用户报告execute_process的结果:

工作原理

CMake工具箱中，超级构建是非常有用的模式。它通过将复杂的项目划分为更小、更容易管理的子项目来管理它们。此外，可以使用CMake作为构建项目的包管理器。CMake可以搜索依赖项，如果在系统上找不到依赖项，则重新构建它们。这里需要三个CMakeLists.txt文件：

  • 主CMakeLists.txt文件包含项目和依赖项共享的设置，还包括我们自己的项目(作为外部项目)。本例中，我们选择的名称为${PROJECT_NAME}_core；也就是recipe-04_core，因为项目名称recipe-04用于超级构建。

  • 外部CMakeLists.txt文件将尝试查找上游依赖项，并在导入目标和构建目标之间进行切换，这取决于是否找到了依赖项。对于每个依赖项，最好有单独的子目录，其中包含一个CMakeLists.txt文件。

  • 最后，我们项目的CMakeLists.txt文件，可以构建一个独立的CMake项目。在原则上，我们可以自己配置和构建它，而不需要超级构建提供的依赖关系管理工具。

当对消息库的依赖关系未得到满足时，将首先考虑超级构建:

让CMake查找库，这是我们得到的输出:

根据指令，CMake报告如下:

  • 安装将分阶段进入构建树。分阶段安装是对实际安装过程进行沙箱化的一种方法。作为开发人员，这对于在运行安装命令之前检查所有库、可执行程序和文件是否安装在正确的位置非常有用。对于用户来说，可在构建目录中给出了相同的结构。这样，即使没有运行正确的安装，我们的项目也可以立即使用。

  • 系统上没有找到合适的消息库。然后，CMake将运行在构建项目之前构建库所提供的命令，以满足这种依赖性。

如果库已经位于系统的已知位置，我们可以将-Dmessage_DIR选项传递给CMake:

事实上，这个库已经找到并导入。我们对自己的项目进行建造操作:

项目的最终安装规则是，将安装文件复制到CMAKE_INSTALL_PREFIX:

注意使用.而不是绝对路径${CMAKE_INSTALL_PREFIX}，这样CPack工具就可以正确理解该规则。CPack的用法将在第11章中介绍。

recipe-04_core项目构建一个简单的可执行目标，该目标链接到消息动态库。正如本章前几节所讨论，为了让可执行文件正确运行，需要正确设置RPATH。本章的第1节展示了，如何在CMake的帮助下实现这一点，同样的模式在CMakeLists.txt中被重用，用于创建use_message的可执行目标:

为了检查这是否合适，可以使用本机工具打印已安装的可执行文件的RPATH。我们将对该工具的调用，封装到Python脚本中，并将其进一步封装到CMake脚本中。最后，使用SCRIPT关键字将CMake脚本作为安装规则调用:

脚本是在安装最后进行执行:

GNU/Linux系统上，我们将看到以下输出:

NOTE:我们建议使用的工具是PatchELF (https://nixos.org/patchelf.html )、chrpath (https://linux.die.net/man/1/chrpath )和otool (http://www.manpagez.com/man/1/otool/ )。第一种方法适用于GNU/Linux和macOS，而chrpath和otool分别适用于GNU/Linux和macOS。

Previous10.3 输出目标Next第11章 打包项目

Last updated

Was this helpful?