Cmake cheatsheet

copyright (C) qingfeng Xia 2011-2020 CC-BY-NC 4.0

#Cmake cheat sheet in markdown

#Cmake cheat sheet

## quick start
1. first example, see more details at <https://cmake.org/cmake-tutorial/>

```
cmake_minimum_required (VERSION 2.8.0)#cmake grammar evolves, 
project (testcpp) # define the output executive name

add_executable (testcpp testcpp.cpp) #define source to object relation
```

2. in source build cmdline:  
`cmake <path to toplevel cmakelists.txt> -G <generator> && make` 

out of source build is recommended to keep source tree clean:  
```
cd dir_of_source_with_toplevel_cmakelists.txt && mkdir build 
cd build && camke .. &&make
make install
```

using `nmake` on windows visual studio build tool, as cmake generate platform specific makefile

3. GUI tool `cmake-gui <path to toplevel cmakelists.txt>`
build option can be turn on and off in GUI  
```
option(<option_variable> "help string describing option"
       [initial value])
```
4. FindGTK module, work like `pkg-config` to get include and lib path

```
GTK_INCLUDE_DIR   - Directories to include to use GTK
GTK_LIBRARIES     - Files to link against to use GTK
GTK_FOUND         - GTK was found
GTK_GL_FOUND      - GTK's GL features were found
```
for more details see <https://cmake.org/Wiki/CMake>


## cmake language syntax

cmake is a script language, similar with shell to some extent.
see [cmake wiki](https://cmake.org/Wiki/CMake/Language_Syntax)

+ only one kind of variable, i.e. string,   
> but it will be interpreted as bool in `IF (var)`  
or integer `IF (var GREATER 10) ... ENDIF`

+ variable substitution `${VAR}`, SET and UNSET, `IF(DEFINED x)`

+ only one kind of data structure: LIST, string sperated by semicolon  
`SET(var a b c)` is equal to `SET(var "a;b;c")`

+ quotation mark to reserve sapce "hello world"
```
SET( x a b c   ) # stores a list "a;b;c" in x      (without quotes)
SET( y "a b c" ) # stores a string "a b c" in y      (without quotes)
MESSAGE( a b c ) # prints "abc"   to stdout, automatically concat (without quotes)
MESSAGE( ${x} )  # prints "abc"   to stdout (without quotes)
MESSAGE("${x}")  # prints "a;b;c" to stdout (without quotes)
MESSAGE( ${y} )  # prints "a b c" to stdout (without quotes)
MESSAGE("${y}")  # prints "a b c" to stdout (without quotes)
```
+ comment by #, escape by \, line continuation by /
> but in path string: "http://////www.example.com"

> but it is different from bash shell

> newline to split list element

- cmake variable and command is case insensitive  
> but UPPER case for command is recommended   
and varible content like filename is case sensitive

- ""(empty string), "NO; N; FALSE; <var>-NOTFOUND; OFF;0;" or lower case is regarded false in IF()

- only integer algorithm `MATH(EXPR outputvar expr)`  
```
SET( expression 4 LESS 10 ) # ${expression} is now "4;LESS;10"
IF( ${expression} )         # expands to IF( 4;LESS;10 )
  MESSAGE( "CMake believes that 4 is less than 10." )
ENDIF( ${expression} )
```
bash shell math: `$((math_expr))` 

- generate `config.h` from `config.h.cmake` template   
> by replacing "@var" with var defined in camkelists.txt
`MESSAGE( ${x}${y} ) # displays "31"`

- function is different from macro whose variables have global scope

## important command and variable
<https://cmake.org/Wiki/CMake_Useful_Variables>
### 1.commands

+ $ENV{HOME} #access to environment variable
+ EXECUTE_PROCESS(cmd var_to_hold_result)
+ INSTALL(TARGETS|FILES list_of_f dest)
+ CONFIGURE_FILE() #generate config.h from config template input file
+ INCLUDE_DIRECTORY() #subdir with cmakelists.txt
+ ADD_LIBRARY(), ADD_EXECUTABLE(), add_definitions, add_dependencies
+ INCLUDE(extra_cmake_file) #as include in c++ for extra functions

### 2. location variables

+ SET(CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/MyCMakeScripts) 
> where FIND_PACKAGE(FooBar) can find `findFooBar.cmake`

+ CMAKE_SOURCE_DIR # top source dir containing the top-level CMakeLists.txt,
+ CMAKE_BINARY_DIR # top folder to build binary object
+ CMAKE_CURRENT_LIST_FILE # full path of the current processed cmakelists.txt
+ CMAKE_INCLUDE_PATH  # path to search for header file e.g. `/usr/include`
+ CMAKE_INSTALL_PREFIX #just as DESTDIR in `make DESTDIR=/home/john install`

### 3. compiler control variables
+ CMAKE_CXX_COMPILER 
+ CMAKE_BUILD_TYPE # NONE, DEBUG, RELEASE, etc
+ CMAKE_<Lang>_FLAGS # for build_type NONE
+ CMAKE_LINK_LIBRARY_CFLAGS
+ enable C++ standard support in a portable way
```
set(CMAKE_CXX_STANDARD 11) #98, 14, 17
set(CMAKE_CXX_STANDARD_REQUIRED ON)
```

### 4. predefined platform and compiler detection varibles   
platform like: WIN32, APPLE, UNIX (linux is UNIX but not APPLE), MYSYS, CYGWIN
compilers: MSVC, MINGW, iNTEL; CMAKE_COMPILER_IS_GNUCXX, CLANG

### 5. command line help
```bash
cmake --variable-list
cmake --command-list
cmake --module-list
cmake -h #show all generator
```

<https://cmake.org/Wiki/CMake_Useful_Variables>

## Why cmake?

cmake is a new language, why should we learn a new language instead of json or python (as in scons)?

1. cmake inherits some conception of traditional unix makefile

2. multiple programming lang support and cross-platform with generators for majourity of IDE tools

3. plenty of official modules like "FindXXX.cmake"

4. speedup by var cache `SET(var value CACHE)`

5. CPACK for binary package and windows NSIS installer generation

6. Generating Dependency Graphs with CMake, `cmake --graphviz=test.dot .`

7. tool to generate cmakelists.txt from scratch or convert from existent build system

## what I do not like

- cmake is not a precise or clear script lang
- confusing string quotation and substitution
- un-intuitive function style programming to c/python programmers
- messed up of variable_content and variable
- mixed up argument list and keyword in function call, not sep by comma
> relies heavily on this fuction to parse function/command input arg
`CMAKE_PARSE_ARGUMENTS(<prefix> <options> <one_value_keywords> <multi_value_keywords> args...)` 



 



CC-BY-NC 4.0 licensed free for non-commercial usage
Author: Qingfeng XIA
copyright (C) 2011-2020
http://www.iesensor.com
please keep the original link in your reference.
http://www.iesensor.com/blog/2016/12/24/cmake_cheatsheet/
This entry was posted in Uncategorized. Bookmark the permalink.