Understanding CMake: Core Principles and Basic Syntax

1. Core Principles of CMake

CMake is not a build tool (like make or ninja), but rather a build system generator, such as generating Makefiles.

Its core working principle can be summarized in the following three steps:

1. Configuration:

• You write a script file named CMakeLists.txt that describes your project structure, source files, dependencies, etc.
• Execute the cmake /path/to/source command.
• CMake reads the CMakeLists.txt file and analyzes and configures based on the current platform (Windows, Linux, macOS) and generator (Visual Studio, Makefiles, Ninja, etc.).
• It checks the availability of compilers, linkers, third-party libraries, etc. This stage generates CMakeCache.txt and some other files.

2. Generation:

• After a successful configuration phase, CMake will generate the necessary native build files for the corresponding platform and generator based on the analysis results from the previous step.
• On Linux/macOS, it defaults to generating a Makefile.
• On Windows, it can generate a Visual Studio .sln solution file.
• You can also specify to generate files for faster build systems like Ninja.

3. Build:

• Now, you no longer use CMake, but rather the corresponding native build tool for your platform to compile and link your project.
• For example, in the directory where the Makefile was generated, you just need to enter the make command to start compiling.
• In the directory where the Visual Studio solution was generated, you can use the MSBuild command or directly open it in the VS IDE to compile.

Simple Analogy: CMake is like a translator and a blueprint designer. You write your project requirements in CMakeLists.txt (a universal language), and CMake “translates” it into the “construction drawings” that the “foremen” (make, ninja, MSBuild) on different “construction sites” (operating systems) can understand (Makefile, .ninja, .sln). Then the “foremen” are responsible for the actual “construction” (compilation, linking).

Core Advantage: Cross-platform. Developers only need to maintain one universal CMakeLists.txt file to generate the corresponding build files on various platforms, greatly simplifying the build management of cross-platform projects.

2. Basic Syntax of CMake

The syntax of CMake is very intuitive, mainly consisting of Commands, Variables, and Comments.

1. Commands:

• The format is similar to function calls:command_name(parameter1 parameter2 ...).
• Case insensitive, but it is generally recommended to use all lowercase, for example, project(), add_executable().
• Command parameters are separated by spaces or semicolons ;.

2. Variables:

• Set using the set() command:set(MY_VARIABLE "some value").
• Referenced using ${} syntax:message(${MY_VARIABLE}).
• Variable types are usually strings.

3. Comments:

• Use the # symbol for single-line comments.
• # This is a comment

4. Control Flow:

• Supports conditional statements (if(), else(), endif()) and loops (foreach(), endforeach(), while(), endwhile()).

3. Common Commands and Variables

Below is a simple project CMakeLists.txt example that includes the most core and commonly used commands:

# 1. Specify the minimum required version of CMake
cmake_minimum_required(VERSION 3.10)

# 2. Define the project name, version, and programming languages used (C/CXX, etc.)
project(MyProject VERSION 1.0 DESCRIPTION "A simple project" LANGUAGES C CXX)

# 3. Set the C++ standard (very common!)
set(CMAKE_CXX_STANDARD 11) # or 14, 17, 20...
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# 4. Add all .cpp files in the current directory to the SOURCES variable
file(GLOB SOURCES "src/*.cpp")

# 5. Add an executable target named hello_world, built from the source files in the SOURCES variable
add_executable(hello_world ${SOURCES})

# 6. Add header file search paths for the target
#    PUBLIC means that not only hello_world will use it, but also other targets linking to hello_world will use it
target_include_directories(hello_world
    PUBLIC
        ${PROJECT_SOURCE_DIR}/include
)

# 7. If you need to link a library
# 7.1 First find the library (e.g., find the Threads library on the system)
find_package(Threads REQUIRED)

# 7.2 Then link the library to your target
target_link_libraries(hello_world
    PRIVATE
        Threads::Threads # Link the Threads library
)

# 8. Add a subdirectory, which must also have a CMakeLists.txt
# add_subdirectory(mylib)

Detailed Explanation of Core Commands:

• cmake_minimum_required(VERSION x.x): Must be placed at the top, specifying the required CMake version.
• project(<PROJECT-NAME>): Defines the project name, which sets some key variables, such as PROJECT_SOURCE_DIR (current project source path) and PROJECT_BINARY_DIR (build output path).
• add_executable(<name> <sources>): Defines an executable build target.
• add_library(<name> [STATIC|SHARED] <sources>): Defines a library build target (static library .a/.lib or dynamic library .so/.dll).
• target_include_directories(<target> [PUBLIC|PRIVATE|INTERFACE] <dirs>): Modern CMake best practice, specifies header file include directories for specific targets. Avoids the old global command include_directories().
• target_link_libraries(<target> [PUBLIC|PRIVATE|INTERFACE] <libraries>): Modern CMake best practice, specifies libraries to link for specific targets. Avoids the old global command link_libraries().
• find_package(<PackageName> REQUIRED): Finds external dependency packages in the system (like OpenCV, Boost, etc.).REQUIRED means it will error out if not found.
• set(<variable> <value>): Sets a variable.
• message(<mode> "message to display"): Prints a message for debugging (STATUS) or error (FATAL_ERROR).

Common Variables:

• CMAKE_CXX_STANDARD: Sets the C++ standard.
• CMAKE_BUILD_TYPE: Sets the build type, such as Debug, Release, RelWithDebInfo, MinSizeRel.
• CMAKE_CXX_FLAGS: Sets the flags for the C++ compiler.
• PROJECT_SOURCE_DIR: Path to the project root directory.
• PROJECT_BINARY_DIR: Path to the build output directory (the directory where the cmake command is run).
• CMAKE_PREFIX_PATH: Sets the path for find_package to search for third-party libraries, for example, set(CMAKE_PREFIX_PATH "/path/to/your/lib").

4. Summary and Usage Process

1. Write CMakeLists.txt: Create this file in your project root directory, using the commands above to describe your project.

2. Create a build directory and configure:

mkdir build &amp;&amp; cd build       # Strongly recommended! Out-of-source build to keep the source directory clean
cmake ..                     # .. indicates that CMakeLists.txt is in the parent directory

3. Generate the build system and compile:

cmake --build .              # Use CMake to call the underlying build tool (generic)
# or
make                         # If a Makefile was generated

4. Run the program:

./hello_world                # Find the generated executable in the build directory

I hope this brief overview helps you quickly understand the core concepts and workings of CMake!