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()是如何工作的

引用第三方库

编写自己的库

热门文章

最新文章

相关电子书

热门

活动广场

任务中心

开发者评测

高校计划

乘风者计划

训练营

阿里云MVP

话题

直播

下载

镜像站

技术资料

插件

cmake简明使用指南

cmake简明使用指南

why this manual？

环境说明

hello world

代码

运行

windows下的做法

必要的解释

更便利的运行方式

cmake使用原理

cmake官方文档

在线文档

自行构建离线文档

find_package()的用法

先吐个槽

find_package()是如何工作的

引用第三方库

编写自己的库

热门文章

最新文章

相关电子书