CMake 安装和打包

为了方便使用项目编译的目标文件，快速部署到目标目录，可以使用CMake的安装功能；如果需要对外发布，提供头文件、库文件、或者demo的压缩包则可以使用CMake的打包功能。

在本系列前序的文章中已经介绍了CMake很多内容，在CMake应用：CMakeLists.txt完全指南一文中简略介绍了安装和打包，本文会更加深入地介绍CMake的安装打包功能。本系列更多精彩文章敬请关注公众号【很酷的程序员】的话题：CMake。

本文主要介绍以下几个方面的内容：

1. 安装库文件、可执行文件和所需要对外提供的头文件

2. 将需要安装的文件打包成压缩包

3. 编译构建脚本编写

本文会先介绍相关命令和知识点，如果想先实践，可直接跳到最后一部分。

一 安装

1 install命令

安装使用install命令，用于指定一个项目的安装规则。其命令格式如下：

1.  
   install(TARGETS <target>... [...])
2.  
   install({FILES | PROGRAMS} <file>... [...])
3.  
   install(DIRECTORY <dir>... [...])
4.  
   install(SCRIPT <file> [...])
5.  
   install(CODE <code> [...])
6.  
   install(EXPORT <export-name> [...])

以上命令概述显示install命令可以安装的目标类型：构建目标、文件、程序、目录等，对应的关键字后面跟上对应要安装的目标。

安装不同的目标的时候，有一些通用的关键字，下面着重介绍几个最常使用的。

DESTINATION

很好理解，就是安装对象的目标安装路径，可以是绝对路径，也可以是相对路径，如果是相对路径，则认为是相对于CMAKE_INSTALL_PREFIX的，所以可以配置CMAKE_INSTALL_PREFIX指定安装目录。

因为cpack并不支持绝对路径，所以建议还是不要使用绝对路径，当然，除非这是开发者自己确切的目的。

CONFIGURATIONS

为不同的配置设置不同的安装规则。假如对Debug和Release两个配置不同的安装路径，代码示例如下：

1.  
   install(TARGETS target
2.  
           CONFIGURATIONS Debug
3.  
           RUNTIME DESTINATION Debug/bin)
4.  
   install(TARGETS target
5.  
           CONFIGURATIONS Release
6.  
           RUNTIME DESTINATION Release/bin)

PERMISSIONS

设置安装目标的权限，接受的参数是一个权限关键字列表，比如：

1.  
   install(TARGETS target
2.  
           RUNTIME PERMISSIONS OWNER_READ OWNER_WRITE OWNER_EXECUTE)

2 安装构建目标

安装构建目标的命令格式为：

1.  
   install(TARGETS static_lib shared_lib exe
2.  
               RUNTIME DESTINATION bin
3.  
               LIBRARY DESTINATION lib
4.  
               ARCHIVE DESTINATION lib)

命令第一个参数TARGETS指定需要安装的构建目标的列表，可以是静态库文件、动态库文件、可执行文件；安装时常常按照文件类型安装到不同的子目录，比如库文件放在lib目录，可执行文件放在bin目录。

针对不同文件类型，比如（RUNTIME, ARCHIVE, LIBRARY，PUBLIC_HEADER），可以分开进行配置，比如分别指定安装路径（DESTINATION）、设置文件权限（PERMISSIONS）；如果不是在某个类别下的单独配置，那么就是针对所有类型。

值得一提的是，ARCHIVE一般是指静态库，LIBRARY则是指共享库，在不同平台上，略有差异，实际应用感觉不符合预期时查看一下官方文档即可，问题不大。

3 安装目录

安装一个目录，一般用于将头文件安装到目标路径。在实际使用中，一般把需要安装的头文件放到一个特定目录下，然后直接安装整个目录即可，比如：

1.  
   install(DIRECTORY "${PROJECT_SOURCE_DIR}/include/"
2.  
         DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}")

更加完备的命令格式为：

1.  
   install(DIRECTORY dirs...
2.  
           TYPE <type> | DESTINATION <dir>
3.  
           [FILES_MATCHING]
4.  
           [[PATTERN <pattern> | REGEX <regex>]
5.  
            [EXCLUDE] [PERMISSIONS permissions...]]

TYPE/DESTINATION

安装目录必须执行安装的目录类型TYPE或者安装的目标路径DESTINATION，但是又不可以同时指定；可以使用TYPE指定安装的目录中的文件类型，然后CMake会自动按照类型分配安装目录，不同类型对应的安装路径如下图：

当然，开发者也可以选择只使用DESTINATION显式指定安装的目录。

FILES_MATCHING

安装目录的时候默认会安装所有的文件，如果使用FILES_MATCHING关键字（在第一个PATTERN或者REGEX之前），则表示必须要满足对应的模式或者正则的文件才能被安装。

比如，如果目录下源文件和头文件混在一起，但是只想安装其中的头文件，则可以这样写：

1.  
   install(DIRECTORY src/ DESTINATION include/
2.  
           FILES_MATCHING PATTERN "*.h")

PATTERN/REGEX

PATTERN表示文件名完全匹配才会被安装，而REGEX则是通过正则表达式匹配目标安装文件（针对目标文件的全路径）；在这两个表达式后面还可以加上EXCLUDE表示反选，或者使用PERMISSIONS指定匹配的目标文件的权限。

4 安装文件

和安装目录类似，只不过是安装的是文件列表，核心的参数也是类似的；需要使用TYPE指定文件类型，自行推断安装目录，或者使用DESTINATION显式指定安装目录。命令格式为：

1.  
   install(<FILES|PROGRAMS> files...
2.  
           TYPE <type> | DESTINATION <dir>

FILES和PROGRAMS的不同之处在于文件的默认权限，前者是一般文件，而后者为可执行文件，默认有可执行权限，包括：OWNER_EXECUTE，GROUP_EXECUTE和WORLD_EXECUTE。

5 自定义安装脚本

使用install命令还可以在安装的时候执行自定义的脚本，使用的命令格式为：

1.  
   install([[SCRIPT <file>] [CODE <code>]]
2.  
           [COMPONENT <component>] [EXCLUDE_FROM_ALL] [...])

SCRIPT指定安装时需要执行的脚本；CODE指定的是CMake的命令，也在安装期间执行，比如：

install(CODE "MESSAGE(\"Sample install message.\")")

 

6 执行安装

在构建编译完成之后，可以使用命令执行安装：

1.  
   cmake --build . --target install
2.  
   # 或者针对make构建工具
3.  
   make install

更加优雅的方法是在cmake3.15版本往后，使用cmake --install命令：

cmake --install . --prefix "../output"

 

--install指定构建目录；--prefix指定安装路径，覆盖安装路径变量CMAKE_INSTALL_PREFIX。

二 打包

1 CPack

要使用打包功能，需要执行include(CPack)启用相关的功能。

include(CPack)会在构建路径(Build tree)下生成两个cpack的配置文件，CPackConfig.cmake和CPackSourceConfig.cmake，其实也就对应了两个构建目标：package和package_source；

配合cpack命令，使用-G参数指定生成器，常用的有ZIP、TGZ、7Z等，可以同时指定多个，格式也是CMake语法中的列表，例如其默认值"STGZ;TGZ"；--config参数可以指定打包配置文件，比如：

1.  
   cpack -G TGZ --config CPackConfig.cmake
2.  
   cpack -G TGZ --config CPackSourceConfig.cmake

当然也可以使用cmake命令：

1.  
   cmake --build . --target package
2.  
   cmake --build . --target package_source

如果使用make作为构建工具，可以简单地执行:

1.  
   make package
2.  
   make package_source

2 CMake打包相关的内置变量

打包的内容就是install命令安装的内容，以目标打包（CPackConfig.cmake）为例，主要的相关变量有：

变量	含义
CPACK_GENERATOR	打包使用的压缩工具，比如"ZIP"；cpack命令的-G参数会覆盖此设置
CPACK_OUTPUT_CONFIG_FILE	配置文件，默认为CPackConfig.cmake
CPACK_OUTPUT_FILE_PREFIX	打包安装的路径前缀。如果是相对路径，则是相对于构建目录
CPACK_INSTALL_PREFIX	打包压缩包的内部目录前缀
CPACK_PACKAGE_FILE_NAME	打包压缩包的名称，由CPACK_PACKAGE_NAME、CPACK_PACKAGE_VERSION、CPACK_SYSTEM_NAME三部分构成

需要特别注意的是：以上变量的设置需要在include(CPack)语句之前。

Before including this CPack module in your CMakeLists.txt file, there are a variety of variables that can be set to customize the resulting installers.

其中CPACK_PACKAGE_NAME默认为项目名称，CPACK_PACKAGE_VERSION默认为项目版本号，它们的默认值都是对应project命令所设置的值；但是如果没有指定版本号，则会是CMake的默认值。

假如:CPACK_OUTPUT_FILE_PREFIX设置为/usr/local/package；CPACK_INSTALL_PREFIX设置为RealCoolEngineer；CPACK_PACKAGE_FILE_NAME设置为CMakeTemplate-1.0.0；那么执行打包文件的生成路径为：

/usr/local/package/CMakeTemplate-1.0.0.zip

 

解压这个包得到的目标文件则会位于路径下：

/usr/local/package/CMakeTemplate-1.0.0/RealCoolEngineer/

 

对于源文件打包，相关的变量名基本是对应地以CPACK_SOURCE_开头，细节可以查看官方文档。

三 实践

本文仍以开源项目：https://gitee.com/RealCoolEngineer/cmake-template为例，本文对应的commit id为：5713908。

在项目根目录中的CMakeLists.txt文件中，使用安装和打包的语句为：

1.  
   # Install
2.  
   install(TARGETS math demo
3.  
           RUNTIME DESTINATION bin
4.  
           LIBRARY DESTINATION lib
5.  
           ARCHIVE DESTINATION lib
6.  
           PUBLIC_HEADER DESTINATION include)
7.  
   file(GLOB_RECURSE MATH_LIB_HEADERS src/c/math/*.h)
8.  
   install(FILES ${MATH_LIB_HEADERS} DESTINATION include/math)
9.  
    
10.  
    # Package
11.  
    set(CPACK_GENERATOR "ZIP")
12.  
    set(CPACK_SET_DESTDIR ON)  # 支持指定安装目录
13.  
    set(CPACK_INSTALL_PREFIX "RealCoolEngineer")
14.  
    include(CPack)

安装打包的内容为项目构建目标可执行文件demo，静态库math，以及math库对应的头文件。

1 构建脚本

为了方便，笔者通常将构建的命令编写为脚本，在脚本内指定文件的安装、打包的目标目录（CMake参数）。

下面针对cmake-template的一个示范，将目标文件安装并打包到项目根目录下的output目录：

1.  
   #!/bin/bash
2.  
    
3.  
   set -euf -o pipefail
4.  
    
5.  
   BUILD_DIR="cmake-build"
6.  
   INSTALL_DIR=$(pwd)/output
7.  
   rm -rf "${BUILD_DIR}"
8.  
    
9.  
   # Configure
10.  
    BUILD_TYPE=Debug
11.  
    cmake -B "${BUILD_DIR}" \
12.  
        -DCMAKE_INSTALL_PREFIX="${INSTALL_DIR}" \
13.  
        -DCMAKE_BUILD_TYPE=${BUILD_TYPE} \
14.  
        -DCPACK_OUTPUT_FILE_PREFIX="${INSTALL_DIR}"
15.  
     
16.  
    # Build
17.  
    cmake --build "${BUILD_DIR}"
18.  
     
19.  
    cd "${BUILD_DIR}"
20.  
    # Test
21.  
    make test CTEST_OUTPUT_ON_FAILURE=TRUE GTEST_COLOR=TRUE
22.  
    # GTEST_COLOR=TRUE ctest --output-on-failure
23.  
     
24.  
    # Install
25.  
    # cmake --build . --target install
26.  
    # cmake --install . --prefix "../output" # After cmake 3.15
27.  
    make install
28.  
     
29.  
    # Package
30.  
    # cmake --build . --target package
31.  
    make package
32.  
     
33.  
    cd -

以上便是关于安装和打包的介绍，关于构建脚本开头set命令的几个参数，可参看往期这篇文章：

编写安全的shell脚本