cmake variable learning

0. CMAKE variables

cmake variables are divided into three types:

• Built-in variables
  Built-in variables also become reserved variables, which are created and reserved by cmake
• Custom variables
  Custom variables are defined and written by developers, and can be modified and accessed by developers in cmake files.
• Environment variables
  Environment variables are the environment variables of the operating system, cmake can interact with it, and obtain mutual information of the system, and the proprietary commands in cmake can interact with it.

0.1 Built-in variables

0.2 Custom variables

There are two types of custom variables: implicit definition and explicit definition.

0.2.1 Implicit custom variables

Variables defined by the project and enable_language commands are called implicit variables.

 project(<projectname> [languageName1 languageName2 ... ] )

The command field is mainly to define the project name. The above command will implicitly define some variables, starting with the defined project name to implicitly
define the variable name

<PROJECT-NAME>_BINARY_DIR
<PROJECT-NAME>_DESCRIPTION
<PROJECT-NAME>_HOMEPAGE_URL
<PROJECT-NAME>_SOURCE_DIR
<PROJECT-NAME>_VERSION
<PROJECT-NAME>_VERSION_MAJOR
<PROJECT-NAME>_VERSION_MINOR
<PROJECT-NAME>_VERSION_PATCH
<PROJECT-NAME>_VERSION_TWEAK

For example

project(helloworld) 

The above command will automatically add the following variable definitions:

helloworld_BINARY_DIR
helloworld_DESCRIPTION
helloworld_HOMEPAGE_URL
helloworld_SOURCE_DIR
helloworld_VERSION
helloworld_VERSION_MAJOR
helloworld_VERSION_MINOR
helloworld_VERSION_PATCH
helloworld_VERSION_TWEAK

enable_language(<lang> [OPTIONAL] )

This command enables CMake to support the language specified in the parameter, and supports CXX/C/Fortran/Asm. This command will define the following hidden variables:

CMAKE_<LANG>_COMPILER
CMAKE_<LANG>_CPPCHECK
CMAKE_<LANG>_CPPLINT
CMAKE_<LANG>_CREATE_SHARED_LIBRARY
CMAKE_<LANG>_CREATE_SHARED_MODULE
CMAKE_<LANG>_CREATE_STATIC_LIBRARY
CMAKE_<LANG>_FLAGS_DEBUG
CMAKE_<LANG>_FLAGS_RELEASE
CMAKE_<LANG>_COMPILER_AR

0.2.2 Normal variable definition

Nornal variables are defined using the set command

set(<variable> <value>... [PARENT_SCOPE])

will create the variable and set the value to , before being set, will be expanded. The value value can be followed by multiple values. If there are multiple values, the variable variable will be saved in the form of a list.

PARENT_SCOPE: It is the scope of the variable name. By default, the default scope of the variable belongs to the current CMakeLists.txt or function. If the PARENT_SCOPE field command is added, the value of a variable is set to the parent path or the calling function.

CMake will create its own instance for each CMakeList.txt file. The CMakeList.txt in the root directory is called a global instance, while those in other directories are called local instances. In fact, we can further find that the instance created by CMakeList.txt in the subdirectory will inherit the variables created in the corresponding parent directory, and copy a copy for our own use, so that modifying the variable value is equivalent to modifying the copied copy, and Values ​​in parent directories are not affected.

0.2.3 CACHE variables

The cache variable is defined using the following command:

set(<variable> <value>... CACHE <type> <docstring> [FORCE])  
	<type> <docstring>为必选项
    <type> 可以被 CMake GUI 用来选择一个窗口。
    FILEPATH  = 文件选择对话框。
    PATH        = 路径选择对话框。
    STRING    = 任意的字符串。
    BOOL       = 布尔值选择复选框。
    INTERNAL = 不需要 GUI 输入端。 (适用于永久保存的变量)  
	<docstring>常用于该变量解释说明一段文字。
	[FORCE]可选项将覆盖 cache 值，常用于修改cache变量。

Cache variables are equivalent to global variables, that is, all CMakeLists.txt in the same CMake project can be accessed.
All Cache variables will appear in the CMakeCache.txt file.
The option and find_file commands can also create cache variables.
Set the Cache variable value method:

0.3 Environment variables

Environment variables are mainly related to how cmake interacts with it:

• Read environment variables: $ENV{NAME}
• Set environment variables: SET(ENV{variable name} value)

CMake variable read

• Get variable value: ${}
• Use the variable name directly in the if statement instead of taking the value through ${}

1. Test example

1.1 CMakeLists.txt

cmake_minimum_required (VERSION 2.6)
project (veriable_test)

# The veriable to config.h.in.
set (MYTEST 1)


# configure a header file to pass some of the CMake settings
# to the source code
configure_file (
  "${PROJECT_SOURCE_DIR}/config.h.in"
  "${PROJECT_BINARY_DIR}/config.h"
  )

# add the binary tree to the search path for include files
# so that we will find config.h
include_directories("${PROJECT_BINARY_DIR}")

message("PROJECT_SOURCE_DIR: ${PROJECT_SOURCE_DIR}")
message("CMAKE_SOURCE_DIR: ${CMAKE_SOURCE_DIR}")
message("Tutorial_SOURCE_DIR: ${Tutorial_SOURCE_DIR}")
message("PROJECT_BINARY_DIR: ${PROJECT_BINARY_DIR}")

# add the executable
add_executable(veriable_test main.c)

1.2 main.c

#include <stdio.h>

void main(void) {

#ifdef MY_TEST
    printf("mytest\n");
#endif

    printf("cmake test\n");
}

1.3 config.h.in

#define MY_TEST @MY_TEST@

1.4 compile

mkdir build
cd build
cmake ..
make

run:

./veriable_test 

2. Common variables

2.1 CMAKE_BINARY_DIR

Indicates the compilation directory of the project, and the three variables below have the same value

PROJECT_BINARY_DIR: /home/xxxx/data/source/opensource/cmake/mystudy/cmake_study/day1/build
CMAKE_BINARY_DIR: /home/xxxx/data/source/opensource/cmake/mystudy/cmake_study/day1/build
veriable_test_BINARY_DIR: /home/xxxx/data/source/opensource/cmake/mystudy/cmake_study/day1/build

2.2 CMAKE_SOURCE_DIR

Indicates the source code directory of the project, and the values ​​​​of the three variables below are the same

PROJECT_SOURCE_DIR: /home/xxxx/data/source/opensource/cmake/mystudy/cmake_study/day1
CMAKE_SOURCE_DIR: /home/xxxx/data/source/opensource/cmake/mystudy/cmake_study/day1
veriable_test_SOURCE_DIR: /home/xxxx/data/source/opensource/cmake/mystudy/cmake_study/day1

2.3 CMAKE_CURRENT_SOURCE_DIR

Refers to the path where the currently processed CMakeLists.txt is located

/home/xxxx/data/source/opensource/cmake/mystudy/cmake_study/day1/myfunc

2.3 CMAKE_CURRENT_LIST_FILE

Outputs the full path to the CMakeLists.txt that calls this variable

/home/xxxx/data/source/opensource/cmake/mystudy/cmake_study/day1/myfunc/CMakeLists.txt

2.4 CMAKE_MODULE_PATH

The CMake module file is represented by xxxx.cmake. When CMakeLists.txt includes the .cmake file, when compiling and running, some commands in the .cmake will be executed at the inclusion, and the . Some macros and functions in cmake.
After setting CMAKE_MODULE_PATH, find the xxxx.cmake module by the include or find_package command.
For example, include(helper.cmake), the helper.cmake file needs to exist under the path name;
or find_package(helper), then the Findhelper.cmake instance needs to exist under the path
: sel4 code
sel4/tools/nanopb/examples/cmake_simple/CMakeLists.txt

set(CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/../../extra)
find_package(Nanopb REQUIRED)

sel4/tools/nanopb/extra/FindNanopb.cmake

Example: sel4 code

list(
    APPEND
        CMAKE_MODULE_PATH ${
    
    CMAKE_CURRENT_LIST_DIR}/helpers/ ${
    
    CMAKE_SOURCE_DIR}/projects/musllibc
)
include(check_arch_compiler)

./tools/seL4/cmake-tool/helpers/check_arch_compiler.cmake

2.5 CMAKE_C_COMPILER

Set the compilation toolchain used to compile C

set(CMAKE_C_COMPILER ${CROSS_COMPILER_PREFIX}gcc)
set(CMAKE_ASM_COMPILER ${CROSS_COMPILER_PREFIX}gcc)
set(CMAKE_CXX_COMPILER ${CROSS_COMPILER_PREFIX}g++)

2.6 @@ reference variable

@@With the configure_file method, pass the variables in the CMakeLists.txt file to the config file.
For example, the CMakeLists.txt file is as follows:

set (MY_TEST "hello")
configure_file (
  "${PROJECT_SOURCE_DIR}/config.h.in"
  "${PROJECT_BINARY_DIR}/config.h"
  )

The config.h.in file is as follows

#define MY_TEST @MY_TEST@
#cmakedefine USE_MYMATH

The generated config.h file is as follows

#define MY_TEST hello
#define USE_MYMATH

3. cmake common commands

3.1 ADD_DEFINITIONS

Add a -D definition to the C/C++ compiler, e.g.:

ADD_DEFINITIONS(-DENABLE_DEBUG -DABC)

The parameters are separated by spaces
If your code defines

#ifdef ENABLE_DEBUG 
// ...
#endif

This block of code will take effect.
If you want to add other compiler switches, you can set them through the CMAKE_C_FLAGS variable and CMAKE_CXX_FLAGS variable.

3.2 ADD_DEPENDENCIES

Define other targets that the target depends on, and ensure that other targets have been built before compiling this target.

ADD_DEPENDENCIES(target-name depend-target1 depend-target2 ...)

3.3 AUX_SOURCE_DIRECTORY

The basic syntax is:

AUX_SOURCE_DIRECTORY(dir VARIABLE)

The function is to find all the source code files in a directory and store the list in a variable. This instruction is temporarily used to automatically build the source file list. Because currently cmake cannot automatically discover newly added source files.
for example:

AUX_SOURCE_DIRECTORY(. SRC_LIST)
ADD_EXECUTABLE(main ${
    
    SRC_LIST})

3.4 FILE

FILE(WRITE filename “message to write”… )
FILE(APPEND filename “message to write”… )
FILE(READ filename variable)
FILE(GLOB variable [RELATIVE path] [globbing expressions]…)
FILE(GLOB_RECURSE variable [RELATIVE path] [globbing expressions]…)
FILE(REMOVE [directory]…)
FILE(REMOVE_RECURSE [directory]…)
FILE(MAKE_DIRECTORY [directory]…)
FILE(RELATIVE_PATH variable directory file)
FILE(TO_CMAKE_PATH path result)
FILE(TO_NATIVE_PATH path result)

3.5 INCLUDE

Used to load the CMakeLists.txt file, also used to load the predefined cmake modules:

INCLUDE(file1 [OPTIONAL])
INCLUDE(module [OPTIONAL])

The loaded content will be executed directly when processing to the INCLUDE statement.

3.6 FIND_ series instructions

FIND_FILE(<VAR> name1 path1 path2 ...)

The VAR variable represents the full path of the found file, including the file name.

FIND_LIBRARY(<VAR> name1 path1 path2 ...)

The VAR variable represents the full path of the found library, including the library file name.

FIND_PATH(<VAR> name1 path1 path2 ...)

The VAR variable represents the path containing this file.

FIND_PROGRAM(<VAR> name1 path1 path2 ...)

The VAR variable represents the full path containing the program.