cmake variable and cache

Local Variables

# Sets the MY_VARIABLE in the current function or directory scope.
set(MY_VARIABLE "value")

• 变量名一般都是大写的。
• 你可以通过%{}访问一个变量。
• cmake中的变量是有作用域的。在subdirectory的cmake中，你将无法再访问当前文件中定义的变量。
• 当变量的值中存在空格时，必须加上引号。特别是指定路径时，因为路径是很有可能含有引号的。所以制定路径不应该写%{MY_PATH}，而应该写"%{MY_PATH}"

---

Cache Variables

当你运行cmake的时候，在build路径下会生成CMakeCache.txt文件，里面会保存你在命令行中设置的options等，所以你下一次运行cmake的时候不需要再次列出。

如果你要在CMakeLists.txt中set命令行中未设置的变量，可以这样做：

# Sets the given cache MY_CACHE_VARIABLE (cache entry).
# Since cache entries are meant to provide user-settable values this does not
# overwrite existing cache entries by default.
# Use the FORCE option to overwrite existing entries.
set(MY_CACHE_VARIABLE "VALUE" CACHE STRING "Description")

如果该变量已经在命令行中被set过，则上面的指令不会覆盖其值。

如果在上述指令中加入FORCE，则会覆盖原有的值。

set(MY_CACHE_VARIABLE "VALUE" CACHE STRING "" FORCE)

variable的type除了STRING之外，还可以为BOOL，PATH，INTERNAL等。
设置BOOL值，有更简单的写法：

option(MY_OPTION "This is settable from the command line" OFF)

这里列出了cmake中的一些特定variable。

---

Properties

Cmake中还有一种存储信息的方式，就是用property。它就像一个变量，但需要依附于其他item，比如directory或target。
设置property有2种方式：

# Sets one property on zero or more objects of a scope.
set_property(TARGET TargetName
             PROPERTY CXX_STANDARD 11)

# Sets properties on targets. Targets can have properties that affect how they are built.
set_target_properties(TargetName PROPERTIES
                      CXX_STANDARD 11)

第一种方式通用性更好，且可以指定多个target/file/test等。
第二种方式就是专门用来给target设置property的，它可以为单个target设置多个property。

get property则可以用

# Gets one property from one object in a scope.
get_property(ResultVariable TARGET TargetName PROPERTY CXX_STANDARD)

ResultVariable用于保存读取出的property的值。

这里列出了cmake中一些特定的property。

---

Scope
CMake中的变量也有scope的概念。这里分别介绍4种情况下，scope会有何不同。
参考链接

1. add_subdirectory()
   parent directory中的CMakeLists.txt（以下简称P CMakeList）用add_subdirectory()，包含了child directory中的CMakeLists.txt（以下简称C CMakeList）。
   但是P CMakeList是感知不到C CMakeList中的local variable的。
   原因是，当add_subdirectory被执行时，它创建了一个新的scope，用于处理C CMakeList中的变量。

2. include()
   P CMakeList用include(child/CMakeLists.txt)包含了C CMakeList。在这种情况下，P CMakeList是可以感知到C CMakeList中的变量的。因为include()指令并没有创建新的scope，P CMakeList与C CMakeList共享同一个scope。

3. function

   # CMakeLists.txt
   cmake_minimum_required(VERSION 3.2)
   project(CMakeVariableScopeTutorial)
   
   function(func)
       set(A "Child")
   endfunction()
   
   set(A "Parent")
   
   func()
   
   message(STATUS ${A})
   # Prints "Parent"
   

   如上所示，在CMakeLists.txt中定义了一个函数func，该函数设置了一个变量A，值为"Child"。
   然后设置了一个变量A，值为"Parent"。
   接着调用func，并打印A的值，最后打印"Parent"。

   即使我们将A作为参数传给func，结果也是一样的。

   # CMakeLists.txt
   cmake_minimum_required(VERSION 3.2)
   project(CMakeVariableScopeTutorial)
   
   function(func param)
       set(${param} "Child")
   endfunction()
   
   set(A "Parent")
   
   func(A)
   
   message(STATUS ${A})
   # Prints "Parent"
   

   之所以会出现这样的结果，是因为function会创建一个新的scope，其中的variable与其外的variable没有关系，就像上面提到的add_subdirectory()。

4. macro

   # CMakeLists.txt
   cmake_minimum_required(VERSION 3.2)
   project(CMakeVariableScopeTutorial)
   
   macro(mac)
       set(A "Child")
   endmacro()
   
   set(A "Parent")
   
   mac(A)
   
   message(STATUS ${A}) # Prints "Child"
   

   现在把function换成Macro，结果打印"Child"。
   这是因为macro并不会建立新的scope。

如果在add_subdirectory()时，在set variable时加上"PARENT_SCOPE"，那么P CMakeList是可以感知到 C CMakeList中的变量的。如下例：

# parent CMakeLists.txt
cmake_minimum_required(VERSION 3.2)
project(CMakeVariableScopeTutorial)

set(A "Parent")

add_subdirectory(child)

message(STATUS ${A})
# Prints "Child"

# child CMakeLists.txt
set(A "Child" PARENT_SCOPE)
message(STATUS ${A})
# Prints "Parent"

在P CMakeList中，打印A的内容为"Child"。这我们是可以理解的，因为其内容在C CMakeList中被修改了。
但是为什么在C CMakeList中，打印A的内容为Parent呢？

因为add_subdirectory()在创建新的scope的时候，创建了变量A的一份copy，即A'。
A在parent scope中，A'在child scope中。

C CMakeList中的2句code：

• set(A "Child" PARENT_SCOPE)，因为加上了PARENT_SCOPE，设置的是parent scope中的A。
• message(STATUS ${A})打印的是child scope中的A'。

同理，在function的例子中，加上PARENT_SCOPE，也可以达到相同的效果。