CMake Tutorial with OpenCV Example

Official Documentation Source:

CMake Tutorial — CMake 3.23.0-rc1 Documentation

Intro. and Installation

source: CMake

CMake is an open-source, cross-platform family of tools designed to build, test and package software. CMake is used to control the software compilation process using simple platform and compiler independent configuration files, and generate native makefiles and workspaces that can be used in the compiler environment of your choice. 

CMake supports various forms of installation, just pick one per your OS and 

==> make sure to add cmake to your system path during installation; CMake is made and documented as a UNIX style command and it's to use as intended.

==> after installation and adding the executable to your system path, you can use it from the windows' terminal "cmd" or by emulated UNIX environment via cygwin.

Essentials

Step 1: A Basic Starting Point — CMake 3.23.0-rc1 Documentation

Configuration

To configure CMake to customize compilation/build processes, use the interface file: 

CMakeList.txt

==> this is a must-have

tutorial example

cmake_minimum_required(VERSION 3.10)

# set the project name
project(Tutorial)

# add the executable
add_executable(Tutorial tutorial.cxx)

Note that this example uses lower case commands in the CMakeLists.txt file. Upper, lower, and mixed case commands are supported by CMake.

Execution

To execute cmake for building your project, or just compile a single executable:

#setup cmake config.
vi CMakeList.txt

#go to the src_dirname's parent; tutorial/Step1/tutorial.cxx ==> 'tutorial' 
cd ~/xxxxxx/src_dirname/..

#copy the CMake config. file, CMakeList.txt, to the src file
cp CMakeList.txt src_dirname/

#prepare build dir
mkdir build_dirname

# "run CMake to configure the project and generate a native build system:"
cd build_dirname
cmake ../src_dirname

# "Then call that build system to actually compile/link the project:"
cmake --build .

# now you have the executable, "use the newly built Tutorial with these commands:"
Tutorial 4294967296
Tutorial 10
Tutorial

in short:

1. add cmake config. file to the srcFile dir.;

2. initialize cmake at the buildDir with the srcFile dir and the config. file; ==> establish local build system

!!!!! -G specify the generator or the compiler and architecture (32/64) to be used later

and each build folder will be generator specific once set ==> rm cache files to reset

!!!! read cmake --help for the generator entries and what do they produce

3. call cmake at the buildDir with "--build" and use local build system ".";

4. the compiled executable will be the specified projectName as in project(projectName).

Finer Control and Rebuild

see the official tutorial for various other compiler control options;

==> you only need to pick what you need and add them into the config. file.

==> every time you updated the config. file, rebuild the project as:

cd buildDir
cmake --build .

==> call cmake and target local build system at buildDir directly, just call, no need to manully update the build system.

Examples

OpenCV: Using OpenCV with gcc and CMake

OpenCV Install

OpenCV: Installation in Windows

for Windows command lines to setup the environment variables, see:

Windows cmd Common Commands_maxzcl的博客-CSDN博客

OpenCV: Installation in Linux

during configuration stage, if there are failed download, chances are you can ignore them, if not, check "CMakeDownloadLog.txt" in the buildDir and download the files manually.

==> first line of each entry tells you where to put the files

for windows user without access to visual studio, try eclipse 

How to install and use Eclipse CDT for C/C++ programming

OpenCV: Using OpenCV with Eclipse (plugin CDT)

for minimalism, use gcc and cmake:

!!! ==> as you will see later cross-platform use, such as Windows with cygwin virtual env. will be very messy, it is recommended to use native UNIX with minimal gcc or Windows with VS   

from: OpenCV: Using OpenCV with gcc and CMake

Create a program using OpenCV

Let's use a simple program such as DisplayImage.cpp shown below.

#include <stdio.h>
#include <opencv2/opencv.hpp>
using namespace cv;
int main(int argc, char** argv )
{
    if ( argc != 2 )
    {
        printf("usage: DisplayImage.out <Image_Path>\n");
        return -1;
    }
    Mat image;
    image = imread( argv[1], 1 );
    if ( !image.data )
    {
        printf("No image data \n");
        return -1;
    }
    namedWindow("Display Image", WINDOW_AUTOSIZE );
    imshow("Display Image", image);
    waitKey(0);
    return 0;
}

Create a CMake file 

Now you have to create your CMakeLists.txt file. It should look like this:

cmake_minimum_required(VERSION 2.8)
project( DisplayImage )
find_package( OpenCV REQUIRED )
include_directories( ${OpenCV_INCLUDE_DIRS} )
add_executable( DisplayImage DisplayImage.cpp )
target_link_libraries( DisplayImage ${OpenCV_LIBS} )

Generate the executable

This part is easy, just proceed as with any other project using CMake:

cd <DisplayImage_directory>
cmake .
make

 ==> note that cmake . might very well fail at find_package step if your installed OpenCV with cross-platform environment, say windows installation but use as UNIX by cygwin; in such a case, see: opencv - CMake Error at CMakeLists.txt CMAKE_PREFIX_PATH - Stack Overflow

1. Check that OpenCV is installed on your system. Note the folder where it is installed. For example: C:\OpenCV
2. Execute CMake with a command line similar to

cmake -DCMAKE_PREFIX_PATH="C:\OpenCV" ..

OR ==> installation root can be a tricky one to determine for mixed platforms 

find the folder containing OpenCVConfig.cmake (for example C:\OpenCV\build\x86\vc10\lib) and pass it to CMake via the variable OpenCV_DIR

cmake -DOpenCV_DIR="C:\OpenCV\build\x86\vc10\lib" ..

!!!!for Windows&Cygwin NOTE!!!!

1. ==> CMakeLists.txt and cmake options must have native system file path (albeit with linux style), not the cygwin virtual file path.

for a more detailed solution and explanation on this error, see:

听说你安装测试 OpenCV 总是不成功？你可能遇到这个find_package坑了！ - 知乎

for your local dir, see opencv_data_config.hpp in the buildDir.

2. ==> now you have set up the build system, if you do not have UNIX makefile, use

cmake --build . 

==> !!! you would still be compiling/building the project with VS, since your OpenCV is installed by that config.

===> MinGW makefile as generator (compiler) might work as well and you would be building the project with MinGW presumably, but it's not as robust as the VS building process. 

3. for problem such as:

opencv_highgui455d.lib(opencv_highgui455d.dll) : fatal error LNK1112: 模块计算机类型“x64”与目标计算机类型“x86”冲突

see 

fatal error LNK1112: module machine type 'x64' conflicts with target machine type 'X86' Visual studio 2010 and cmake - Stack Overflow

/MACHINE (Specify Target Platform) | Microsoft Docs

==> seriously though, just stick with MinGW or UNIX generator and use the gcc if you don't like VS.

Result

By now you should have an executable (called DisplayImage in this case). You just have to run it giving an image location as an argument, i.e.:

./DisplayImage lena.jpg

You should get a nice window as the one shown below:

Additional Note for Windows VS Deployment

even though the sample code might be compiled and executed successfully, during debugging run, you might still encounter error such as: 无法查找或打开PDB文件

it's an issue with loading the descriptive files associated with .dlls 

当程序在 VS 上编译时，程序所依赖的所有动态链接库（dll 文件）也会被编译，编译过程中每个 dll 都会产生一个pdb文件，又称为“符号文件”，是一个存储数据的信息文件，其包含 dll 库在编译过程的某些调试信息，例如程序中所用到的全局变量、局部变量、函数名以及他们的入口地址等。pdb 文件主要用于调试程序，多用于当VS中有多个项目，且项目之间互有依赖关系时，使用pdb文件调试程序，往往会事半功倍，初学者一般不会用到。当使用VS 调试程序时，会默认加载你的程序以及程序依赖的dll库产生的所有pdb文件，但是结果往往是VS自己找不到依赖库的pdb文件，于是就提示给你“无法查找或打开pdb文件”。

==>to resolve this issue see:

VS常见问题：“无法查找或打开PDB文件”是怎么回事？如何解决 - 云+社区 - 腾讯云

or as 解决VS出现 “无法查找或打开 PDB 文件”_鸡啄米的时光机的博客-CSDN博客_无法打开或查找pdb文件

indicates, just use Ctrl + F5 to run without debugger to avoid this issue.