📘
CMake Cookbook
  • Introduction
  • 前言
  • 第0章 配置环境
    • 0.1 获取代码
    • 0.2 Docker镜像
    • 0.3 安装必要的软件
    • 0.4 测试环境
    • 0.5 上报问题并提出改进建议
  • 第1章 从可执行文件到库
    • 1.1 将单个源文件编译为可执行文件
    • 1.2 切换生成器
    • 1.3 构建和链接静态库和动态库
    • 1.4 用条件句控制编译
    • 1.5 向用户显示选项
    • 1.6 指定编译器
    • 1.7 切换构建类型
    • 1.8 设置编译器选项
    • 1.9 为语言设定标准
    • 1.10 使用控制流
  • 第2章 检测环境
    • 2.1 检测操作系统
    • 2.2 处理与平台相关的源代码
    • 2.3 处理与编译器相关的源代码
    • 2.4 检测处理器体系结构
    • 2.5 检测处理器指令集
    • 2.6 为Eigen库使能向量化
  • 第3章 检测外部库和程序
    • 3.1 检测Python解释器
    • 3.2 检测Python库
    • 3.3 检测Python模块和包
    • 3.4 检测BLAS和LAPACK数学库
    • 3.5 检测OpenMP的并行环境
    • 3.6 检测MPI的并行环境
    • 3.7 检测Eigen库
    • 3.8 检测Boost库
    • 3.9 检测外部库:Ⅰ. 使用pkg-config
    • 3.10 检测外部库:Ⅱ. 自定义find模块
  • 第4章 创建和运行测试
    • 4.1 创建一个简单的单元测试
    • 4.2 使用Catch2库进行单元测试
    • 4.3 使用Google Test库进行单元测试
    • 4.4 使用Boost Test进行单元测试
    • 4.5 使用动态分析来检测内存缺陷
    • 4.6 预期测试失败
    • 4.7 使用超时测试运行时间过长的测试
    • 4.8 并行测试
    • 4.9 运行测试子集
    • 4.10 使用测试固件
  • 第5章 配置时和构建时的操作
    • 5.1 使用平台无关的文件操作
    • 5.2 配置时运行自定义命令
    • 5.3 构建时运行自定义命令:Ⅰ. 使用add_custom_command
    • 5.4 构建时运行自定义命令:Ⅱ. 使用add_custom_target
    • 5.5 构建时为特定目标运行自定义命令
    • 5.6 探究编译和链接命令
    • 5.7 探究编译器标志命令
    • 5.8 探究可执行命令
    • 5.9 使用生成器表达式微调配置和编译
  • 第6章 生成源码
    • 6.1 配置时生成源码
    • 6.2 使用Python在配置时生成源码
    • 6.3 构建时使用Python生成源码
    • 6.4 记录项目版本信息以便报告
    • 6.5 从文件中记录项目版本
    • 6.6 配置时记录Git Hash值
    • 6.7 构建时记录Git Hash值
  • 第7章 构建项目
    • 7.1 使用函数和宏重用代码
    • 7.2 将CMake源代码分成模块
    • 7.3 编写函数来测试和设置编译器标志
    • 7.4 用指定参数定义函数或宏
    • 7.5 重新定义函数和宏
    • 7.6 使用废弃函数、宏和变量
    • 7.7 add_subdirectory的限定范围
    • 7.8 使用target_sources避免全局变量
    • 7.9 组织Fortran项目
  • 第8章 超级构建模式
    • 8.1 使用超级构建模式
    • 8.2 使用超级构建管理依赖项:Ⅰ.Boost库
    • 8.3 使用超级构建管理依赖项:Ⅱ.FFTW库
    • 8.4 使用超级构建管理依赖项:Ⅲ.Google Test框架
    • 8.5 使用超级构建支持项目
  • 第9章 语言混合项目
    • 9.1 使用C/C++库构建Fortran项目
    • 9.2 使用Fortran库构建C/C++项目
    • 9.3 使用Cython构建C++和Python项目
    • 9.4 使用Boost.Python构建C++和Python项目
    • 9.5 使用pybind11构建C++和Python项目
    • 9.6 使用Python CFFI混合C,C++,Fortran和Python
  • 第10章 编写安装程序
    • 10.1 安装项目
    • 10.2 生成输出头文件
    • 10.3 输出目标
    • 10.4 安装超级构建
  • 第11章 打包项目
    • 11.1 生成源代码和二进制包
    • 11.2 通过PyPI发布使用CMake/pybind11构建的C++/Python项目
    • 11.3 通过PyPI发布使用CMake/CFFI构建C/Fortran/Python项目
    • 11.4 以Conda包的形式发布一个简单的项目
    • 11.5 将Conda包作为依赖项发布给项目
  • 第12章 构建文档
    • 12.1 使用Doxygen构建文档
    • 12.2 使用Sphinx构建文档
    • 12.3 结合Doxygen和Sphinx
  • 第13章 选择生成器和交叉编译
    • 13.1 使用CMake构建Visual Studio 2017项目
    • 13.2 交叉编译hello world示例
    • 13.3 使用OpenMP并行化交叉编译Windows二进制文件
  • 第14章 测试面板
    • 14.1 将测试部署到CDash
    • 14.2 CDash显示测试覆盖率
    • 14.3 使用AddressSanifier向CDash报告内存缺陷
    • 14.4 使用ThreadSaniiser向CDash报告数据争用
  • 第15章 使用CMake构建已有项目
    • 15.1 如何开始迁移项目
    • 15.2 生成文件并编写平台检查
    • 15.3 检测所需的链接和依赖关系
    • 15.4 复制编译标志
    • 15.5 移植测试
    • 15.6 移植安装目标
    • 15.7 进一步迁移的措施
    • 15.8 项目转换为CMake的常见问题
  • 第16章 可能感兴趣的书
    • 16.1 留下评论——让其他读者知道你的想法
Powered by GitBook
On this page
  • 准备工作
  • 具体实施
  • 工作原理
  • 打包源码
  • 二进制包
  • 平台原生的二进制安装
  • 更多信息

Was this helpful?

  1. 第11章 打包项目

11.1 生成源代码和二进制包

Previous第11章 打包项目Next11.2 通过PyPI发布使用CMake/pybind11构建的C++/Python项目

Last updated 5 years ago

Was this helpful?

NOTE:此示例代码可以在 中找到。该示例在CMake 3.6版(或更高版本)中是有效的,并且已经在GNU/Linux、macOS和Windows上进行过测试。

如果代码是开源的,用户将能够下载项目的源代码,并使用完全定制的CMake脚本自行构建。当然,打包操作也可以使用脚本完成,但是CPack提供了更简单和可移植的替代方案。本示例将指导您创建一些包:

  • 源代码包:可以将源代码直接压缩成归档文件,进行发送。用户将不必为特定的版本控制系统操心。

  • 二进制包:工具将新构建的目标以打包的方式到归档文件中。这个功能非常有用,但可能不够健壮,无法发布库和可执行程序。

  • 平台原生的二进制安装:CPack能够以许多不同的格式生成二进制安装程序,因此可以将软件发布到不同的平台。我们将展示如何生成安装程序:

    • 基于Debian的GNU/Linux发行版的.deb格式:

    • 基于Red Hat的GNU/Linux发行版的.rpm格式:

    • macOS包的.dmg格式:

    • Windows的NSIS格式:

准备工作

我们将使用第10章第3节的示例,项目树由以下目录和文件组成:

.
├── cmake
│    ├── coffee.icns
│    ├── Info.plist.in
│    └── messageConfig.cmake.in
├── CMakeCPack.cmake
├── CMakeLists.txt
├── INSTALL.md
├── LICENSE
├── src
│    ├── CMakeLists.txt
│    ├── hello-world.cpp
│    ├── Message.cpp
│    └── Message.hpp
└── tests
    ├── CMakeLists.txt
    └── use_target
        ├── CMakeLists.txt
        └── use_message.cpp

由于本示例的重点是使用CPack,所以不会讨论源码。我们只会在CMakeCPack.cmake中添加打包指令。此外,还添加了INSTALL.md和LICENSE文件:打包要求需要包含安装说明和项目许可信息。

具体实施

让我们看看需要添加到这个项目中的打包指令。我们将在CMakeCPack.cmake中收集它们,并在在CMakeLists.txt的末尾包含这个模块include(cmakecpackage.cmake):

  1. 我们声明包的名称,与项目的名称相同,因此我们使用PROJECT_NAME的CMake变量:

    set(CPACK_PACKAGE_NAME "${PROJECT_NAME}")
  2. 声明包的供应商:

    set(CPACK_PACKAGE_VENDOR "CMake Cookbook")
  3. 打包的源代码将包括一个描述文件。这是带有安装说明的纯文本文件:

    set(CPACK_PACKAGE_DESCRIPTION_FILE "${PROJECT_SOURCE_DIR}/INSTALL.md")
  4. 还添加了一个包的描述:

    set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "message: a small messaging library")
  5. 许可证文件也将包括在包中:

    set(CPACK_RESOURCE_FILE_LICENSE "${PROJECT_SOURCE_DIR}/LICENSE")
  6. 从发布包中安装时,文件将放在/opt/recipe-01目录下:

    set(CPACK_PACKAGING_INSTALL_PREFIX "/opt/${PROJECT_NAME}")
  7. CPack所需的主要、次要和补丁版本:

    set(CPACK_PACKAGE_VERSION_MAJOR "${PROJECT_VERSION_MAJOR}")
    set(CPACK_PACKAGE_VERSION_MINOR "${PROJECT_VERSION_MINOR}")
    set(CPACK_PACKAGE_VERSION_PATCH "${PROJECT_VERSION_PATCH}")
  8. 设置了在包装的时候需要忽略的文件列表和目录:

    set(CPACK_SOURCE_IGNORE_FILES "${PROJECT_BINARY_DIR};/.git/;.gitignore")
  9. 列出了源代码归档的打包生成器——在我们的例子中是ZIP,用于生成.ZIP归档,TGZ用于.tar.gz归档:

    set(CPACK_SOURCE_GENERATOR "ZIP;TGZ")
  10. 我们还列出了二进制存档生成器:

    set(CPACK_GENERATOR "ZIP;TGZ")
  11. 现在也可声明平台原生二进制安装程序,从DEB和RPM包生成器开始,不过只适用于GNU/Linux:

    if(UNIX)
      if(CMAKE_SYSTEM_NAME MATCHES Linux)
        list(APPEND CPACK_GENERATOR "DEB")
        set(CPACK_DEBIAN_PACKAGE_MAINTAINER "robertodr")
        set(CPACK_DEBIAN_PACKAGE_SECTION "devel")
        set(CPACK_DEBIAN_PACKAGE_DEPENDS "uuid-dev")
    
        list(APPEND CPACK_GENERATOR "RPM")
        set(CPACK_RPM_PACKAGE_RELEASE "1")
        set(CPACK_RPM_PACKAGE_LICENSE "MIT")
        set(CPACK_RPM_PACKAGE_REQUIRES "uuid-devel")
      endif()
    endif()
  12. 如果我们在Windows上,我们会想要生成一个NSIS安装程序:

    if(WIN32 OR MINGW)
      list(APPEND CPACK_GENERATOR "NSIS")
      set(CPACK_NSIS_PACKAGE_NAME "message")
      set(CPACK_NSIS_CONTACT "robertdr")
      set(CPACK_NSIS_ENABLE_UNINSTALL_BEFORE_INSTALL ON)
    endif()
  13. 另一方面,在macOS上,bundle包是我们的安装程序的选择:

    if(APPLE)
      list(APPEND CPACK_GENERATOR "Bundle")
      set(CPACK_BUNDLE_NAME "message")
      configure_file(${PROJECT_SOURCE_DIR}/cmake/Info.plist.in Info.plist @ONLY)
      set(CPACK_BUNDLE_PLIST ${CMAKE_CURRENT_BINARY_DIR}/Info.plist)
      set(CPACK_BUNDLE_ICON ${PROJECT_SOURCE_DIR}/cmake/coffee.icns)
    endif()
  14. 我们在现有系统的包装生成器上,向用户打印一条信息:

    message(STATUS "CPack generators: ${CPACK_GENERATOR}")
  15. 最后,我们包括了CPack.cmake标准模块。这将向构建系统添加一个包和一个package_source目标:

    include(CPack)

现在来配置这个项目:

$ mkdir -p build
$ cd build
$ cmake ..

使用下面的命令,我们可以列出可用的目标(示例输出是在使用Unix Makefile作为生成器的GNU/Linux系统上获得的):

$ cmake --build . --target help

The following are some of the valid targets for this Makefile:
... all (the default if no target is provided)
... clean
... depend
... install/strip
... install
... package_source
... package
... install/local
... test
... list_install_components
... edit_cache
... rebuild_cache
... hello- world
... message

我们可以看到package和package_source目标是可用的。可以使用以下命令生成源包:

$ cmake --build . --target package_source

Run CPack packaging tool for source...
CPack: Create package using ZIP
CPack: Install projects
CPack: - Install directory: /home/user/cmake-cookbook/chapter-11/recipe-01/cxx-example
CPack: Create package
CPack: - package: /home/user/cmake-cookbook/chapter- 11/recipe-01/cxx-example/build/recipe-01-1.0.0-Source.zip generated.
CPack: Create package using TGZ
CPack: Install projects
CPack: - Install directory: /home/user/cmake-cookbook/chapter- 11/recipe-01/cxx-example
CPack: Create package
CPack: - package: /home/user/cmake-cookbook/chapter-11/recipe-01/cxx-example/build/recipe-01- 1.0.0-Source.tar.gz generated.

同样,也可以构建二进制包:

$ cmake --build . --target package message-1.0.0-Linux.deb

例子中,最后得到了以下二进制包:

message-1.0.0-Linux.rpm
message-1.0.0-Linux.tar.gz
message-1.0.0-Linux.zip

工作原理

CPack可用于生成用于分发的包。生成构建系统时,我们在CMakeCPack.cmake中列出了CPack指令,用于在构建目录下生成CPackConfig.cmake。当运行以package或package_source目标的CMake命令时,CPack会自动调用,参数是自动生成的配置文件。实际上,这两个新目标是对CPack简单规则的使用。与CMake一样,CPack也有生成器的概念。CMake上下文中的生成器是用于生成本地构建脚本的工具,例如Unix Makefile或Visual Studio项目文件,而CPack上下文中的生成器是用于打包的工具。我们列出了这些变量,并对不同的平台进行了特别的关注,为源包和二进制包定义了CPACK_SOURCE_GENERATOR和CPACK_GENERATOR变量。因此,DEB包生成器将调用Debian打包实用程序,而TGZ生成器将调用给定平台上的归档工具。我们可以直接在build目录中调用CPack,并选择要与-G命令行选项一起使用的生成器。RPM包可以通过以下步骤生成:

$ cd build
$ cpack -G RPM

CPack: Create package using RPM
CPack: Install projects
CPack: - Run preinstall target for: recipe-01
CPack: - Install project: recipe-01
CPack: Create package
CPackRPM: Will use GENERATED spec file: /home/user/cmake-cookbook/chapter-11/recipe-01/cxx-example/build/_CPack_Packages/Linux/RPM/SPECS/recipe-01.spec
CPack: - package: /home/user/cmake-cookbook/chapter-11/recipe-01/cxx-example/build/recipe-01-1.0.0-Linux.rpm generated.

对于任何发行版,无论是源代码还是二进制文件,我们只需要打包用户需要的内容,因此整个构建目录和其他与版本控制相关的文件,都必须从要打包的文件列表中排除。我们的例子中,排除列表使用下面的命令声明:

set(CPACK_SOURCE_IGNORE_FILES "${PROJECT_BINARY_DIR};/.git/;.gitignore")

我们还需要指定包的基本信息,例如:名称、简短描述和版本。这个信息是通过CMake变量设置的,当包含相应的模块时,CMake变量被传递给CPack。

NOTE:由于CMake 3.9中的project()命令接受DESCRIPTION字段,该字段带有一个描述项目的短字符串。CMake将设置一个PROJECT_DESCRIPTION,可以用它来重置CPACK_PACKAGE_DESCRIPTION_SUMMARY。

让我们详细看看,可以为示例项目生成的不同类型包的说明。

打包源码

我们的示例中,决定对源存档使用TGZ和ZIP生成器。这些文件将分别生成.tar.gz和.zip压缩文件。我们可以检查生成的.tar.gz文件的内容:

$ tar tzf recipe-01-1.0.0-Source.tar.gz

recipe-01-1.0.0-Source/opt/
recipe-01-1.0.0-Source/opt/recipe-01/
recipe-01-1.0.0-Source/opt/recipe-01/cmake/
recipe-01-1.0.0-Source/opt/recipe-01/cmake/coffee.icns
recipe-01-1.0.0-Source/opt/recipe-01/cmake/Info.plist.in
recipe-01-1.0.0-Source/opt/recipe-01/cmake/messageConfig.cmake.in
recipe-01-1.0.0-Source/opt/recipe-01/CMakeLists.txt
recipe-01-1.0.0-Source/opt/recipe-01/src/
recipe-01-1.0.0-Source/opt/recipe-01/src/Message.hpp
recipe-01-1.0.0-Source/opt/recipe-01/src/CMakeLists.txt
recipe-01-1.0.0-Source/opt/recipe-01/src/Message.cpp
recipe-01-1.0.0-Source/opt/recipe-01/src/hello-world.cpp
recipe-01-1.0.0-Source/opt/recipe-01/LICENSE
recipe-01-1.0.0-Source/opt/recipe-01/tests/
recipe-01-1.0.0-Source/opt/recipe-01/tests/CMakeLists.txt
recipe-01-1.0.0-Source/opt/recipe-01/tests/use_target/
recipe-01-1.0.0-Source/opt/recipe-01/tests/use_target/CMakeLists.txt
recipe-01-1.0.0-Source/opt/recipe-01/tests/use_target/use_message.cpp
recipe-01-1.0.0-Source/opt/recipe-01/INSTALL.md

与预期相同,只包含源码树的内容。注意INSTALL.md和LICENSE文件也包括在内,可以通过CPACK_PACKAGE_DESCRIPTION_FILE和CPACK_RESOURCE_FILE_LICENSE变量指定。

二进制包

创建二进制存档时,CPack将打包CMakeCPack.cmake中描述的目标的内容。因此,在我们的示例中,hello-world可执行文件、消息动态库以及相应的头文件都将以.tar.gz和.zip的格式打包。此外,还将打包CMake配置文件。这对于需要链接到我们的库的其他项目非常有用。包中使用的安装目录可能与从构建树中安装项目时使用的前缀不同,可以使用CPACK_PACKAGING_INSTALL_PREFIX变量来实现这一点。我们的示例中,我们将它设置为系统上的特定位置:/opt/recipe-01。

$ tar tzf recipe-01-1.0.0-Linux.tar.gz

recipe-01- 1.0.0-Linux/opt/
recipe-01-1.0.0-Linux/opt/recipe-01/
recipe-01-1.0.0- Linux/opt/recipe-01/bin/
recipe-01-1.0.0-Linux/opt/recipe-01/bin/hello- world
recipe-01-1.0.0-Linux/opt/recipe-01/share/
recipe-01-1.0.0- Linux/opt/recipe-01/share/cmake/
recipe-01-1.0.0-Linux/opt/recipe- 01/share/cmake/recipe-01/
recipe-01-1.0.0-Linux/opt/recipe- 01/share/cmake/recipe-01/messageConfig.cmake
recipe-01-1.0.0- Linux/opt/recipe-01/share/cmake/recipe-01/messageTargets-hello- world.cmake
recipe-01-1.0.0-Linux/opt/recipe-01/share/cmake/recipe- 01/messageConfigVersion.cmake
recipe-01-1.0.0-Linux/opt/recipe- 01/share/cmake/recipe-01/messageTargets-hello-world- release.cmake
recipe-01-1.0.0-Linux/opt/recipe-01/share/cmake/recipe- 01/messageTargets-release.cmake
recipe-01-1.0.0-Linux/opt/recipe- 01/share/cmake/recipe-01/messageTargets.cmake
recipe-01-1.0.0- Linux/opt/recipe-01/include/
recipe-01-1.0.0-Linux/opt/recipe- 01/include/message/
recipe-01-1.0.0-Linux/opt/recipe- 01/include/message/Message.hpp
recipe-01-1.0.0-Linux/opt/recipe- 01/include/message/messageExport.h
recipe-01-1.0.0-Linux/opt/recipe- 01/lib64/
recipe-01-1.0.0-Linux/opt/recipe- 01/lib64/libmessage.so
recipe-01-1.0.0-Linux/opt/recipe- 01/lib64/libmessage.so.1`

平台原生的二进制安装

我们希望每个平台原生二进制安装程序的配置略有不同。可以在单个CMakeCPack.cmake中使用CPack管理这些差异,就像例子中做的那样。

对于GNU/Linux系统,配置了DEB和RPM生成器:

if(UNIX)
  if(CMAKE_SYSTEM_NAME MATCHES Linux)
    list(APPEND CPACK_GENERATOR "DEB")
    set(CPACK_DEBIAN_PACKAGE_MAINTAINER "robertodr")
    set(CPACK_DEBIAN_PACKAGE_SECTION "devel")
    set(CPACK_DEBIAN_PACKAGE_DEPENDS "uuid-dev")

    list(APPEND CPACK_GENERATOR "RPM")
    set(CPACK_RPM_PACKAGE_RELEASE "1")
    set(CPACK_RPM_PACKAGE_LICENSE "MIT")
    set(CPACK_RPM_PACKAGE_REQUIRES "uuid-devel")
  endif()
endif()

我们的示例依赖于UUID库,CPACK_DEBIAN_PACKAGE_DEPENDS和cpack_rpm_package_require选项允许指定,包和数据库中对其他包的依赖关系。可以使用dpkg和rpm程序分别分析生成的.deb和.rpm包的内容。

注意,CPACK_PACKAGING_INSTALL_PREFIX也会影响这些包生成器:我们的包将安装到/opt/recipe-01。

CMake真正提供了跨平台和可移植构建系统的支持。下面将使用Nullsoft脚本安装系统(NSIS)创建一个安装程序:

if(WIN32 OR MINGW)
  list(APPEND CPACK_GENERATOR "NSIS")
  set(CPACK_NSIS_PACKAGE_NAME "message")
  set(CPACK_NSIS_CONTACT "robertdr")
  set(CPACK_NSIS_ENABLE_UNINSTALL_BEFORE_INSTALL ON)
endif()

如果在macOS上构建项目,将启用Bundle packager:

if(APPLE)
  list(APPEND CPACK_GENERATOR "Bundle")
  set(CPACK_BUNDLE_NAME "message")
  configure_file(${PROJECT_SOURCE_DIR}/cmake/Info.plist.in Info.plist @ONLY)
  set(CPACK_BUNDLE_PLIST ${CMAKE_CURRENT_BINARY_DIR}/Info.plist)
  set(CPACK_BUNDLE_ICON ${PROJECT_SOURCE_DIR}/cmake/coffee.icns)
endif()

macOS的示例中,需要为包配置属性列表文件,这是通过configure_file实现的。Info.plist的位置和包的图标,这些都可以通过CPack的变量进行设置。

更多信息

NOTE:Visual Studio生成器无法解析package_source目标:

NOTE:可以在这里阅读,关于属性列表格式的更多信息:

对CMakeCPack.cmake进行设置,要比列出CPack的配置选项简单的多,我们可以将CPACK_*变量的每个生成器设置放在单独的文件中,比如CMakeCPackOptions.cmake,并将这些设置包含到CMakeCPack.cmake使用set(CPACK_PROJECT_CONFIG_FILE "${PROJECT_SOUsRCE_DIR}/CMakeCPackOptions.cmake")将设置包含入CMakeCPack.cmake中。还可以在CMake时配置该文件,然后在CPack时包含该文件,这为配置多格式包生成器提供了一种简洁的方法(参见 )。

与CMake中的所有工具一样,CPack功能强大、功能多样,并且提供了更多的灵活性和选项。感兴趣的读者应该看官方文档的命令行界面CPack ( )手册页,如何使用CPack生成器打包相关项目的更多细节( )。

https://github.com/dev-cafe/cmake-cookbook/tree/v1.0/chapter-11/recipe-01
https://manpages.debian.org/unstable/dpkg-dev/deb.5.en.html
http://rpm.org/
https://developer.apple.com/library/archive/documentation/CoreFoundation/Conceptual/CFBundles/BundleTypes/BundleTypes.html
http://nsis.sourceforge.net/Main_Page
https://gitlab.kitware.com/cmake/cmake/issues/13058。
https://en.wikipedia.org/wiki/Property_list
https://cmake.org/cmake/help/v3.6/module/CPack.html
https://cmake.org/cmake/help/v3.6/manual/cpack.1.html
https://cmake.org/cmake/help/v3.6/module/CPack.html