cmake简明使用指南

why this manual？

必须用cmake
很多开源项目如KDE、VTK、OpenCV、Caffe等，都使用cmake来构建。要玩转这些项目，就需要掌握cmake。而且趋势是cmake会更加流行。

实际情况往往是，系统预装的opencv不够用，尝试编译opencv的时候遇到cmake各种问题，被折腾的死去活来，于是决定好好学一下cmake。

cmake资料不够好
cmake经历了多个版本发展，现在（2017.05.05）它的官方文档比原来有了很多进步。

现有的

小白视角
从一个cmake小白的角度来总结cmake的用法。

环境说明

cmake提供命令行方式，以及图形界面方式（包括cmake-GUI和ccmake)。这里仅使用cmake命令行方式，因为更简单直接。

使用ubuntu16.04, cmake3.5版。其他系统和cmake版本问题也都不大，因为本文尽量做到具备较好的通用性。

先确保安装了gcc，g++和cmake

hello world

最简单的cmake项目，不使用IDE（如CLion），也不考虑什么编码风格的，就是干，简单粗暴！

代码

编辑两个文件：main.cc和CMakeLists.txt。它们放在你的项目目录，比如~/work/hello-cmake

main.cc

#include <iostream>
using namespace std;

int main(){
    cout << "Hello World!" << endl;
    return 0;
}

CMakeLists.txt

cmake_minimum_required (VERSION 2.8)
project(hello-world)
add_executable(hello main.cc)

运行

开终端，运行这些命令：

cd ~/work/hello-cmake    #进入你的cmake项目目录
cmake .                  #执行cmake
make                     #执行make

windows下的做法

可以用Visual Studio来编译
假设C++代码和CMakeLists.txt文件内容相同。那么打开cmd执行如下命令，或者把如下命令保存到一个文件（例如build.bat）中再执行这个文件：

# 在源码相同目录下构建
cmake -G "Visual Studio 14"  #生成.sln文件
cmake --build .     #调用native build tool。在windows上，相当于是打开.sln然后手动点击构建。

或者在专门的文件夹里面编译：

#当然，把编译出来的东西单独放到一个目录也是OK的
mkdir build
cd build
cmake -G "Visual Studio 14" ..
cmake --build .
cd ..

以及，可以指定用Release模式，x64架构：

BUILD_DIR=build
rm -rf $BUILD_DIR
mkdir -p $BUILD_DIR
cd $BUILD_DIR

cmake \
    -G "Visual Studio 14 Win64" \
    ..

cmake --build . --config Release
# 在windows上，必须在build的时候指定编译类型，而不是cmake的阶段

或者用Unix的构建工具套件，这里使用的是tdmgcc64。安装之后把mingw32-make.exe复制一份为make.exe再执行

mkdir buildUnix
cd buildUnix
cmake -G "Unix Makefiles" ..
make
cd ..

必要的解释

cmake命令会在提供的路径（上例为"."）下，找到CMakeLists.txt并执行它。执行成功后生成makefile（或其他类似的，目前阶段就认为是makefile好了）；执行make，会根据makefile内容去执行。

至于cmake和make执行了哪些操作，需要了解cmake的语法，以及makefile的编写规则。有了cmake，其实可以忽略makefile，不妨认为makefile就是写给编译器gcc看的。

更便利的运行方式

通常cmake运行后产生若干文件，和源码目录混杂在一起并不是一个好的选择。通常新建一个build目录，在build目录执行cmake。

个人倾向于建一个脚本，每次用cmake构建时，参数比较多，用这个脚本比较方便：

compile.sh

#!/bin/bash

set -x   #把本行后的脚本执行内容，打印到屏幕。用于调试
set -e   #本行后，如果某行执行结果返回值不是true，那么终止

LOG="log.build"
touch $LOG
rm $LOG

exec &> >(tee -a "$LOG")   #将屏幕输出内容，同时写入log文件：便于后续查找

echo "Logging to $LOG"


BUILD_ROOT=build
if [ -d $BUILD_ROOT ]; then
    rm -rf $BUILD_ROOT
fi
mkdir -p $BUILD_ROOT
cd $BUILD_ROOT
echo "building root folder is $BUILD_ROOT"

echo "Now do cmake"

cmake ..

echo "Now do make"

make -j8

echo "Done"

执行构建脚本：

chmod +x compile.sh
./compile.sh
cd build
./hello

cmake使用原理

自顶向下看，cmake执行的是给定路径下的CMakeLists.txt，比如"."表示当前路径，".."表示当前目录的父目录。

CMakeLists.txt中指定项目的输入和输出：
输出：产生的可执行文件（或者库文件？）
输入：产生输出所依赖的源文件（以及库文件？）

CMakeLists.txt中通过cmake的语法编写相应代码语句，这些语句被cmake解释执行。进而产生makefile，用make去执行就完成编译。

cmake语法并不很复杂，往往翻看下cmake的官方手册就能知道某个变量、命令、标准的各种细节了。

cmake官方文档

遇到cmake指令看不懂，直接看文档，基本上解决问题。

在线文档

https://cmake.org/cmake/help/latest/

自行构建离线文档

实在是忍受不了查看文档时刷一个个网页一直出不来结果的情况。自己动手丰衣足食。如果你网络比较好，可以跳过这一节。

查看哪些apt包是cmake的文档：

aptitude search cmake

结果显示cmake-doc提供了文档，cmake-data则是另一种形式的文档。

安装cmake及其文档：

sudo apt install cmake cmake-doc cmake-data  #安装cmake文档
dpkg -L cmake-doc    #查看cmake-doc包安装位置

发现是在/usr/share/doc/cmake-data目录，它的马甲目录（链接）是/usr/share/doc/cmake-doc，那就开启来好了：

cd /usr/share/doc/cmake-data/html
python -m SimpleHTTPServer 4002    #用python开一个本地http服务器

浏览器访问http://localhost:4002查看文档。

“另一种形式的文档”呢？在/usr/share/cmake-3.5/Help目录，是.rst格式文档，要用sphinx编译：

sudo pip install sphinx   #先确保装了pip
cd /usr/share/cmake-3.5/Help
sudo sphinx-quickstart  #按照提示来，唯一需要注意的是autogen选择y。这一步生成makefile
cd _build
sudo make html   #编译生成html
cd html
python -m SimpleHTTPServer 4003

可以把上述开启文档的http服务器命令用tmux开启。

查询某个命令：http://10.10.10.53:4003/command/
查询某个变量：http://10.10.10.53:4003/variable/
查询某个手册：http://10.10.10.53:4003/manual/
查询某个模块：http://10.10.10.53:4003/module/
查询发行日志：http://10.10.10.53:4003/release/
查询 policy ：http://10.10.10.53:4003/policy/ 包含了各种cmake规范

find_package()的用法

先吐个槽

本来，直接查看手册中find_package()一节即可。

鉴于现有一些博客对于find_package()这条命令介绍不够好，比如这篇内容陈旧、不全面；比如这篇纯粹是官方文档翻译，而官方文档不够突出重点，所以再罗嗦一小节的内容。

平时用cmake，遇到问题最多就是这个find_package()命令的使用导致的。最常见于寻找opencv包的情况。

这里喷一下opencv：要想用opencv各种特性，就要自行把opencv_contrib编译进去。编译时候还会出现各种3rdparty的包从github上无法下载要手动解决的问题，不方便。

find_package()是如何工作的

find_package()：

先从CMAKE_MODULE_PATH变量表示的路径下去找Find<name>.cmake文件；

如果失败，则在CMAKE安装目录/share/cmake-x.y/Modules目录下查找Find<name>.cmake文件

如果上一步失败，则查找<Name>Config.cmake或者<lower-case-name>-config.cmake文件。按8大顺序查找你想要的包，如果前一个里面找到了就不去后面的找，还可以通过变量关闭某个查找顺序项

比如现在要找opencv的包。那么它的查找顺序是(都是在寻找<Name>Config.cmake或者<lower-case-name>-config.cmake)：

在CMAKE_PREFIX_PATH变量所表示的路径下寻找。
换言之，CMAKE_PREFIX_PATH有最高的查找优先级。
在find_package()参数列表中填写NO_CMAKE_PATH则跳过该查找项。
在cmake特有的环境变量中查找。包括：
```
<package>_DIR
CMAKE_PREFIX_PATH
CMAKE_FRAMEWORK_PATH
CMAKE_APPBUNDLE_PATH
```
对于OpenCV，就是OpenCV_DIR了。
在find_package()参数列表中填写NO_CMAKE_ENVIRONMENT_PATH跳过该查找项。
find_package()的HINTS参数指定
系统环境变量PATH里寻找。
在find_package()参数列表中填写NO_SYSTEM_ENVIRONMENT_PATH跳过该查找项。
搜索在CMake GUI中最新配置过的工程的构建树。在find_package()参数列表中填写NO_CMAKE_BUILDS_PATH跳过该查找项。
搜索存储在CMake用户包注册表中的路径。
在find_package()参数列表中填写NO_CMAKE_PACKAGE_REGISTRY或者设定CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY变量值为TRUE跳过该查找项。（似乎Linux下没啥用！）
搜索在当前系统的平台文件中定义的cmake变量:
```
CMAKE_SYSTEM_PREFIX_PATH
CMAKE_SYSTEM_FRAMEWORK_PATH
CMAKE_SYSTEM_APPBUNDLE_PATH
```
在find_package()参数列表中填写NO_CMAKE_SYSTEM_PATH选项跳过这些路径。
注意这里测试发现，CMAKE_SYSTEM_PREFIX_PATH是/usr/local;/usr;/;/usr;/usr/local，如果前面的查找顺序项都失败或者被关闭了，那么在这一查找项上，会在/usr/local这样的路径下，查找opencv开头的目录，比如/usr/local/opencv-git-master会被找到；而假如我把opencv的路径换成不以opencv开头，比如/usr/local/what-opencv则不能找到opencv。
find_package()参数列表中用PATHS指定搜索路径。这些路径一般是硬编码的参考路径。。。。（太长而且个人觉得没啥用，想看的去找手册好了）

写了这么多查找顺序，其实就记住一个好了，先设定定CMAKE_PREFIX_PATH变量，再用find_package()去找包，保证万事大吉：

list(APPEND CMAKE_PREFIX_PATH "/opt/opencv-git-master") #引号里是我的opencv安装路径
find_package(OpenCV)

成功查找到包后，产生这些变量吗？
按照cmake手册的说法，find_package()执行后会产生几个变量：

_FOUND
_INCLUDE_DIRS 或者 _INCLUDES
_LIBRARIES 或者 _LIBS
_DEFINITIONS


但尝试找opencv的包时，无论是apt装的opencv还是自行编译的opencv，都是一样：并非这几个变量都有值：

CMAKE_MODULE_PATH is:
-- Found OpenCV: /usr/local/opencv-git-master (found version "3.2.0")
OpenCV_FOUND is : 1
OpenCV_INCLUDE_DIRS is : /usr/local/opencv-git-master/include;/usr/local/opencv-git-master/include/opencv
OpenCV_INCLUDES is :
OpenCV_LIBRARIES is opencv_calib3d;opencv_core;opencv_features2d;opencv_flann;opencv_highgui;opencv_imgcodecs;opencv_imgproc;opencv_ml;opencv_objdetect;opencv_photo;opencv_shape;opencv_stitching;opencv_superres;opencv_video;opencv_videoio;opencv_videostab;opencv_aruco;opencv_bgsegm;opencv_bioinspired;opencv_ccalib;opencv_datasets;opencv_dnn;opencv_dnn_modern;opencv_dpm;opencv_face;opencv_freetype;opencv_fuzzy;opencv_hdf;opencv_line_descriptor;opencv_optflow;opencv_phase_unwrapping;opencv_plot;opencv_reg;opencv_rgbd;opencv_saliency;opencv_stereo;opencv_structured_light;opencv_surface_matching;opencv_text;opencv_tracking;opencv_xfeatures2d;opencv_ximgproc;opencv_xobjdetect;opencv_xphoto
OpenCV_LIBS is : opencv_calib3d;opencv_core;opencv_features2d;opencv_flann;opencv_highgui;opencv_imgcodecs;opencv_imgproc;opencv_ml;opencv_objdetect;opencv_photo;opencv_shape;opencv_stitching;opencv_superres;opencv_video;opencv_videoio;opencv_videostab;opencv_aruco;opencv_bgsegm;opencv_bioinspired;opencv_ccalib;opencv_datasets;opencv_dnn;opencv_dnn_modern;opencv_dpm;opencv_face;opencv_freetype;opencv_fuzzy;opencv_hdf;opencv_line_descriptor;opencv_optflow;opencv_phase_unwrapping;opencv_plot;opencv_reg;opencv_rgbd;opencv_saliency;opencv_stereo;opencv_structured_light;opencv_surface_matching;opencv_text;opencv_tracking;opencv_xfeatures2d;opencv_ximgproc;opencv_xobjdetect;opencv_xphoto
OpenCV_DEFINITIONS is :
```

引用第三方库

比如读取jpeg图像，并转化到Lab空间以及灰度图像。使用到opencv库，利用find_package()进行查找。代码如下：

main.cc

#include <iostream>
#include <opencv2/opencv.hpp>

using cv::Mat;
using cv::imread;
using cv::imshow;
using cv::waitKey;
using cv::cvtColor;
using cv::COLOR_BGR2Lab;
using cv::COLOR_BGR2GRAY;


int main(){
    // Load image
    Mat srcImage = imread("cat.jpg", -1);
    Mat dstImage;

    imshow("RGB Space", srcImage);

    // Convert to other color space
    cvtColor(srcImage, dstImage, COLOR_BGR2Lab);
    imshow("Lab Space", dstImage);

    cvtColor(srcImage, dstImage, COLOR_BGR2GRAY);
    imshow("Gray Scale", dstImage);

    waitKey();

    return 0;
}

CMakeLists.txt

cmake_minimum_required(VERSION 3.2)

project(hello-cmake)

list(APPEND CMAKE_PREFIX_PATH "/usr/share/OpenCV")  # apt装的opencv
#list(APPEND CMAKE_PREFIX_PATH "/usr/local/opencv-git-master")   #自行编译的opencv
message("CMAKE_MODULE_PATH is: ${CMAKE_MODULE_PATH}")
find_package(OpenCV
    #NO_CMAKE_PATH
    #NO_CMAKE_ENVIRONMENT_PATH
    #NO_SYSTEM_ENVIRONMENT_PATH
    #NO_CMAKE_PACKAGE_REGISTRY
    #NO_CMAKE_SYSTEM_PATH
    )
message("OpenCV_FOUND is : ${OpenCV_FOUND}")
message("OpenCV_INCLUDE_DIRS is : ${OpenCV_INCLUDE_DIRS}")
message("OpenCV_INCLUDES is : ${OpenCV_INCLUDES}")
message("OpenCV_LIBRARIES is ${OpenCV_LIBRARIES}")
message("OpenCV_LIBS is : ${OpenCV_LIBS}")
message("OpenCV_DEFINITIONS is : ${OpenCV_DEFINITIONS}")

add_executable(hello main.cc)

target_link_libraries(hello ${OpenCV_LIBS})

build.sh

#!/bin/bash

set -x
set -e

LOG="log.build"
touch $LOG
rm $LOG

exec &> >(tee -a "$LOG")

echo "Logging to $LOG"

BUILD_ROOT=build
if [ -d $BUILD_ROOT ]; then
    rm -rf $BUILD_ROOT
fi

mkdir -p $BUILD_ROOT
cd $BUILD_ROOT

echo "building root folder is $BUILD_ROOT"

echo "Now do cmake"
cmake ..

make -j8

echo "Done"

编写自己的库

利用add_library()生成库文件。

main.cc

#include <iostream>
using namespace std;

void smile(){
    cout << "Nice smile" << endl;
}

CMakeLists.txt

cmake_minimum_required(VERSION 3.2)

message("BUILD_SHARED_LIBS is ${BUILD_SHARED_LIBS}")
#set(BUILD_SHARED_LIBS ON)   # 设定BUILD_SHARED_LIBS来表示add_library构建共享库(shared)还是静态库(static)
message("BUILD_SHARED_LIBS is ${BUILD_SHARED_LIBS}")

add_library(smile STATIC main.cc)  #不过，add_library()显示地设定SHARED和STATIC，更直观

build.sh
其实每次我的build.sh都是一样的:)

#!/bin/bash

set -x
set -e

LOG="log.build"
touch $LOG
rm $LOG

exec &> >(tee -a "$LOG")

echo "Logging to $LOG"

BUILD_ROOT=build
if [ -d $BUILD_ROOT ]; then
    rm -rf $BUILD_ROOT
fi

mkdir -p $BUILD_ROOT
cd $BUILD_ROOT

echo "building root folder is $BUILD_ROOT"

echo "Now do cmake"
cmake ..

make -j8

echo "Done"

现在，自己的库写好了，怎么用呢？一种方法是make install，另一种方法是提供配置文件，比如mylibrary-config.cmake这种，后者需要配合.cmake.in文件进行生成，可以参考官方wiki:https://cmake.org/Wiki/CMake/Tutorials/How_to_create_a_ProjectConfig.cmake_file

cmake简明使用指南

cmake简明使用指南

why this manual？

环境说明

hello world

代码

运行

windows下的做法

必要的解释

更便利的运行方式

cmake使用原理

cmake官方文档

在线文档

自行构建离线文档

find_package()的用法

先吐个槽

find_package()是如何工作的

引用第三方库

编写自己的库

热门文章

最新文章

相关课程

相关电子书

相关实验场景