cmake简明使用指南

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):

  1. CMAKE_PREFIX_PATH变量所表示的路径下寻找。
    换言之,CMAKE_PREFIX_PATH有最高的查找优先级。
    find_package()参数列表中填写NO_CMAKE_PATH则跳过该查找项。

  2. 在cmake特有的环境变量中查找。包括:

<package>_DIR
CMAKE_PREFIX_PATH
CMAKE_FRAMEWORK_PATH
CMAKE_APPBUNDLE_PATH

对于OpenCV,就是OpenCV_DIR了。
find_package()参数列表中填写NO_CMAKE_ENVIRONMENT_PATH跳过该查找项。

  1. find_package()的HINTS参数指定

  2. 系统环境变量PATH里寻找。
    find_package()参数列表中填写NO_SYSTEM_ENVIRONMENT_PATH跳过该查找项。

  3. 搜索在CMake GUI中最新配置过的工程的构建树。在find_package()参数列表中填写NO_CMAKE_BUILDS_PATH跳过该查找项。

  4. 搜索存储在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编译,而如果前面15的设置路径有错误,那么就加载这个~/.cmake/package/Caffe/xxx文件中的路径。很坑!)

  5. 搜索在当前系统的平台文件中定义的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。

  1. 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**
```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])的方式

posted @ 2017-05-05 23:32  ChrisZZ  阅读(3893)  评论(0编辑  收藏