CMake编译学习笔记

CMake编译概述

CMake学习资源

• CMake官方推荐教程：CMake Tutorial
• 知乎博客（偏向实践，以项目方式说明）：全网最细的CMake教程！(强烈建议收藏)
• 简书博文（博主对官方文档进行中文说明并配上相关例子）：Cmake

对于CMake推荐在项目使用中学习，通过查阅文档和实际测试每个指令的用处能有效的掌握CMake。

CMake编译

项目架构

CMake是一种常用的C++项目编译工具，通常一个完备的CMake项目包括了如下几部分：

• src：源代码文件夹
• include：头文件文件夹
• doc：项目文档文件夹
• build：编译文件夹
• devel：ROS1用于保存编译后程序的文件夹
• run.sh：项目启动脚本（ROS中无）
• CMakeList.txt：CMake文件，应在项目根目录和各级子文件夹内存在（例如ROS内就是在工作空间根目录和各个功能包根目录下存在）

对于一个C++项目，在编译完成后还可能需要使用make install将其安装至指定位置。

cmake指令

对于一个项目会构建一个build文件夹用于存放编译生成的中间文件，从而避免污染工作空间：

mkdir build & cd build			# 新建build目录并进入
cmake ..						# 构建MakeFile（build父目录）
make -j5						# 编译

cmake ..表示使用cmake构建当前文件夹build的父文件夹（项目根目录）。上述指令还可简化为使用参数--build：

mkdir build & cd build			# 新建build目录并进入
cmake --build ..				# 构建并编译（build父目录）

cmake指令的更多参数和使用可参考官方手册：cmake

CMakeList基础准则

CMakeList文件的编写主要遵从如下几条原则：

• ${变量名}被用于引用CMake变量，使用IF控制语句除外
• 指令参数被括弧括起，用空格分开：project(projectname [cxx])
• 指令是大小写无关的（官方推荐小写），参数、变量是大小写相关的
• 参数中包括空格，则应用双引号括起："fn nc.c"
• 使用#注释

CMakeList编写

项目构建

cmake_minimum_required() 和 project()

cmake_minimum_required用于指定所使用CMake的最低版本号，置于CMakeList.txt的开头；project指令则用于指定项目的名称，指令的用法如下：

cmake_minimum_required(VERSION <min>[...<policy_max>] [FATAL_ERROR])
project(<PROJECT-NAME> [<language-name>...])

• VERSION：关键字，表明后续添加为版本号
  -min： 设置所使用CMake的最低版本号，格式为major.minor[.patch[.tweak]]
  • policy_max：设置所使用的CMake的最高版本号，应高于min
• <PROJECT-NAME>：设置项目名称
• <language-name>：设置项目支持的语言，不加表示默认所有编程语言

使用示例如下所示：

cmake_minimum_required(VERSION 3.2.4)
project(Demo)

project指令同时隐式的定义了几个变量：

• <projectname>_BINARY_DIR：项目编译目录的绝对路径
• <projectname>_SOURCE_DIR：项目源目录的绝对路径
• PROJECT_BINARY_DIR：自动绑定<projectname>_BINARY_DIR的内容
• PROJECT_SOURCE_DIR：自动绑定<projectname>_SOURCE_DIR的内容

通常在调用上述CMake变量时，使用PROJECT_BINARY_DIR和PROJECT_SOURCE_DIR进行，从而避免CMake项目名称修改后需要额外修改其余内容。

更多内容可参考官方指导手册：cmake_minimum_required、project
以及博文Cmake命令之cmake_minimum_required介绍和Cmake命令之project介绍

set()

用于设置variable的值为 value，指令用法如下：

set(<variable> <value>... [PARENT_SCOPE])

• variable：被设置的参数
• value：设置的值

例如在CMake中指定使用的C++标准为C++ 14，则可定义变量${CMAKE_CXX_STANDARD}的值为14：

set(CMAKE_CXX_STANDARD 14)
set(CMAKE_CXX_STANDARD_REQUIRED True)

更多用法（环境变量、缓存变量、定义域等）可查看官方手册：set，以及博文Cmake命令之set介绍

find_package()

用于查找包（通常由项目外部的第三方库提供），并加载其包特定的详细信息。指令使用方式如下：

find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE][REQUIRED] [[COMPONENTS] [components...]][OPTIONAL_COMPONENTS components...][REGISTRY_VIEW  (64|32|64_32|32_64|HOST|TARGET|BOTH)][GLOBAL][NO_POLICY_SCOPE][BYPASS_PROVIDER])

• PackageName：需要查找的包名
• version：可指定查找包的版本要求
  • versionMin...versionMax：如1.1.1.1…1.2.2.1（包括1.2.2.1）
  • versionMin...[<]versionMax：如1.1.1.1…<1.2.2.1（不包括1.2.2.1）
• QUIET：禁止输出查找日志信息
• REQUIRED：当未找到满足条件的包时停止构建
• COMPONENTS：指定要查找的组件

例如如下即为常见的ROS查找catkin包相关组件：

find_package(catkin REQUIRED COMPONENTSgeometry_msgsmessage_generationnav_msgsroscpprospystd_msgstfvisualization_msgs
)

更多使用方法可以参考博文Cmake命令之find_package介绍
以及官方手册：find_package

add_executable()

用于从源码文件编译得到一个可执行文件，指令用法如下：

add_executable(<name> [WIN32] [MACOSX_BUNDLE][EXCLUDE_FROM_ALL][source1] [source2 ...])

• name：编译所得的可执行文件命名
• source：用于编译的源文件
• [EXCLUDE_FROM_ALL]：设置后，表明该可执行文件将被排除在all外，需要手动确定才能执行生成

通常仅指定构建的可执行文件名和使用的源码，如：

add_executable(Demo main.c)

更多用法参考博文Cmake命令之add_executable介绍
以及官方手册：add_executable

aux_source_directory()

当一个文件夹内存在多个源代码时，可使用该指令将其定义为一个变量，从而方便调用：

aux_source_directory(<dir> <variable>)

• dir：源代码路径
• variable：变量名

例如，下列示例将当前目录下所有源代码加入至DIR_SRCS，并用其编译生成可执行文件Demo

cmake_minimum_required (VERSION 2.8)
project (Demo2)aux_source_directory(. DIR_SRCS)
add_executable(Demo ${DIR_SRCS})

更多用法可参考官方手册：aux_source_directory

连接库文件

include_directories()和target_include_directories()

两者都用于将给定目录添加到编译器用于搜索包含文件的目录中，不同之处在于include_directories将对整个CMakeList内每个目标添加搜索路径，而target_include_directories则仅针对指定目标添加搜索路径，两者用法如下：

include_directories([AFTER|BEFORE] [SYSTEM] dir1 [dir2 ...])target_include_directories(<target> [SYSTEM] [AFTER|BEFORE]<INTERFACE|PUBLIC|PRIVATE> [items1...][<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])

• <target>：target_include_directories中的指定目标
• [AFTER|BEFORE]：可显式指定添加头文件搜索路径的位置
  • 在原有搜索路径的最后（AFTER）
  • 在原有搜索路径的最前（BEFORE）
• dir：include_directories中添加的搜索路径，相对路径将被解释为基于当前源目录开始
• <INTERFACE|PUBLIC|PRIVATE>
  • INTERFACE ：仅target的头文件可使用该路径
  • PUBLIC：target的头文件和源文件均可以使用
  • PRIVATE：target对应的源文件可以使用
• items：target_include_directories中添加的搜索路径，相对路径将被解释为基于当前源目录开始

此处可参考博文CMake 添加头文件搜索路径 include_directories, target_include_directories
以及官方手册：include_directories、target_include_directories

add_library()

用于从源码文件编译得到一个库文件，指令用法如下：

add_library(<name> [STATIC | SHARED | MODULE][EXCLUDE_FROM_ALL][<source>...])

• <name>：构建的库文件的名称，最终生成的库文件名字将根据本机惯例进行产生，如：lib<name>.lib或<name>.a
• [STATIC | SHARED | MODULE]：构建库文件的类型
  • STATIC：静态库文件
  • SHARED：动态库文件
  • MODULE：模块库文件
• source：用于编译的源文件
• [EXCLUDE_FROM_ALL]：设置后，表明该库将被排除在all外，需要手动确定才能执行生成
• 生成的库文件相关CMake参数以INTERFACE_开头

生成的库文件将被输出至${ARCHIVE_OUTPUT_DIRECTORY}、${LIBRARY_OUTPUT_DIRECTORY}和${RUNTIME_OUTPUT_DIRECTORY}中：

• ARCHIVE_OUTPUT_DIRECTORY：静态库文件存储位置
• LIBRARY_OUTPUT_DIRECTORY：Lib文件存储位置
• RUNTIME_OUTPUT_DIRECTORY：动态库文件存储位置

若需要导入一个已经生成的库文件还可以使用如下方式：

add_library(<name> [STATIC | SHARED | MODULE] IMPORTED [GLOBAL])

• IMPORTED关键字用于说明该库文件已生成无需编译
• GLOBAL：设置后表明该库文件全局可见
• 使用此方法生成的库文件相关CMake参数以IMPORTED_开头

更多用法可以参考博文：cmake : add_library详解或者官方手册：add_library

add_subdirectory()

用于添加需要被构建的子目录，指令用法如下：

add_subdirectory(source_dir [binary_dir] [EXCLUDE_FROM_ALL] [SYSTEM])

• source_dir：指定子目录，其内应包含CMakeList.txt文件、源码文件
• binary_dir：指定输出可执行文件位置

例如项目内包含子文件夹src，其内包括CMakeList.txt和相关源码。则在项目根目录CMakeList.txt中添加如下指令使其被构建：

add_subdirectory(src)

更多用法可以参考博文Cmake命令之add_subdirectory介绍以及官方手册：add_subdirectory

target_link_libraries()

用于连接可执行文件和对应的库文件：

target_link_libraries(<target> ... <item>... ...)

• target：被连接的可执行文件
• item：库文件名称、路径等

例如，可执行文件main连接生成的库文件B：

add_executable(main main.c)
add_library(B SHARED b.c)
target_link_libraries(main B)

更多使用方式可参考官方手册：target_link_libraries

target_link_directories()

用于连接可执行文件和用于查找依赖库文件的路径，指令用法如下：

target_link_directories(<target> [BEFORE]<INTERFACE|PUBLIC|PRIVATE> [items1...][<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])

更多使用方式可参考官方手册：target_link_directories

安装与日志

在CMake中安装使用install指令实现，针对不同的文件类型，该指令具备不同的使用方式，可参考官方手册查看详细内容：install

install target

install(TARGETS targets... [EXPORT <export-name>][RUNTIME_DEPENDENCIES args...|RUNTIME_DEPENDENCY_SET <set-name>][[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE|PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE|FILE_SET <set-name>|CXX_MODULES_BMI][DESTINATION <dir>][PERMISSIONS permissions...][CONFIGURATIONS [Debug|Release|...]][COMPONENT <component>][NAMELINK_COMPONENT <component>][OPTIONAL] [EXCLUDE_FROM_ALL][NAMELINK_ONLY|NAMELINK_SKIP]] [...][INCLUDES DESTINATION [<dir> ...]])

• TARGETS：关键字，表明安装的对象为Target
• targets：指定目标文件名
• [ARCHIVE|LIBRARY|RUNTIME……]：指定文件类型
  • ARCHIVE：静态库
  • LIBRARY：动态库
  • RUNTIME：可执行目标二进制文件
• [DESTINATION <dir>]：指定安装路径
  • 若路径<dir>为绝对路径，以"/"开头
  • 若路径<dir>为相对路径，则实际安装路径为：${CMAKE_INSTALL_PREFIX}<dir>
• [PERMISSIONS permissions...] ：用户权限，最高777（参考liunx权限）
  • OWNER_WRITE ：拥有者写入权限
  • OWNER_READ ：拥有者读取权限
  • OWNER_EXECUTE ：组成员执行权限
  • GROUP_WRITE ：组成员写入权限
  • GROUP_READ ：组成员读取权限
  • GROUP_EXECUTE ：组成员执行权限
  • WORLD_WRITE ：其他人写入权限
  • WORLD_READ ：其他人读取权限
  • WORLD_EXECUTE ：其他人执行权限

例如，如下使用方式：

install(TARGETS myExe mySharedLib myStaticLibRUNTIME DESTINATION binLIBRARY DESTINATION libARCHIVE DESTINATION lib/static)
install(TARGETS mySharedLib DESTINATION /some/full/path)

上述例子实现如下目标：

• 二进制文件（RUNTIME）myExe安装至${CMAKE_INSTALL_PREFIX}/bin 下
• 动态库文件（LIBRARY）mySharedLib安装至${CMAKE_INSTALL_PREFIX}/lib和/some/full/path下
• 静态库文件（ARCHIVE）myStaticLib安装至${CMAKE_INSTALL_PREFIX}/lib/static下

install Files和install programs

install(<FILES|PROGRAMS> files...TYPE <type> | DESTINATION <dir>[PERMISSIONS permissions...][CONFIGURATIONS [Debug|Release|...]][COMPONENT <component>][RENAME <name>] [OPTIONAL] [EXCLUDE_FROM_ALL])

• <FILES|PROGRAMS>：关键字，表明安装的对象类型为FILES或PROGRAMS，应选择其一填写
  • FILES：权限为拥有者读写、组成员读、其余人读（644）
  • PROGRAMS：权限为拥有者读写执行、组成员读执行、其余人读执行（755）
• files…：指定文件名称
• TYPE：关键字，表明文件的类型
• [DESTINATION <dir>]：指定安装路径

文件类型可选如下所示：

install Directories

install(DIRECTORY dirs...TYPE <type> | DESTINATION <dir>[FILE_PERMISSIONS permissions...][DIRECTORY_PERMISSIONS permissions...][USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER][CONFIGURATIONS [Debug|Release|...]][COMPONENT <component>] [EXCLUDE_FROM_ALL][FILES_MATCHING][[PATTERN <pattern> | REGEX <regex>][EXCLUDE] [PERMISSIONS permissions...]] [...])

• [FILE_PERMISSIONS permissions...]：目录内文件权限
• [DIRECTORY_PERMISSIONS permissions...]：目录本身权限
• [USE_SOURCE_PERMISSIONS]：若未指定FILE_PERMISSIONS permissions...，则根据源文件权限赋予
• [PATTERN <pattern>：采用模式匹配进行筛选内容 <pattern>
• REGEX <regex>：采用正则匹配进行筛选内容<regex>
• [EXCLUDE]：安装时，排除筛选得到的文件
• [PERMISSIONS permissions...]：指定筛选得到的文件的权限

例如使用该命令执行如下：

INSTALL(DIRECTORY icons scripts/ DESTINATION share/myprojPATTERN "CVS" EXCLUDEPATTERN "scripts/*" PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ GROUP_EXECUTE GROUP_READ WORLD_EXECUTE)

上述指令执行如下操作：

• 将目录icons安装至${CMAKE_INSTALL_PREFIX}/share/myproj
• 将目录scripts/ 中的内容安装${CMAKE_INSTALL_PREFIX}/share/myproj
• 在进行安装时，排除名字包含CVS 的文件
• 在进行安装时，将scripts/* 文件的权限指定为731

message()

用于向终端中输出用户定义的编译日志信息，指令用法如下：

message([<mode>] "message text" ...)

• mode：日志类型
  • FATAL_ERROR：红色CMake Error，将终止CMake编译
  • SEND_ERROR：CMake Error，将跳过生成但不影响编译
  • WARNING：黄色CMake Warning，不影响CMake编译
  • AUTHOR_WARNING：CMake Warning (dev)，不影响CMake编译
  • STATUS：输出一些编译过程中的简明信息
  • VERBOSE：输出一些编译过程中的详细信息
• message text：输出的日志内容

更多使用方式可参考官方手册：message