CMake Notes

1. cmake_minimum_required

   • 版本限制

2. project

   • project("Project information")
   • 项目信息

3. add_executable

   • 生成目标，可执行文件

同单文件没什么区别

1
2
3
4
5
6

# CMake 最低版本号要求
cmake_minimum_required (VERSION 2.8)
# 项目信息
project (Demo2)
# 指定生成目标
add_executable(Demo main.cc MathFunctions.cc)

1. aux_source_directory(. path_var_name)

   • 给路径设置一个名称

2. add_library(lib_name ${lib_path_var_name})

   • 生成链接库名称

3. target_link_libraries(executable_file lib_name)

   • 把链接库，添加到可执行文件 target（建立对应关系）

4. 其它，命令

   • add_subdirectory
   • cmake_minimum_required(VERSION 2.8)
   • project

1

cmake .. -DDLIBCLANG_LIBRARY="C:\Program Files\LLVM\bin\libclang.dll" -DCXX_COMPILER="C:\Program Files\LLVM\bin\clang++.exe"

来源： https://legends2k.github.io/note/install-irony-win32/

目的：编译 irony-server, rtags on windows.

把 include_directory 添加到特定的 your_lib 和 your_excutable

1
2
3
4

target_include_directories(mylib PUBLIC
  $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib>
  $<INSTALL_INTERFACE:include/mylib>  # <prefix>/include/mylib
)

• normal 正常类型

  • STATIC

    • 静态链接库

      • .a 或 .lib 文件

  • SHARED

    • 动态链接库

      • .so 或 .dll 文件

  • MODULE

    • 不导出 symbol 的库，一般通过 dlopen 打开

• OBJECT

  • non-archieval collection of object files, 收集 obj 文件，作为中间变量

  • 参考：

    • cmake-buildsystem(7) — CMake 3.24.1 Documentation

特点：

• 默认添加的是静态库(STATIC)

  • 修改默认行为的方法： set(BUILD_SHARED_LIBS ON)
  • 修改变量 BUILD_SHARED_LIBS

1
2
3
4
5

  cmake --help-module FindPythonLibs
  cmake --help-module-list          # 列出所有的Module.
  cmake --help-command find_package
  cmake --help-command include_directories
  cmake --help-command target_link_libraries

通过 cmake –help-module FindPythonLibs 查找 Module 的帮助文档，可以查看这个 Module 定义的变量的 “真实名称”

• 注意

  • 这个真实名称很重要，大小写，版本号等，很容易错误（网上的人，也很多写的是错误的。）

CMAKE_SYSTEM_NAME ==> Linux-4.15.0-29deepin-generic CMAKE_SYSTEM ==> Linux

• 相比 Win32, Unix, APPLE (存储的是 trule, false)更据跨平台特性

参考：

• 全面的教程

  • https://dominoc925.blogspot.com/2016/08/use-cmake-to-help-build-and-use-windows.html

• 中文简略说明

  • https://blog.csdn.net/LaineGates/article/details/83899961

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

  #output library export file *.lib and
  #output macro definitions include file
  include (GenerateExportHeader)
  add_library(animallib SHARED ${SOURCES})
  GENERATE_EXPORT_HEADER (animallib
      BASE_NAME animallib
      EXPORT_MACRO_NAME animallib_EXPORT
      EXPORT_FILE_NAME animallib_Export.h
      STATIC_DEFINE animallib_BUILT_AS_STATIC
  )

  GENERATE_EXPORT_HEADER( myDLL  # dll文件名
    EXPORT_MACRO_NAME MYDLLExports  # export 宏
    EXPORT_FILE_NAME ${CMAKE_BINARY_DIR}/include/myDLLExports.h  #宏的保存文件
    ）

• 在 dll 的代码中

  1 2 3 4

  #include "myDLLExports.h" class MYDLLExports A { // definition }

Walkthrough: Create and use your own Dynamic Link Library (C++) | Microsoft Docs

Using dllimport and dllexport in C++ Classes | Microsoft Docs

CMAKE_PREFIX_PATH — CMake 3.24.0-rc3 Documentation

• 一个通过分号“;”分割的路径 path 列表， eg: "/usr;/usr/local"
• 用来指定安装库，软件等位置，用于用户需要查找的东西
• 作用工具：find_package, find_program, find_library, find_file, find_path 等

• 如何被使用的

  • 当 find_library 等命令调用 CMAKE_PREFIX_PATH 时， 会搜索其目录下的 bin，include，lib 等目录

• 设定者：project 使用它

  • 我的理解：

    • 应当是用户在写一个“项目”时，定义它
• 默认值：为空

CMAKE_LIBRARY_PATH — CMake 3.24.0-rc3 Documentation

• 用途：find_library
• 分号“；”分割的路径 path 列表，
• 设定者：project
• 默认值：为空

CMAKE_FRAMEWORK_PATH — CMake 3.24.0-rc3 Documentation

• 用途：find_library, find_package, find_path, find_file
• 平台：macOS
• 分号“；”分割的路径 path 列表

• 当前 CMakeLists.txt 文件所在目录

  • This the full path to the source directory that is currently being processed by cmake.

参考：

• cmake - Difference between CMAKE_CURRENT_SOURCE_DIR and CMAKE_CURRENT_LIST_DI…

辨析：

1. 当 CMakeLists.txt 自身生效时，两者是同一个文件

2. 当 module_name.cmake 文件被其他文件（一个 CMakeLists.txt）通过 include(module_path/module_name.cmake) 命令调用时

   • CMAKE_CURRENT_LIST_DIR 指的是： module.name.cmake 文件所在目录 project_root/module_path/
   • CMAKE_CURRENT_SOURCE_DIR 指的是：发起调用方（CMakeLists.txt）所在目录 project_root
   • 注意： listfile 可以是 module.cmake 文件，也可以是另一个 CMakeLists.txt 文件

3. CMAKE_CURRENT_LIST_DIR 有动态作用域

   • 永远是正在处理的 listfile 所在文件目录
   • 处理 include 命令前，是发起调用方所在目录
   • 处理 include 命令过程中，是被调用文件所在目录
   • 处理 include 命令后，又变成调用方所在目录

辨析：

1. CMAKE_SOURCE_DIR: 项目根目录所存在的 CMakeLists.txt 文件所在目录

   • 需要有 project() 命令
   • 这里的项目根目录是 cmake 项目的根目录
2. PROJECT_SOURCE_DIR: 最近的 有 project() 命令的 CMakeLists.txt 文件所在目录

3. CMAKE_CURRENT_SOURCE_DIR: 当前 CMakeLists.txt 文件所在文件目录

   • 不一定有 project() 命令

4. CMAKE_CURRENT_LIST_DIR: cmake 代码所在文件，不一定是 CMakeLists.txt 文件

   • 不一定有 project() 命令

find_library — CMake 3.24.0-rc3 Documentation

下面的内容由 NO_DEFAULT_PATH 反推

• target 类似对象

• 与 target 有关的函数 是 对应的方法

  • target_link_libraries
  • target_include_directories

  • target_compile_features

    • 编译特征– 指定 compiler 必须具有的特征

      1	arget_compile_features(mylib PUBLIC cxx_constexpr)

  • target_compile_options

    1	target_compile_options(MyTarget PRIVATE "$<$<CONFIG:Debug>:--my-flag>")

    • 注：如果 BUILD_TYPE 是 Debug, 添加 –my-flag 选项参数
  • target_compile_definitions

  • set_target_property – cmake 提供属性

    1 2	set_property(TARGET TargetName PROPERTY CXX_STANDARD 11) set_target_properties(TargetName PROPERTIES CXX_STANDARD 11)

  • get_target_property

    1	get_property(ResultVariable TARGET TargetName PROPERTY CXX_STANDARD)

参考：

• CMAKE 里PRIVATE、PUBLIC、INTERFACE属性示例详解_无人等人的博客-CSDN博客_cmake private

说明：

• 清楚的解释

  • PRIVATE

    • header file 不包含 依赖库内容（即库的头文件，以下类推）
    • source file 包含 依赖库内容

  • INTERFACE

    • header file 包含 依赖库内容
    • source file 不包含 依赖库内容

  • PUBLIC

    • header file 包含 依赖库内容
    • source file 包含 依赖库内容

• PRIVATE

  • 仅仅 target 需要

• INTERFACE

  • 使用 target 时需要

• PUBLIC

  • 当前 target 需要
  • 使用 target 时也需要

• 例子 A:

  1 2 3 4

  add_library(another STATIC another.cpp another.h) target_link_libraries(another PUBLIC one) target_include_directories(one PUBLIC include)

参考：

• How to Structure Your Project · Modern CMake

类型：

regular

不会被缓存的变量

cache

会被缓存的变量

1
2

message("Regular variable (before): ${abc}")
message("Cache variable (before): ${xyz}")

注释：

缓存

即，被存储到 CMakeCache.txt 文件中

异同：

1. -D 设置

   • regular 不能被设置
   • cache 可以被设置

2. 覆盖

   • regular 会被 cache 覆盖

3. 缓存数据的影响

   • cache 变量，第一次执行 cmake 命令时缓存到文件中

   • 第二次直接读取缓存数据

     • 即使修改 CMakeLists.txt 文件也无效
     • 只能通过 cmake -D 覆盖修改

4. 作用域

   • regular 有作用域
   • cache 是全局作用域，没有局部作用域

5. 生效时间

   • CACHE set 语句只有第一次生效，后续会被跳过

   • 无 CACHE set 语句，总是被执行

     1 2 3 4 5 6 7

     cmake_minimum_required(VERSION 2.8) project(foo NONE) set(A "123") # 每次执行 cmake 命令时，都会被执行 set(A "456" CACHE STRING "") # 只有第一次执行 cmake 命令时，会被执行 message("A: ${A}")

分类

1. CMakeLists.txt 文件

   • 通过 add_subdirectory 被执行

2. *.cmake Module 文件

   • 通过 cmake -P 命令行被执行
   • 通过 include 命令被执行

1. RPATH

   • 一个路径.so 文件存放列表
   • 被 linked into 可执行文件
   • 如果 RUNPATH 存在会被忽略
   • 大部份 unix 支持它
   • 一般它的优先级高于 LD_LIBRARY_PATH

   • 添加方法：

     1. ld 命令： ld -rpath=/given/path

        • 注意 ld -rpath-link=dir 只有链接时起作用，运行时无效， -rpath 在 runtime 运行时也有效

     2. gcc 命令： gcc -Wl,rpath,dir

        • 参考：gcc - I don't understand -Wl,-rpath -Wl, - Stack Overflow
        • gcc 通过 -Wl,option_name 把 link 选项传递给 linker(这里是 ld 命令)

2. LD_LIBRARY_PATH

   • 环境变量

     • 用户自行配置

3. RUNPATH

   • 类似 RPATH, 但是搜索优先级在 LD_LIBRARY_PATH 之后
   • 注意：只有新版 unix 支持

4. /etc/ld.so.conf

   • ld.so 库的配置文件，额外的动态库存放目录

5. builtin 内建目录

   • eg: /lib, /usr/lib

参考：

• RPATH handling · Wiki · CMake / Community · GitLab

1. macos 中 RPATH 的搜索有限级的 DYLD_LIBRARY_PATH 之后
2. RPATH 通过 @loader_path 和 @executable_path 来定义

cmake 中 rpath 有两种使用场景：

1. build tree 编译位置

   • cmake 编译 target 产生的位置，运行 target 时，rpath 指向 build tree 中设置的动态库路径

2. install location 安装位置

   • 安装后，动态库的路径改变了，因此 rpath 也要改变

3. 注意：

   • 安装时 rpath 的 cmake 自动修改是通过 install() 命令触发的，因此手动复制 target, 不会触发 rpath 改变

与 rpath 相关的 cmake 变量 (在顶层 CMakeLists.txt 中设置）：

• CMAKE_INSTALL_RPATH

  • 安装后的 rpath 设置（这里我把它归类到，安装时 rpath）
  • 默认为空： ""

  • 关于 $ORIGIN 的处理：

    • 参考：CMP0095 — CMake 3.24.1 Documentation

    • 在 v3.15 及以前需要转义： set(CMAKE_INSTALL_RPATH "\\\${ORIGIN}/../lib")

      • 为什么需要转义：因为在 ld.so 中就是 ${ORIGIN} 或 $ORIGIN, cmake 中变量也是这种写法， 不做转义处理，cmake 会把 ${ORIGIN} 转换为空串 ""

    • 在 v3.16 及以后不需要转义： set(CMAKE_INSTALL_RPATH "${ORIGIN}/../lib")

      • 这是因为，cmake 添加了针对这种情况的特殊处理
    • 在 v3.24.1 及以后通过 cmake_policy(set CMP0095 NEW) 来支持新型写法（默认使用旧式写法）

• CMAKE_BUILD_RPATH

  • build tree 中 target 使用的运行时 rpath, 编译时rpath,(v3.8 新特性)
  • 注意：它在 install location 不起作用（无效）

• CMAKE_BUILD_RPATH_USE_ORIGIN

  • 是否允许 build tree 中 target 的 rpath 使用 ${ORIGIN}, (v3.14 新特性)

    • cmake 传统上，build tree rpath 使用的是绝对路径
  • 默认不支持：FALSE
  • 好处：允许把编译的代码直接移动的别的地方
  • 注意：它不影响 BUILD_RPATH 设置内容

• CMAKE_SKIP_BUILD_RPATH

  • 是否跳过 编译时 rpath
  • 默认：不跳过，即添加编译时 rpath, FALSE

• CMAKE_BUILD_WITH_INSTALL_RPATH

  • 是否把 install location rpath 安装时 rpath 编译进去
  • 默认：不把 安装时 rpath 编译进去，即 FALSE

• CMAKE_INSTALL_RPATH_USE_LINK_PATH

  • 安装时 rpath, 是否使用搜索到的 rpath：
  • 默认：不使用自动搜索到的 rpath, FALSE
• 注意：上面的选项默认值都是 否 ("" 或 FALSE)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# use, i.e. don't skip the full RPATH for the build tree
set(CMAKE_SKIP_BUILD_RPATH FALSE) # 跳过编译时 rpath

# when building, don't use the install RPATH already
# (but later on when installing)
set(CMAKE_BUILD_WITH_INSTALL_RPATH FALSE) # 不使用安装 rpath

# the RPATH to be used when installing
set(CMAKE_INSTALL_RPATH "")     # 不设置安装时 rpath 具体路径

# don't add the automatically determined parts of the RPATH
# which point to directories outside the build tree to the install RPATH
set(CMAKE_INSTALL_RPATH_USE_LINK_PATH FALSE) # 不使用自动搜索到的 rpath

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

# use, i.e. don't skip the full RPATH for the build tree
set(CMAKE_SKIP_BUILD_RPATH FALSE) # 不使用编译时 rpath

# when building, don't use the install RPATH already
# (but later on when installing)
set(CMAKE_BUILD_WITH_INSTALL_RPATH FALSE) # 不把 安装时 rpath 编译进target, 而是在安装过程中修改

set(CMAKE_INSTALL_RPATH "${CMAKE_INSTALL_PREFIX}/lib") #设定安装时 rpath

# add the automatically determined parts of the RPATH
# which point to directories outside the build tree to the install RPATH
set(CMAKE_INSTALL_RPATH_USE_LINK_PATH TRUE) # 安装时 rpath, 使用自动搜索到的 rpath

# the RPATH to be used when installing, but only if it's not a system directory
list(FIND CMAKE_PLATFORM_IMPLICIT_LINK_DIRECTORIES "${CMAKE_INSTALL_PREFIX}/lib" isSystemDir)
if("${isSystemDir}" STREQUAL "-1")
    set(CMAKE_INSTALL_RPATH "${CMAKE_INSTALL_PREFIX}/lib")
endif("${isSystemDir}" STREQUAL "-1")

参考：

• c++ - Cmake on Windows doesn't add shared library paths (works on linux) - St…

宗旨：

1. Windows 中不存在 rpath
2. Windows 会在 executable 所在位置寻找 .dll 文件

1. conan 默认设置跳过 rpath 设置：

   • conan_basic_setup() 会设置 set(CMAKE_SKIP_RPATH 1) (在 macos 中)

2. 跳过 conan 默认 rpath 设置方法：

   • conan_basic_setup(KEEP_RPATHS)

3. 设置 conan 支持 rpath 方法：

   1. 配置 conan_basic_setup

      1 2	include(${CMAKE_BINARY_DIR}/conanbuildinfo.cmake) conan_basic_setup(KEEP_RPATHS)

   2. 配置 cmake 的 rpath 设置

      1 2 3 4 5 6 7

      if (APPLE) set(CMAKE_INSTALL_RPATH "@executable_path/../lib") else() set(CMAKE_INSTALL_RPATH "$ORIGIN/../lib") endif() set(CMAKE_BUILD_WITH_INSTALL_RPATH ON)

      • 解释： 把 install location 的 rpath 编译进 target
      • 目的： 让 target 知道在哪里找 .dll 或 .so 文件

   3. 设置 conanfile.txt, 处理 .so 或 .dll 方法

      1 2 3 4 5 6 7

      [requires] poco/1.9.4 [imports] bin, *.dll -> ./bin # Copies all dll files from packages bin folder to my "bin" folder lib, *.dylib* -> ./lib # Copies all dylib files from packages lib folder to my "lib" folder lib, *.so* -> ./lib # Copies all so files from packages lib folder to my "lib" folder

      • 解释： 把 .so 文件复制到 ./lib 文件夹下，一般是 build/lib

4. 总结：

   • conan 不能自动让 target 知道 shared library 在哪里
   • conan 只能把对应的.so 或 .dll 文件复制到给定的目标位置
   • 用户需要 hard code 硬编码，指定出安装的目标位置（rpath）

1. 用来添加预处理器指令
2. 指令可以有值，也可以没有
3. 添加的 -D 定义前缀会被 cmake 自身忽略

4. eg:

   1 2 3 4 5 6 7 8

   # * 下面的四种方法效果等价 target_compile_definitions(foo PUBLIC FOO) # --> #define FOO target_compile_definitions(foo PUBLIC -DFOO) # -D removed target_compile_definitions(foo PUBLIC "" FOO) # "" ignored target_compile_definitions(foo PUBLIC -D FOO) # -D becomes "", then ignored # * 添加 define 的值 target_compile_definitions(foo PUBLIC FOO=1) # --> #define FOO 1

1. 定义的是传递给编译器（eg: gcc）的命令选项

2. eg:

   1	target_compile_options(my_target PUBLIC -Wall -Wextra -pedantic -Werror)

参考：

• cmake-buildsystem(7) — CMake 3.24.2 Documentation

作用：

• 通过有 INTERFACE_ 开头的属性，向 consumer 传递相应属性

• eg:

  • my_lib 有 INTERFACE_POSITION_INDEPENDENT_CODE 属性
  • my_exe 通过 add_executable(my_exe PUBLIC my_lib) 语句继承了 my_lib
  • 这样，my_exe 就会获得 POSITION_INDEPENDENT_CODE 属性，（通过 my_lib 传递过来的）

1
2
3
4
5
6
7
8

set(CMAKE_DEBUG_TARGET_PROPERTIES
  INCLUDE_DIRECTORIES
  COMPILE_DEFINITIONS
  POSITION_INDEPENDENT_CODE
  CONTAINER_SIZE_REQUIRED
  LIB_VERSION
)
add_executable(exe1 exe1.cpp)

1. install(TARGETS ...)

   • 通过 add_library() 或 add_executable() 创建的 target

2. install(FILES ...)

   • 头文件，或任意文件
   • 用来安装通用文件

3. install(PROGRAMS ...)

   • 任意可执行文件

     • 注意：这里不是 target, 是实实在在的本地文件

   • 与 install(FILES …) 接口的区别：

     • 它会设置文件的可执行属性
   • 例如：shell 脚本，非 cmake 项目编译生成的可执行文件等

4. install(DIRECTORIES ...)

   • 文件夹的安装
   • 用来安装资源文件
   • 例如：包含图片的文件夹，数据文件夹

5. install(SCRIPT ...)

   • 安装过程中执行的 cmake 脚本程序

   • 指定要执行的 .cmake 文件

     • eg: install(SCRIPT message.cmake)

6. install(CODE ...)

   • cmake 脚本程序

   • 指定要执行的 cmake 代码，通过字符串指定

     • eg: install(CODE "MESSAGE(\"Installing My Project\")")

7. install(EXPORT ...)

   • 安装 cmake 脚本程序，（从安装目录到到外部项目）

• DESTINATION

  • 安装位置

    • 绝对路径：就是指定的安装位置
    • 相对路径：相对与 CMAKE_INSTALL_PREFIX

• PERMISSIONS

  • 安装文件权限

    • 用来覆盖默认权限
    • 注意：不同安装命令有默认权限

  • 可选值

    • OWNER_READ, OWNER_WRITE, OWNER_EXECUTE, GROUP_READ, GROUP_WRITE, GROUP_EXECUTE, WORLD_READ, WORLD_WRITE, WORLD_EXECUTE, SETUID, and SETGID.

• CONFIGURATIONS

  • 安装配置

    • 举例：Release, Debug
    • 用来指定安装规则 install rule 使用范围
    • 例如 Release 配置只能用来在 CMAKE_BUILD_TYPE 是 release 类型时起作用

• COMPONENT

  • 安装规则分类（组件）

    • 举例：

      • Runtime: 运行需要的组件

        • 注意：一个组件，可以是多个文件
      • Development: 编译组件
      • Document: man page 和 help files 等文档相关文件
  • 作用：通过把 install rule 拆分成多个 component 组件，可以一次只安装部分组件或单个组件

  • 注意：

    • 组件名称不是 cmake 指定的，由项目（用户）自己指定

• OPTIONAL

  • 可选规则

    • 类似 python None, 用来处理 target 或文件不存在文件
    • 不存在，也可以不报错

1
2
3
4
5
6
7

install(DIRECTORY data/icons DESTINATION share/myproject
        PATTERN ".git" EXCLUDE
        PATTERN "*.txt" EXCLUDE)

install(DIRECTORY data/icons DESTINATION share/myproject
        REGEX "/.git$" EXCLUDE
        REGEX "/[^/]*.txt$" EXCLUDE)

匹配工具

1. PATTERN

   • 通配符匹配

2. REGEX

   • 正则匹配

排除工具：

1. EXCLUDE

   • 用来反向匹配，排除不需要的文件名

参考 cmake install 官方： Installing Files — Mastering CMake

1. make 命令法

   1 2 3

   make package make package_source

2. cpack 命令法

   1 2 3 4 5

   cd <build_directory> cpack --config CPackConfig.cmake # 打包二进制可执行程序 cpack --config CPackSourceConfig.cmake # 源码打包

3. cmake –target 命令法

   1 2 3

   cmake --build <build_directory> --target package # 打包二进制可执行程序 cmake --build <build_directory> --target package_source # 源码打包

参考：

• Packaging With CPack — Mastering CMake