cmake简明使用指南
Last update 2018/8/8
先执行cmake生成makefile，然后看看里面的内容，（至少在ubuntu16.04上的cmake3.5.1上），有如下内容提供：
# Help Target
help:
@echo "The following are some of the valid targets for this Makefile:"
@echo "... all (the default if no target is provided)"
@echo "... clean"
@echo "... depend"
@echo "... edit_cache"
@echo "... rebuild_cache"
@echo "... net_demo"
@echo "... src/net_demo.o"
@echo "... src/net_demo.i"
@echo "... src/net_demo.s"
.PHONY : help
其中net_demo是我自己的build target，可以忽略。可以看到，提供了edit_cache选项，则通过make edit_cache可以交互式的修改一些变量，挺好的。
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用户包注册表(User Package Registry)中的路径。
在find_package()参数列表中填写NO_CMAKE_PACKAGE_REGISTRY或者设定CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY变量值为TRUE跳过该查找项。（似乎Linux下没啥用！）
（update@2018-07-31 00:47:33 今天被这个User Package Registry坑惨了！具体实例和解决方法看SO上的一个问答：how-to-avoid-cmake-to-read-in-its-system-cache-home-cmake。简单说，Caffe的cmake脚本中有一句export Caffe，这会向User Package Registry写东西，在ubuntu下的表现就是在~/.cmake/package/Caffe路径下写入一个文件，文件名字是一个hash值，文件内容是cmake编译的caffe的路径。一旦有多个版本的caffe存在并且都用了cmake编译，而如果前面1~5的设置路径有错误，那么就加载这个~/.cmake/package/Caffe/xxx文件中的路径。很坑！） -
搜索在当前系统的平台文件中定义的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()执行后会产生几个变量：
但尝试找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**
```c++
#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
===================
2018年8月16日 20点46分
这里插播一个实际遇到的情况，挺有意思，领教了CMAKE_CXX_COMPILER变量的厉害（采坑）。
小伙伴的ubuntu上要编译Caffe，官方源码下载后用CMake构建，到95%左右，convert_mnist_siamse_data.o这里会报错，说DSO Missing，具体指向的是libcstdc++.
开始时百思不得其解，因为查看g++和cmake，以及protobuf什么的，都是apt装的或者系统自带的，为啥缺库呢。
后来有人指出是链接阶段没有链接libstdc++.so.6。但是为啥要明确链接它？
我的Debug方法：利用message( )函数（相当于C/C++里的printf( )）暴力输出各种链接库的名字，还是不能发现问题，逐步溯源到CMake的输出，发现CMAKE_CXX_COMPILER这个变量的取值出了问题。
CMAKE_CXX_COMPILER
CXX这个环境变量被设定了，设定的值为/usr/bin/gcc-5
CMake会读取这个$CXX 然后设定CMAKE_CXX_COMPILER为这个值，也就是用gcc-5替代了g++
所以后续编译的话都缺少stdc++这个库
在终端里，unset CXX，或者把你的bashrc/zshrc里面的export CXX=/usr/bin/gcc-5注释掉并退出重新进入shell，就可以正常使用CMAKE_CXX_COMPILER这一变量来编译Caffe了。
cmake变量
这篇写的还可以：https://chaopei.github.io/blog/2018/10/cmake-variable.html
这篇更详细一些：https://riptutorial.com/zh-CN/cmake/example/11821/变量和全局变量缓存
如果希望cmake -Dvar=value的方式，临时设定变量的值，则必须用set(VAR "some value" CACHE STRING "ignore this" [FORCE])的方式