Comments, instructions and variables in CMake syntax

Comments, instructions and variables in CMake syntax

CMake commands have different types, including script commands, project configuration commands and test commands. For details, please check the official website** cmake-commands**.

CMake language is organized into three source file types in project configuration:

  1. Directory: cmakelists Txt, which refers to a directory. It describes how to generate and build the system for the directory (Source tree), and the project configuration command will be used;
  2. Script: < script > CMake is a script file of CMake language, which can be executed directly with cmake -P and can only contain script commands;
  3. Module: < module > Cmake, which realizes some modular functions, can be included by the first two, such as include(CTest) to enable the test function.

Run script mode

CMake provides a script file mode, which can run the specified script instead of generating makefile. The syntax features described later can be practiced in literal translation mode.

$ cmake -P <script-file> # -P specifies the CMake script file to execute

Although this means that we can use CMake as a general scripting language, CMake is not designed for general programming language, so it may not be convenient to use, especially in mathematical calculation.

Introduction to CMake grammar

CMake syntax is very simple, with the following points:

  • CMake is composed of command and comment. Blank, line feed and tab are only used as separators.
  • Note: the note begins with a pound sign "#" and ends at the end of the line.
  • Instruction: parentheses are added after the instruction to pass in parameters. The instruction is parsed from top to bottom. Instruction names are case insensitive. For example, command and command are the same.
  • Variables: users can use variables to store information. Variables are case sensitive, and built-in variables are capitalized.

1. Notes

  • Line comments: use #;

  • Block annotations: using #[[annotation content]].

Example 1: Notes

script.cmake

# Single-Line Comments 
#[[
Block annotation
Author: yunxinglouyun
Date: 2022-05-14
]]

2. Instruction

CMake script consists of a series of commands, each of which can have zero or more parameters. For example, the message instruction is often used to output messages:

Example 2: print helloworld
message(helloworld)

Output:

helloworld

The instruction is case insensitive, that is, Command(), Command() and Command() are the same. Note that the variable is case sensitive, that is, the variable Hello is different from the variable hello.

3. Variables

Key points of variables in CMake:

  • Variable names are case sensitive, and built-in variables are capitalized. For example, hello is different from hello.
  • Users can use variables to store information. Strictly speaking, CMake has only two forms: string and string list. In essence, numeric variables and Boolean variables are only strings with special meaning.
  • The basic variable operation commands are set() and unset(), but there are other commands that can affect variables, such as string() and list()

The following common variable types are available in CMake.

variabledescribe
General variableFor general statements
Cache variableProvide user configuration options
environment variableFor environment variables

Use the set and unset commands in CMake to set or unset variables.

When it comes to variable categories, variable references work in a somewhat special way, but in general, the following situations apply:

  • The ${} syntax is used to reference normal variables or cached variables.
  • The $ENV {} syntax is used to reference environment variables.
  • The $CACHE {} syntax is used to reference CACHE variables.

General variable

Boolean type

typevalue
trueOn, y, not true, y
false0, OFF, NO, FALSE, N, IGNORE, NOTFOUND, empty string ", string ending with - NOTFOUND

The set variables can be string, string list (set multiple values directly, or use semicolon separated string format as "v1;v2;v3"),

Example 3: set the variable and extract the variable value (usually the ${} symbol must be added outside)
# script.cmake
# Author: yunxingluoyun
# Date: 2022-05-14

# Print helloworld
message(helloworld)

# Set variables of string type
set(AUTHOR_NAME1 yunxingluoyun)
set(AUTHOR_NAME2 "yun xing luo yun")
set(AUTHOR_NAME3 yun\ xing\ luo\ yun)

# Set variables of string list type
set(P1 hello world)   # Save as "hello;world"
set(P2 hello;world)
set(P3 "hello;world")

# Special variables: numeric and Boolean values, but both belong to strings
set(NUM 2022)   # Saved as string, but can compare with other number string
set(FLAG ON)  # Bool value

# display output
message("character string:")
message(${AUTHOR_NAME1}) #Almost all escape tables of C language can be used in message
message(${AUTHOR_NAME2})
message(${AUTHOR_NAME3})

message("String list:")
message(${P1})
message(${P2})
message(${P3})

message("numerical value:")
message(${NUM})

message("Boolean value:")
message(${FLAG})

Output:

helloworld
 character string:
yunxingluoyun
yun xing luo yun
yun xing luo yun
 String list:
helloworld
helloworld
helloworld
 numerical value:
2022
 Boolean value:
ON

The main points are as follows:

  1. If the variable value to be set contains spaces, you need to use double quotation marks or "" escape, otherwise you can omit double quotation marks;
  2. If multiple values are set or there is ";" in the middle of the string value, it will be saved as a list, also with ";" Split string;
  3. Variables can be operated by the list command. Variables with a single value are equivalent to a list with only one element;
  4. Reference variable: ${< variable >}, which can be simplified to use only variable name < variable > in if() condition judgment.
Example 4: unsetting variables
# Author: yunxingluoyun
# Date: 2022-05-14

set(P "hello;world")
unset(P)
message(${P})

result:

# Because the P variable is canceled, an error is reported: the number of function call parameters is incorrect
CMake Error at script.cmake:6 (message):
  message called with incorrect number of arguments

Cache variable

In essence, the cache variable is cmakecache stored in build tree Txt file. They contain information collected from the system (compilers, linkers, tools, and other paths) and users through the graphical user interface during the project configuration phase. Cache variables are not available in scripts (because there is no CMakeCache.txt file) – they exist only in the project.

Cache variables (cache entries) are mainly used to provide user configuration options. If the user does not specify them, the default value will be used. The setting method is as follows:

# set(<variable> <value>... CACHE <type> <docstring> [FORCE])
set(CACHE_VAR "Default cache value" CACHE STRING "A sample for cache variable")

main points:

  1. Mainly to provide configurable variables, such as compilation switch;
  2. Reference CACHE variable: $CACHE {< varialbe >}.

The Cache variable will be saved in cmakecache.exe under the build directory Txt, it will remain unchanged after caching, unless it is reconfigured and updated

environment variable

This is the simplest variable. Cmake replicates variables in the environment used to start the cmake process and makes them available in a single global scope. To reference these variables, use the $env {< name >} syntax.

Modify the environment variable of the current processing process, and set and reference the format as follows:

# Author: yunxingluoyun
# Date: 2022-05-14

# set(ENV{<variable>} [<value>]) # Set the syntax of the environment variable
set(ENV{ENV_VAR} "$ENV{PATH}") # Extract the string from the environment variable PATH of the system and save it to ENV_VAR environment variable
message("Value of ENV_VAR: $ENV{ENV_VAR}") # Display output results

Output:

Value of ENV_VAR: C:\Users\67231\AppData\Local\Microsoft\WindowsApps;
'''Partial omission'''
C:\Users\67231\AppData\Local\Microsoft\WindowsApps;D:\MiKTeX\miktex\bin\x64\;D:\Microsoft VS Code\bin;D:\snap\bin;C:\Users\67231\AppData\Roaming\npm

Similar to CACHE variables, environment variables should be referenced in the format: $env {< variable >}.

Reference website:
https://zhuanlan.zhihu.com/p/368701263
https://cmake.org/cmake/help/latest/command/unset.html?highlight=unset
https://zh.wikibooks.org/wiki/CMake_%E5%85%A5%E9%96%80/%E5%9F%BA%E6%9C%AC%E8%AA%9E%E6%B3%95
http://vegetable.wodekouwei.com/2019/04/21/l-cmake-syntax/
https://www.codeleading.com/article/93674685430/
https://www.jianshu.com/p/1ec2b5602b03

Tags: C++ cmake IDE Visual Studio

Posted by MsShelle on Sun, 15 May 2022 04:03:36 +0300