06. CMake Grammer

CMake Grammer

---

1. Overview

CMake is a command-based scripting language where everything is treated as strings.

command(arg1 arg2 ...)

There are no strong types like C++ — behavior depends on how strings are interpreted.

---

2. Variables

2-1. set()

set(VAR value)

Description:

Creates or updates a variable.

Behavior:

• Stored in current scope
• Overwritten if called again

---

2-2. Access Variable

message(${VAR})

Description:

${} expands the variable into its value.

---

2-3. List Behavior

set(LIST a b c)

Description:

CMake treats lists as semicolon-separated strings.

a;b;c

---

2-4. unset()

unset(VAR)
unset(VAR CACHE)

Description:

• Removes variable
• Optional CACHE removes persistent value

---

3. Variable Expansion

3-1. Basic Expansion

${VAR}

Meaning:

Replace with value of VAR.

---

3-2. Indirect Expansion (Important)

set(name FOO)
set(FOO hello)

message(${${name}})

Meaning:

1. ${name} → FOO
2. ${FOO} → hello

✔ Used for dynamic variable access

---

3-3. Environment Variables

$ENV{HOME}

Description:

Access OS environment variables.

---

4. Condition (if)

if(condition)
elseif(condition)
else()
endif()

Description:

Evaluates condition expressions.

---

4-1. Numeric Comparison

if(A GREATER 10)

✔ Integer comparison

---

4-2. String Comparison

if(A STREQUAL "hello")

✔ Exact string match

---

4-3. Regex Match

if(A MATCHES "h.*o")

✔ Regular expression

---

4-4. Logical Operators

if(A AND B)
if(A OR B)
if(NOT A)

---

4-5. Existence Check

if(DEFINED VAR)
if(EXISTS file.txt)

✔ Check if variable or file exists

---

4-6. Combined Pattern (Advanced)

if(DEFINED ${variable} AND "${${variable}}")

Meaning:

• Check if referenced variable exists
• Check if value is TRUE

✔ Common in large projects (e.g., OpenCV)

---

5. Dynamic Expression Execution

set(cond 2 GREATER 1)

if(${cond})

Behavior:

if(2 GREATER 1)

✔ CMake executes expanded string as condition

---

6. Loops

6-1. foreach()

foreach(x a b c)
  message(${x})
endforeach()

Description:

Iterates over values.

---

6-2. List Iteration

foreach(x ${LIST})

✔ Expands list first

---

6-3. Range Loop

foreach(i RANGE 0 10)

✔ Numeric iteration

---

6-4. while()

while(condition)
endwhile()

✔ Loop while condition is true

---

7. Functions and Macros

7-1. function()

function(foo x)
  message(${x})
endfunction()

Behavior:

• Has its own scope
• Variables are local

---

7-2. macro()

macro(foo x)
  message(${x})
endmacro()

Behavior:

• No scope
• Acts like text substitution

✔ Used in OpenCV (OCV_OPTION)

---

7-3. Arguments

${ARGV0}
${ARGV1}
${ARGN}

---

8. Cache Variables

set(VAR value CACHE STRING "description")

Description:

Stores variable in CMakeCache.txt

---

Why Important

• Persists between configure runs
• User can override via CLI or GUI

---

Types

Type	Meaning
STRING	text
BOOL	ON/OFF
PATH	directory
FILEPATH	file

---

FORCE

set(VAR value CACHE STRING "" FORCE)

✔ Override existing cache value

---

9. option()

option(USE_CUDA "Enable CUDA" ON)

Description:

Creates user-configurable boolean option.

---

10. include() vs add_subdirectory()

include()

include(utils.cmake)

✔ Executes file inline ✔ No target creation

---

add_subdirectory()

add_subdirectory(src)

✔ Executes another CMakeLists.txt ✔ Adds build targets

---

11. Targets

11-1. Executable

add_executable(App main.cpp)

---

11-2. Library

add_library(MyLib STATIC lib.cpp)

---

11-3. Linking

target_link_libraries(App MyLib)

Description:

Defines dependency between targets.

---

11-4. Include Directories

target_include_directories(App PUBLIC include/)

---

11-5. Compile Options

target_compile_options(App PRIVATE -O2)

---

11-6. Definitions

target_compile_definitions(App PRIVATE USE_FEATURE)

---

12. install()

install(TARGETS App DESTINATION bin)
install(FILES a.h DESTINATION include)

Description:

Defines how build outputs are copied into a structured install directory.

---

12-1. Basic Concept

install() does not build anything.

It copies and organizes artifacts produced during build.

Example result:

install/
 ├── bin/
 ├── lib/
 ├── include/

---

12-2. Common Signatures

Install targets

install(TARGETS App DESTINATION bin)

✔ Executables / libraries

---

Install files

install(FILES a.h DESTINATION include)

✔ Headers or config files

---

Install directories

install(DIRECTORY include/ DESTINATION include)

✔ Entire folder copy

---

12-3. COMPONENT (Important)

install(TARGETS App DESTINATION bin COMPONENT runtime)
install(FILES a.h DESTINATION include COMPONENT dev)

Description:

COMPONENT groups install rules into logical parts.

---

Why it exists

Allows partial installation.

cmake --install build --component dev

✔ installs only development files (headers)

---

Typical Convention

Component	Meaning
runtime	executables
dev	headers, cmake configs
library	shared/static libs

---

Important Insight

COMPONENT is NOT a variable and NOT a folder name.
It is a label used by CMake to group install rules.

---

13. File Operations

file(GLOB SRC "*.cpp")
file(COPY src DESTINATION build)

---

14. string()

string(REPLACE "a" "b" OUT ${VAR})
string(TOUPPER ${VAR} OUT)

Description:

Performs string manipulation.

---

14-1. REPLACE

set(VAR "apple")
string(REPLACE "a" "b" OUT ${VAR})

Result:

OUT = bpple

---

14-2. TOUPPER / TOLOWER

string(TOUPPER "hello" OUT)

Result:

OUT = HELLO

---

14-3. CONCAT

string(CONCAT OUT "Hello " "World")

Result:

OUT = Hello World

---

14-4. REGEX

string(REGEX MATCH "h.*o" OUT "hello")

✔ Pattern matching

---

Important Insight

string() does NOT modify variables directly.
It always writes to an output variable.

---

15. list()

list(APPEND MYLIST item)
list(REMOVE_ITEM MYLIST item)
list(LENGTH MYLIST len)

Description:

Manipulates list variables.

---

15-1. Append

set(MYLIST a b)
list(APPEND MYLIST c)

Result:

a;b;c

---

15-2. Remove

list(REMOVE_ITEM MYLIST b)

Result:

a;c

---

15-3. Length

list(LENGTH MYLIST len)

Result:

len = 2

---

15-4. Get Element

list(GET MYLIST 0 first)

✔ Index-based access

---

Important Insight

CMake lists are just strings separated by ';'

---

16. message()

message("Hello")
message(STATUS "Info")
message(WARNING "Warning")
message(FATAL_ERROR "Stop")

Description:

Outputs messages during configure/build.

---

16-1. Levels

Level	Meaning
STATUS	normal info
WARNING	warning message
AUTHOR_WARNING	dev warning
FATAL_ERROR	stop execution

---

Example

message(STATUS "Building project...")

---

Behavior

message(FATAL_ERROR "Something failed")

✔ Immediately stops CMake

---

Important Insight

message() is mainly used during configure phase
for debugging and logging

---

17. Built-in Variables

CMAKE_SYSTEM_NAME
CMAKE_SOURCE_DIR
CMAKE_BINARY_DIR
CMAKE_CURRENT_SOURCE_DIR
CMAKE_CURRENT_BINARY_DIR

---

18. Comments

18-1. Single-line

# This is a comment

---

18-2. Multi-line

#[[
This is a multi-line comment
]]

---

Important Behavior

Comments are ignored during parsing

---

Common Usage

# Enable CUDA if available
option(USE_CUDA "Enable CUDA" ON)

---

Important Insight

CMake has no inline comment syntax (like // or /* */)
Only # and #[[ ]] are valid

---

19. Key Concepts

✔ Everything is string-based
✔ ${} controls execution
✔ if() evaluates expressions, not just values
✔ CACHE variables persist
✔ include executes code
✔ add_subdirectory builds structure
✔ target is the core abstraction