11.1 生成源代码和二进制包

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

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

准备工作

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

  1. .
  2. ├── cmake
  3. │    ├── coffee.icns
  4. │    ├── Info.plist.in
  5. │    └── messageConfig.cmake.in
  6. ├── CMakeCPack.cmake
  7. ├── CMakeLists.txt
  8. ├── INSTALL.md
  9. ├── LICENSE
  10. ├── src
  11. │    ├── CMakeLists.txt
  12. │    ├── hello-world.cpp
  13. │    ├── Message.cpp
  14. │    └── Message.hpp
  15. └── tests
  16.     ├── CMakeLists.txt
  17.     └── use_target
  18.         ├── CMakeLists.txt
  19.         └── use_message.cpp

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

具体实施

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

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

    1. set(CPACK_PACKAGE_NAME "${PROJECT_NAME}")

  2. 声明包的供应商：

    1. set(CPACK_PACKAGE_VENDOR "CMake Cookbook")

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

    1. set(CPACK_PACKAGE_DESCRIPTION_FILE "${PROJECT_SOURCE_DIR}/INSTALL.md")

  4. 还添加了一个包的描述:

    1. set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "message: a small messaging library")

  5. 许可证文件也将包括在包中:

    1. set(CPACK_RESOURCE_FILE_LICENSE "${PROJECT_SOURCE_DIR}/LICENSE")

  6. 从发布包中安装时，文件将放在/opt/recipe-01目录下:

    1. set(CPACK_PACKAGING_INSTALL_PREFIX "/opt/${PROJECT_NAME}")

  7. CPack所需的主要、次要和补丁版本:

    1. set(CPACK_PACKAGE_VERSION_MAJOR "${PROJECT_VERSION_MAJOR}")
    2. set(CPACK_PACKAGE_VERSION_MINOR "${PROJECT_VERSION_MINOR}")
    3. set(CPACK_PACKAGE_VERSION_PATCH "${PROJECT_VERSION_PATCH}")

  8. 设置了在包装的时候需要忽略的文件列表和目录:

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

  9. 列出了源代码归档的打包生成器——在我们的例子中是ZIP，用于生成.ZIP归档，TGZ用于.tar.gz归档:

    1. set(CPACK_SOURCE_GENERATOR "ZIP;TGZ")

  10. 我们还列出了二进制存档生成器:

    1. set(CPACK_GENERATOR "ZIP;TGZ")

  11. 现在也可声明平台原生二进制安装程序，从DEB和RPM包生成器开始，不过只适用于GNU/Linux:

    1. if(UNIX)
    2.   if(CMAKE_SYSTEM_NAME MATCHES Linux)
    3.     list(APPEND CPACK_GENERATOR "DEB")
    4.     set(CPACK_DEBIAN_PACKAGE_MAINTAINER "robertodr")
    5.     set(CPACK_DEBIAN_PACKAGE_SECTION "devel")
    6.     set(CPACK_DEBIAN_PACKAGE_DEPENDS "uuid-dev")
    8.     list(APPEND CPACK_GENERATOR "RPM")
    9.     set(CPACK_RPM_PACKAGE_RELEASE "1")
    10.     set(CPACK_RPM_PACKAGE_LICENSE "MIT")
    11.     set(CPACK_RPM_PACKAGE_REQUIRES "uuid-devel")
    12.   endif()
    13. endif()

  12. 如果我们在Windows上，我们会想要生成一个NSIS安装程序:

    1. if(WIN32 OR MINGW)
    2.   list(APPEND CPACK_GENERATOR "NSIS")
    3.   set(CPACK_NSIS_PACKAGE_NAME "message")
    4.   set(CPACK_NSIS_CONTACT "robertdr")
    5.   set(CPACK_NSIS_ENABLE_UNINSTALL_BEFORE_INSTALL ON)
    6. endif()

  13. 另一方面，在macOS上，bundle包是我们的安装程序的选择:

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

  14. 我们在现有系统的包装生成器上，向用户打印一条信息:

    1. message(STATUS "CPack generators: ${CPACK_GENERATOR}")

  15. 最后，我们包括了CPack.cmake标准模块。这将向构建系统添加一个包和一个package_source目标:

    1. include(CPack)

现在来配置这个项目：

  1. $ mkdir -p build
  2. $ cd build
  3. $ cmake ..

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

  1. $ cmake --build . --target help
  3. The following are some of the valid targets for this Makefile:
  4. ... all (the default if no target is provided)
  5. ... clean
  6. ... depend
  7. ... install/strip
  8. ... install
  9. ... package_source
  10. ... package
  11. ... install/local
  12. ... test
  13. ... list_install_components
  14. ... edit_cache
  15. ... rebuild_cache
  16. ... hello- world
  17. ... message

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

  1. $ cmake --build . --target package_source
  3. Run CPack packaging tool for source...
  4. CPack: Create package using ZIP
  5. CPack: Install projects
  6. CPack: - Install directory: /home/user/cmake-cookbook/chapter-11/recipe-01/cxx-example
  7. CPack: Create package
  8. CPack: - package: /home/user/cmake-cookbook/chapter- 11/recipe-01/cxx-example/build/recipe-01-1.0.0-Source.zip generated.
  9. CPack: Create package using TGZ
  10. CPack: Install projects
  11. CPack: - Install directory: /home/user/cmake-cookbook/chapter- 11/recipe-01/cxx-example
  12. CPack: Create package
  13. CPack: - package: /home/user/cmake-cookbook/chapter-11/recipe-01/cxx-example/build/recipe-01- 1.0.0-Source.tar.gz generated.

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

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

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

  1. message-1.0.0-Linux.rpm
  2. message-1.0.0-Linux.tar.gz
  3. 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包可以通过以下步骤生成:

  1. $ cd build
  2. $ cpack -G RPM
  4. CPack: Create package using RPM
  5. CPack: Install projects
  6. CPack: - Run preinstall target for: recipe-01
  7. CPack: - Install project: recipe-01
  8. CPack: Create package
  9. 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
  10. CPack: - package: /home/user/cmake-cookbook/chapter-11/recipe-01/cxx-example/build/recipe-01-1.0.0-Linux.rpm generated.

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

  1. 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文件的内容:

  1. $ tar tzf recipe-01-1.0.0-Source.tar.gz
  3. recipe-01-1.0.0-Source/opt/
  4. recipe-01-1.0.0-Source/opt/recipe-01/
  5. recipe-01-1.0.0-Source/opt/recipe-01/cmake/
  6. recipe-01-1.0.0-Source/opt/recipe-01/cmake/coffee.icns
  7. recipe-01-1.0.0-Source/opt/recipe-01/cmake/Info.plist.in
  8. recipe-01-1.0.0-Source/opt/recipe-01/cmake/messageConfig.cmake.in
  9. recipe-01-1.0.0-Source/opt/recipe-01/CMakeLists.txt
  10. recipe-01-1.0.0-Source/opt/recipe-01/src/
  11. recipe-01-1.0.0-Source/opt/recipe-01/src/Message.hpp
  12. recipe-01-1.0.0-Source/opt/recipe-01/src/CMakeLists.txt
  13. recipe-01-1.0.0-Source/opt/recipe-01/src/Message.cpp
  14. recipe-01-1.0.0-Source/opt/recipe-01/src/hello-world.cpp
  15. recipe-01-1.0.0-Source/opt/recipe-01/LICENSE
  16. recipe-01-1.0.0-Source/opt/recipe-01/tests/
  17. recipe-01-1.0.0-Source/opt/recipe-01/tests/CMakeLists.txt
  18. recipe-01-1.0.0-Source/opt/recipe-01/tests/use_target/
  19. recipe-01-1.0.0-Source/opt/recipe-01/tests/use_target/CMakeLists.txt
  20. recipe-01-1.0.0-Source/opt/recipe-01/tests/use_target/use_message.cpp
  21. recipe-01-1.0.0-Source/opt/recipe-01/INSTALL.md

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

NOTE:Visual Studio生成器无法解析package_source目标:https://gitlab.kitware.com/cmake/cmake/issues/13058。

二进制包

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

  1. $ tar tzf recipe-01-1.0.0-Linux.tar.gz
  3. recipe-01- 1.0.0-Linux/opt/
  4. recipe-01-1.0.0-Linux/opt/recipe-01/
  5. recipe-01-1.0.0- Linux/opt/recipe-01/bin/
  6. recipe-01-1.0.0-Linux/opt/recipe-01/bin/hello- world
  7. recipe-01-1.0.0-Linux/opt/recipe-01/share/
  8. recipe-01-1.0.0- Linux/opt/recipe-01/share/cmake/
  9. recipe-01-1.0.0-Linux/opt/recipe- 01/share/cmake/recipe-01/
  10. recipe-01-1.0.0-Linux/opt/recipe- 01/share/cmake/recipe-01/messageConfig.cmake
  11. recipe-01-1.0.0- Linux/opt/recipe-01/share/cmake/recipe-01/messageTargets-hello- world.cmake
  12. recipe-01-1.0.0-Linux/opt/recipe-01/share/cmake/recipe- 01/messageConfigVersion.cmake
  13. recipe-01-1.0.0-Linux/opt/recipe- 01/share/cmake/recipe-01/messageTargets-hello-world- release.cmake
  14. recipe-01-1.0.0-Linux/opt/recipe-01/share/cmake/recipe- 01/messageTargets-release.cmake
  15. recipe-01-1.0.0-Linux/opt/recipe- 01/share/cmake/recipe-01/messageTargets.cmake
  16. recipe-01-1.0.0- Linux/opt/recipe-01/include/
  17. recipe-01-1.0.0-Linux/opt/recipe- 01/include/message/
  18. recipe-01-1.0.0-Linux/opt/recipe- 01/include/message/Message.hpp
  19. recipe-01-1.0.0-Linux/opt/recipe- 01/include/message/messageExport.h
  20. recipe-01-1.0.0-Linux/opt/recipe- 01/lib64/
  21. recipe-01-1.0.0-Linux/opt/recipe- 01/lib64/libmessage.so
  22. recipe-01-1.0.0-Linux/opt/recipe- 01/lib64/libmessage.so.1`

平台原生的二进制安装

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

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

  1. if(UNIX)
  2.   if(CMAKE_SYSTEM_NAME MATCHES Linux)
  3.     list(APPEND CPACK_GENERATOR "DEB")
  4.     set(CPACK_DEBIAN_PACKAGE_MAINTAINER "robertodr")
  5.     set(CPACK_DEBIAN_PACKAGE_SECTION "devel")
  6.     set(CPACK_DEBIAN_PACKAGE_DEPENDS "uuid-dev")
  8.     list(APPEND CPACK_GENERATOR "RPM")
  9.     set(CPACK_RPM_PACKAGE_RELEASE "1")
  10.     set(CPACK_RPM_PACKAGE_LICENSE "MIT")
  11.     set(CPACK_RPM_PACKAGE_REQUIRES "uuid-devel")
  12.   endif()
  13. endif()

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

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

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

  1. if(WIN32 OR MINGW)
  2.   list(APPEND CPACK_GENERATOR "NSIS")
  3.   set(CPACK_NSIS_PACKAGE_NAME "message")
  4.   set(CPACK_NSIS_CONTACT "robertdr")
  5.   set(CPACK_NSIS_ENABLE_UNINSTALL_BEFORE_INSTALL ON)
  6. endif()

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

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

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

NOTE:可以在这里阅读，关于属性列表格式的更多信息:https://en.wikipedia.org/wiki/Property_list

更多信息

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

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