/home/zhuang

zhuang@linux:~/notes/learn-some-cmake/$ cat

Learn Some CMake

$ stat learn-some-cmake.md

words 364
reading 2 min
views ...

$ grep tags learn-some-cmake.md

@tools #CMake #build-system

CMake provides several built-in variables that describe the project, source tree, build tree, and the file currently being processed. Knowing the differences between them makes it easier to write reusable CMakeLists.txt files.

Common Directory Variables

CMake variable references use the ${VARIABLE_NAME} syntax. For example:

cmake 
message(STATUS "Current source directory: ${CMAKE_CURRENT_SOURCE_DIR}")

The following variables are commonly used when working with paths.

Source Directories

VariableDescription
CMAKE_SOURCE_DIRThe top-level source directory of the entire CMake build. It contains the root CMakeLists.txt.
PROJECT_SOURCE_DIRThe source directory of the most recent project() command.
<PROJECT-NAME>_SOURCE_DIRThe source directory of the named project. For example, ${MyApp_SOURCE_DIR}.
CMAKE_CURRENT_SOURCE_DIRThe source directory whose CMakeLists.txt is currently being processed.

In a simple project with only one project() call, CMAKE_SOURCE_DIR and PROJECT_SOURCE_DIR usually have the same value. They may differ when the project is included as a subproject of another CMake build.

Build Directories

VariableDescription
CMAKE_BINARY_DIRThe top-level build directory of the entire CMake build.
PROJECT_BINARY_DIRThe build directory corresponding to the most recent project() command.
<PROJECT-NAME>_BINARY_DIRThe build directory of the named project. For example, ${MyApp_BINARY_DIR}.
CMAKE_CURRENT_BINARY_DIRThe build directory corresponding to the CMakeLists.txt currently being processed.

Here, binary directory means the build directory where CMake generates build-system files and other build outputs. It does not specifically mean a directory containing executable files.

Current File and List Context

VariableDescription
CMAKE_CURRENT_LIST_FILEThe full path of the CMake list file currently being processed.
CMAKE_CURRENT_LIST_DIRThe directory containing the current list file.
CMAKE_CURRENT_LIST_LINEThe current line number in the list file.
CMAKE_CURRENT_FUNCTION_LIST_DIRThe directory in which the currently executing function was defined.

CMAKE_CURRENT_LIST_DIR is especially useful in included modules because it refers to the location of the module itself:

cmake 
include("${CMAKE_CURRENT_LIST_DIR}/helpers.cmake")

Example Directory Layout

Given this project:

text 
my-project/
├── CMakeLists.txt
└── src/
    └── CMakeLists.txt

configured with:

sh 
cmake -S my-project -B my-project/build

while CMake processes src/CMakeLists.txt, the main variables have values similar to:

text 
CMAKE_SOURCE_DIR         = /path/to/my-project
PROJECT_SOURCE_DIR       = /path/to/my-project
CMAKE_CURRENT_SOURCE_DIR = /path/to/my-project/src

CMAKE_BINARY_DIR         = /path/to/my-project/build
PROJECT_BINARY_DIR       = /path/to/my-project/build
CMAKE_CURRENT_BINARY_DIR = /path/to/my-project/build/src

Prefer PROJECT_SOURCE_DIR when referring to the root of the current project, and CMAKE_CURRENT_SOURCE_DIR when referring to files located beside the current CMakeLists.txt. For reusable modules, CMAKE_CURRENT_LIST_DIR is often the safest choice.

zhuang@linux:~/notes/learn-some-cmake/$ comments