In-Depth Analysis of CMake Build Process: From Fundamentals to Complex Projects

1. Analysis of the Project Structure After CMake Build

1.1 Directory Structure After CMake Build

After CMake build is complete, a directory named build will be generated in the root directory of the project. This directory is where all intermediate files and final target files generated during the CMake build process are stored. Below, we will analyze the structure of this directory in detail.

First, let’s take a look at the first-level subdirectories of the build directory:

• CMakeFiles: This directory contains temporary files generated by CMake during the build process, including the results of compiler checks and the results of Find modules. These files are mainly for CMake’s own needs, and generally, we do not need to pay attention to the contents of this directory.

• Testing: If your project includes CTest tests, this directory will be generated. It contains the results of all CTest tests.

• bin: This directory contains all executable files. If your CMake project includes multiple executable files, they will all be placed in this directory.

• lib: This directory contains all library files. Whether static libraries or dynamic libraries, they will be placed in this directory.

Next, let’s delve into the CMakeFiles directory and take a look at its second-level subdirectories:

• project.dir: This directory contains temporary files from the project build process, such as .o files and .d files. These files are generated by the compiler when compiling source code.

• CMakeOutput.log: This file records the output information from CMake during the configuration process, including results from compiler checks and Find module searches.

• CMakeError.log: This file records error messages encountered by CMake during the configuration process.

The above outlines the basic situation of the directory structure after CMake build. In actual projects, more subdirectories and files may be generated based on specific project needs. However, these basic directories and files are what you will see in any project that uses CMake for building.

1.2 Types of Files Generated by the Build and Their Functions

During the CMake build process, various types of files are generated, each with its specific function. Below, we will analyze these file types and their functions in detail.

• CMakeFiles directory: This directory contains temporary files generated by CMake during the build process, including results from compiler checks and Find module searches. These files are mainly for CMake’s own needs, and generally, we do not need to pay attention to the contents of this directory.

• project.dir directory: This directory contains temporary files from the project build process, such as .o files and .d files. These files are generated by the compiler when compiling source code.

• CMakeOutput.log file: This file records the output information from CMake during the configuration process, including results from compiler checks and Find module searches.

• CMakeError.log file: This file records error messages encountered by CMake during the configuration process.

• Testing directory: If your project includes CTest tests, this directory will be generated. It contains the results of all CTest tests.

• bin directory: This directory contains all executable files. If your CMake project includes multiple executable files, they will all be placed in this directory.

• lib directory: This directory contains all library files. Whether static libraries or dynamic libraries, they will be placed in this directory.

The above outlines the main types of files generated during the CMake build process and their functions. Understanding the role of these files can help us better comprehend the CMake build process.

1.3 The Relationship Between CMakeLists.txt and the Generated Makefile

In the CMake build system, there is a close relationship between the CMakeLists.txt file and the generated Makefile. Below, we will analyze this relationship in detail.

CMakeLists.txt is the core file of the CMake build system, defining the build rules and dependencies of the project. When executing the CMake command, CMake reads the CMakeLists.txt file, parses the build rules and dependencies within it, and then generates the corresponding Makefile.

The Makefile is generated by CMake based on the CMakeLists.txt file, and it is a build script that the Make build tool can read directly. The Makefile contains specific compile commands and link commands, as well as dependencies between source files and target files.

In a CMake project, there are usually multiple CMakeLists.txt files, and each directory can contain one CMakeLists.txt file. The build rules and dependencies defined in these CMakeLists.txt files will be merged by CMake to generate one or more Makefiles.

If a CMake project has only one CMakeLists.txt file, CMake will generate one Makefile. If a CMake project has multiple CMakeLists.txt files, CMake will generate a Makefile in each directory where a CMakeLists.txt file is located. The Makefile in the top-level directory is the main Makefile, which will call the Makefiles in other directories.

In summary, the relationship between the CMakeLists.txt file and the generated Makefile is as follows: the CMakeLists.txt file defines the build rules and dependencies of the project, CMake generates the Makefile based on the CMakeLists.txt file, and then Make executes specific build tasks according to the Makefile.

Need C/C++ Linux server architect learning materials? Add group 812855908 to get them (materials include C/C++, Linux, Golang technology, Nginx, ZeroMQ, MySQL, Redis, FastDFS, MongoDB, ZK, streaming media, CDN, P2P, K8S, Docker, TCP/IP, coroutines, DPDK, FFmpeg, etc.), free sharing.

2. In-Depth Understanding of the Makefile Generated by CMake

2.1 Basic Structure and Principles of Makefile

Makefile is the configuration file for the GNU make tool, defining a set of rules to specify which files need to be updated and how to update those files. In C++ projects, Makefile is commonly used to compile source code and generate executable files.

The basic structure of a Makefile includes three parts: Target, Dependencies, and Commands.

• Target: This is the name of the file to be generated. It can be an object file or an executable file.

• Dependencies: These are the source files required by the target file. If any dependency file is newer than the target file, the target file needs to be regenerated.

• Commands: These are the shell commands that need to be executed to generate the target file. These commands must start with a Tab character.

Below is a simple example of a Makefile:

target: dependencies
    commands

In CMake, the directives in the CMakeLists.txt file will be converted into targets, dependencies, and commands in the Makefile. For example, the add_executable directive will generate a target, the target_link_libraries directive will generate dependencies, and the actual compile and link commands will be automatically generated by CMake.

Understanding the basic structure and principles of Makefile is crucial for a deeper understanding of the Makefile generated by CMake. In the next section, we will further explore the analysis of Makefiles generated by multiple CMakeLists.txt files.

2.2 Analysis of Makefiles Generated by Multiple CMakeLists.txt

In large C++ projects, there are usually multiple CMakeLists.txt files, each located in its own directory. This structure helps maintain modularity in the project, allowing each part to be built and tested independently.

When running the CMake command, it will first look for the CMakeLists.txt file in the root directory, then recursively process the CMakeLists.txt files in each subdirectory. Each CMakeLists.txt file will generate a corresponding Makefile.

During this process, CMake processes the directives in the CMakeLists.txt files, such as add_executable, add_library, target_link_libraries, etc., and converts these directives into targets, dependencies, and commands in the Makefile.

For example, if we have the following directory structure:

project/
├── CMakeLists.txt
├── main.cpp
└── module/
    ├── CMakeLists.txt
    └── module.cpp

In the root directory’s CMakeLists.txt file, we might have the following directives:

add_executable(main main.cpp)
add_subdirectory(module)
target_link_libraries(main module)

In the module directory’s CMakeLists.txt file, we might have the following directive:

add_library(module module.cpp)

In this example, CMake will generate two Makefiles, one in the project directory and one in the project/module directory. In the Makefile in the project directory, there will be a target named main, which depends on main.cpp and the library generated in the module directory’s Makefile. In the Makefile in the project/module directory, there will be a target named module, which depends on module.cpp.

Through this approach, CMake enables each subdirectory to be built independently while ensuring the build order of the entire project.

2.3 The Correspondence Between CMake and Makefile

CMake is a cross-platform build system whose main task is to generate appropriate Makefile files according to user requirements. CMake understands user needs by reading the CMakeLists.txt file and then generates the corresponding Makefile files.

There is a clear correspondence between CMake and Makefile. Each directive in the CMakeLists.txt file has a corresponding representation in the generated Makefile. Below, we will look at some common CMake directives and their corresponding relationships in the Makefile:

• add_executable: This CMake directive is used to define a target executable file. In the generated Makefile, this target will be defined as a rule, where the target is the executable file, the dependencies are the source files, and the commands are the compile commands.

• add_library: This CMake directive is used to define a target library file. In the generated Makefile, this target will also be defined as a rule, where the target is the library file, the dependencies are the source files, and the commands are the compile commands.

• target_link_libraries: This CMake directive is used to define the libraries linked to the target. In the generated Makefile, this directive will affect the link commands, which will include the corresponding library files.

• add_subdirectory: This CMake directive is used to add a subdirectory. In the generated Makefile, this directive will result in a new Makefile being generated in the corresponding subdirectory.

By understanding the correspondence between CMake and Makefile, we can better understand how CMake works and how to write effective CMakeLists.txt files. In the next chapter, we will further explore the underlying principles of the CMake build process.

3. Underlying Principles of the CMake Build Process

3.1 Basic Flow of the CMake Build Process

The CMake build process can be divided into three main steps: Configuration, Generation, and Build. Below, we will analyze each step in detail.

1. Configuration

The configuration phase is the process where CMake parses the CMakeLists.txt file. During this phase, CMake reads the CMakeLists.txt file and executes the commands within it. These commands are mainly used to check the system environment (such as compilers, libraries, etc.), set build options, and define build targets (such as libraries, executables, etc.).

The CMakeLists.txt file is the core of CMake, defining the build rules and dependencies of the project. Each directory (including subdirectories) can have a CMakeLists.txt file. During the configuration phase, CMake will start from the CMakeLists.txt file in the top-level directory and recursively process each CMakeLists.txt file in the subdirectories.

2. Generation

The generation phase is the process where CMake generates the actual build files based on the results of the configuration phase. These build files are usually Makefile files, but can also be other types of build files, such as Ninja build files or Visual Studio project files, depending on the build tool you choose.

In the generation phase, CMake converts the build rules and dependencies defined in the CMakeLists.txt file into a form that the build tool can understand. For example, if the build tool you choose is Make, CMake will generate Makefile files. Each directory (including subdirectories) will generate a Makefile file.

3. Build

The build phase is the process where the build tool (such as Make, Ninja, or Visual Studio) compiles the source code and links to generate the target files based on the generated build files.

During the build phase, the build tool reads the generated build files and executes the actual compile and link operations according to the rules and dependencies defined within them. The build tool automatically handles dependencies, ensuring that all dependent target files are correctly compiled and linked before compiling and linking a target file.

The above outlines the basic flow of the CMake build process. Once we understand this flow, we can delve deeper into how CMake generates Makefile and the key steps in the CMake build process.

3.2 How CMake Generates Makefile

The process of CMake generating Makefile is completed during its generation phase. This process mainly involves CMake’s core component—the generator. Below, we will analyze this process in detail.

1. Selecting a Generator

At the beginning of the CMake generation phase, a generator needs to be selected. The generator is a core component of CMake that is responsible for converting the build rules and dependencies in the CMakeLists.txt file into a form that specific build tools can understand. CMake supports various generators, allowing it to generate Makefile files, Ninja build files, or Visual Studio project files, etc.

The way to select a generator is usually to specify it using the -G option when running the CMake command. For example, if you want to generate Unix-style Makefile files, you can use the “Unix Makefiles” generator with the following command:

cmake -G "Unix Makefiles"

If no generator is specified, CMake will choose a default generator, which is usually automatically selected based on your system environment.

2. Generating Makefile

Once the generator is selected, CMake will begin generating the Makefile files. During this process, CMake will traverse each directory (including subdirectories) in the project and process each CMakeLists.txt file.

For each CMakeLists.txt file, CMake will parse the commands within it and generate the corresponding Makefile based on the build rules and dependencies defined by those commands. Each CMakeLists.txt file will generate a Makefile file that contains the rules and commands needed to compile and link the target files in that directory.

When generating the Makefile files, CMake will automatically handle dependencies between target files. If a target file depends on other target files, CMake will add the corresponding dependency rules in the generated Makefile for that target file.

The above outlines the process of how CMake generates Makefile. Understanding this process allows us to better comprehend the key steps in the CMake build process and the relationship between CMake and Makefile.

3.3 Key Steps in the CMake Build Process

The key steps in the CMake build process mainly include the following aspects:

1. Parsing CMakeLists.txt Files

This is the first and most critical step in the CMake build process. The CMakeLists.txt file is the core of CMake, defining the build rules and dependencies of the project. CMake needs to parse this file to obtain all the information needed to build the project.

2. Checking System Environment

In the CMakeLists.txt file, there are usually commands to check the system environment, such as checking compilers and libraries. These commands will be executed during the CMake build process to ensure that the system environment meets the project’s build requirements.

3. Generating Build Files

CMake’s main task is to generate build files, which are usually Makefile files, but can also be other types of build files, such as Ninja build files or Visual Studio project files, depending on the build tool you choose. The process of generating build files is a key step in the CMake build process.

4. Executing Build Commands

Once the build files are generated, build commands can be executed. These build commands are usually executed by the build tool (such as Make, Ninja, or Visual Studio). The build tool will compile the source code and link to generate target files according to the rules and commands defined in the build files.

The above outlines the key steps in the CMake build process. Understanding these steps allows us to better comprehend how CMake works and how to use CMake for project building.

4. Application of CMake in Complex Projects

4.1 CMake Build Strategy in Complex Projects

In complex projects, CMake’s build strategy needs to be more refined and comprehensive. We need to consider the modularity of the project, dependencies, and potential platform differences. Below are some strategies and suggestions for using CMake in complex projects.

4.1.1 Modularized CMakeLists.txt

In large projects, we often see the project divided into multiple modules or subprojects, each with its own source code and dependencies. In this case, we can create a CMakeLists.txt file for each module, making the build process clearer and easier to manage.

For example, we can create a CMakeLists.txt file in each module’s directory, and then use the add_subdirectory() command in the project’s top-level CMakeLists.txt file to add these modules.

4.1.2 Managing Dependencies

In complex projects, different modules may have various dependencies. CMake provides several commands to help us manage these dependencies, such as the target_link_libraries() command, which can specify the libraries a target needs to link against.

When managing dependencies, an important principle to keep in mind is to make dependencies clear and intuitive. This means if module A depends on module B, we should explicitly state this dependency in module A’s CMakeLists.txt file.

4.1.3 Handling Platform Differences

In cross-platform projects, we may need to handle differences between platforms. CMake provides several variables and commands to help us manage these differences, such as the CMAKE_SYSTEM_NAME variable, which can be used to detect the current operating system, and the if() command, which can execute different commands based on different conditions.

When handling platform differences, we should avoid hardcoding specific platform information. Instead, we should use the variables and commands provided by CMake as much as possible, making our CMakeLists.txt files more universal and maintainable.

The above outlines some strategies and suggestions for using CMake in complex projects. In actual applications, we need to adjust and optimize our CMake build strategies according to the specific circumstances and requirements of the project.

4.1.4 Using Modern CMake Commands

Modern versions of CMake provide new commands and features that can make our CMakeLists.txt files more concise and easier to understand. For example, the target_include_directories() command can specify a target’s header file search path, which is more flexible and intuitive than using the older include_directories() command.

When using modern CMake commands, an important principle to keep in mind is to prefer target properties over global variables. This is because target properties can make our CMakeLists.txt files more modular and easier to understand and maintain.

4.1.5 Leveraging CMake’s Scripting Capabilities

CMake is not only a build tool, but also a scripting language. We can leverage CMake’s scripting capabilities to implement complex build logic, such as using commands like if() and foreach() to write loops and conditional statements.

When using CMake’s scripting capabilities, an important principle to keep in mind is to avoid overly complex script logic. Overly complex script logic may make our CMakeLists.txt files difficult to understand and maintain. Instead, we should use the commands and features provided by CMake as much as possible, making our CMakeLists.txt files more concise and easier to understand.

The above outlines some strategies and suggestions for using CMake in complex projects. In actual applications, we need to adjust and optimize our CMake build strategies according to the specific circumstances and requirements of the project.

4.2 Management of Multiple CMakeLists.txt in Complex Projects

In large complex projects, we often have multiple CMakeLists.txt files, each located in its own subdirectory. These CMakeLists.txt files collectively define the build rules for the entire project. Managing these CMakeLists.txt files is an important task, and the following are some strategies and suggestions.

4.2.1 Modular Management

Each CMakeLists.txt file should only be responsible for managing the source code and dependencies in its own directory. This keeps the content of each CMakeLists.txt file concise and makes it easier to understand and maintain the build rules for each module.

4.2.2 Unified Build Rules

Although each CMakeLists.txt file has its own build rules, we should try to keep these build rules consistent. This makes our build process more predictable and easier to manage and maintain.

4.2.3 Leveraging CMake’s Package Management Features

CMake provides several commands and features to help us manage project dependencies, such as the find_package() command to find and load external libraries. We should leverage these commands and features as much as possible to make our CMakeLists.txt files more concise and avoid common dependency issues.

4.2.4 Avoid Hard-Coded Paths

In CMakeLists.txt files, we should avoid hardcoding paths as much as possible. Hardcoded paths may make our build process dependent on a specific directory structure, reducing the portability of our build rules. Instead, we should use the variables and commands provided by CMake to specify paths, making our CMakeLists.txt files more universal and maintainable.

The above outlines some strategies and suggestions for managing multiple CMakeLists.txt files in complex projects. In actual applications, we need to adjust and optimize our management strategies according to the specific circumstances and requirements of the project.

4.3 Best Practices of CMake in Large Projects

When using CMake in large projects, we need to follow some best practices to ensure the efficiency, stability, and maintainability of the build process. Below are some best practices for using CMake in large projects.

4.3.1 Use the Latest Version of CMake

Whenever possible, use the latest version of CMake. New versions of CMake usually include new features and improvements that can make our build process more efficient and stable. Additionally, new versions of CMake may fix issues and defects present in older versions.

4.3.2 Avoid Modifying Compiler Flags in CMakeLists.txt Files

Directly modifying compiler flags in CMakeLists.txt files can lead to issues. For example, this may override compiler flags specified by users on the command line or cause inconsistent build behavior across different platforms. Instead, we should use the commands and features provided by CMake to manage compiler flags, such as the target_compile_options() command.

4.3.3 Use CMake’s Testing Features

CMake provides several commands and features to help us manage and run tests, such as the enable_testing() command and the add_test() command. We should leverage these commands and features to make our testing process more automated and controllable.

4.3.4 Use CMake’s Installation Features

CMake provides several commands and features to help us manage the installation process of the project, such as the install() command. We should leverage these commands and features to make our installation process more automated and controllable.

The above outlines some best practices for using CMake in large projects. In actual applications, we need to adjust and optimize our build processes according to the specific circumstances and requirements of the project.

5. Detailed Explanation of the Makefile Generated by CMake

5.1 How CMake Translates to Generate Makefile

Before delving into how CMake translates to generate Makefile, let us first look at the relationship between CMake and Makefile. As illustrated below, CMake generates the corresponding Makefile by parsing the CMakeLists.txt file, then executes the Makefile for compilation and linking, ultimately generating the executable file.

The main task of CMake is to parse the CMakeLists.txt file and translate it into Makefile. The CMakeLists.txt file is the core of CMake, defining the build rules of the project, including the project’s directory structure, source files to be compiled, dependencies, compilation parameters, and more. CMake reads the CMakeLists.txt file to understand these build rules and then generates the corresponding Makefile.

During the process of generating the Makefile, CMake performs a series of translation operations. These operations mainly include:

1. Parsing CMakeLists.txt file: CMake first reads the CMakeLists.txt file, parses the commands and parameters within it, and understands the project’s build rules.

2. Generating Makefile: Based on the parsed build rules, CMake generates the corresponding Makefile. This Makefile contains all the compile and link commands, as well as the dependencies between source files and target files.

3. Handling dependencies: During the process of generating the Makefile, CMake handles the dependencies between source files. If one source file depends on another, the compile command for that source file will depend on the compile command of the other source file in the Makefile.

4. Setting compilation parameters: CMake also sets the compilation parameters in the Makefile, including compiler options, linker options, etc. These parameters will affect the compilation and linking process.

The above outlines the basic process of how CMake translates to generate Makefile. In subsequent sections, we will delve into the detailed structure and principles of Makefile, as well as advanced topics such as using external Makefile in CMake.

5.2 Detailed Analysis of Makefile

Makefile is a script file executed by the make tool, describing a set of targets and the rules needed to build those targets. In the Makefile generated by CMake, each target usually corresponds to one or more source files, while the rules describe how to generate targets from these source files.

Below is a simple example of a Makefile:

all: hello

hello: main.o function.o
    g++ main.o function.o -o hello

main.o: main.cpp
    g++ -c main.cpp

function.o: function.cpp
    g++ -c function.cpp

clean:
    rm *.o hello

In this example, all, hello, main.o, function.o, and clean are all targets, while the content following each target describes the rules for building that target. For instance, the rule for the hello target is g++ main.o function.o -o hello, which tells the make tool how to generate the hello target from main.o and function.o.

In the Makefile generated by CMake, these rules will be more complex as they need to handle the project’s dependencies, compilation parameters, etc. However, the basic structure and principles remain the same: each target has a set of rules that describe how to generate the target from source files.

5.3 How CMake Translates to Generate Makefile

Of course, let’s delve deeper into the relationship between some CMake commands and the generated Makefile.

1. add_executable: This command in CMake is used to define a target executable file. For example, add_executable(hello main.cpp) defines a target named hello, which is generated from the source file main.cpp. In the generated Makefile, this command is translated into a compile command like $(CXX) $(CXXFLAGS) -o hello main.cpp. This command tells the make tool to compile main.cpp using the C++ compiler (CXX) and the compile options (CXXFLAGS), and output the file named hello.

2. add_library: This command in CMake is used to define a target library file. For example, add_library(mylib mylib.cpp) defines a target named mylib, generated from the source file mylib.cpp. In the generated Makefile, this command is translated into a library generation command like $(AR) $(ARFLAGS) mylib mylib.cpp. This command tells the make tool to generate the library mylib using the library generator (AR) and the library generation options (ARFLAGS).

3. target_link_libraries: This command in CMake is used to define the libraries linked to the target. For example, target_link_libraries(hello mylib) tells CMake that the hello target needs to link against the mylib library. In the generated Makefile, this command is translated into a link command like $(CXX) $(LDFLAGS) -o hello main.cpp -lmylib. This command tells the make tool to link the mylib library when linking hello.

The above outlines some basic relationships between CMake commands and the generated Makefile. In actual projects, these relationships may be more complex, as CMake and Makefile are both very powerful tools that provide many advanced features to handle various issues in projects. However, understanding these basic relationships is key to understanding CMake and Makefile.

5.4 Common Issues and Solutions in Makefile Generated by CMake

During the process of using CMake to generate Makefile, some common issues may arise. These issues may involve generating the Makefile, executing it, and handling dependencies. Below, we will detail these issues and their corresponding solutions.

1. Makefile generation failure: This is a common issue, usually caused by errors in the CMakeLists.txt file. The solution is to check the CMakeLists.txt file to ensure that the commands and parameters are correct.

2. Makefile execution error: This issue is usually caused by errors in the commands within the Makefile. The solution is to check the Makefile to ensure that the compile and link commands are correct.

3. Dependency handling error: This issue is usually caused by errors in CMake’s handling of dependencies between source files. The solution is to check the CMakeLists.txt file to ensure that the dependencies are correct.

The above outlines some common issues that may be encountered when using CMake to generate Makefile, along with their corresponding solutions. In practical use, other issues may arise, and in those cases, it is necessary to troubleshoot and resolve them based on the specific error messages.

6. Interaction Between CMake and External Makefile

6.1 How to Use External Makefile in CMake

To use external Makefile in CMake, we can use the add_custom_command and add_custom_target commands. These two commands can be used to execute custom build rules, such as running a script, creating a file, or running a Makefile.

6.1.1 add_custom_command

The add_custom_command command is used to define how to generate a file. This command has many parameters, but the most commonly used are OUTPUT, COMMAND, and DEPENDS.

• The OUTPUT parameter specifies the generated file.

• The COMMAND parameter specifies the command to generate the file, which can be any shell command.

• The DEPENDS parameter specifies the files that the generated file depends on.

For example, we can use the following command to run an external Makefile:

add_custom_command(
  OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/generated_file
  COMMAND make -C ${CMAKE_CURRENT_SOURCE_DIR}/external_project
  DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/external_project/Makefile
)

This command indicates that if generated_file does not exist or external_project/Makefile has any changes, the command make -C external_project will be executed to generate generated_file.

6.1.2 add_custom_target

However, add_custom_command will only be executed if its output file is used by other targets. If we want to execute a command every time we build, we need to use the add_custom_target command.

The add_custom_target command is used to define a custom target. This target does not generate any files and is not automatically executed during the build. We need to manually execute this target or add it as a dependency of other targets.

For example, we can use the following command to define a target that runs an external Makefile:

add_custom_target(
  run_external_makefile
  COMMAND make -C ${CMAKE_CURRENT_SOURCE_DIR}/external_project
)

This command defines a target named run_external_makefile. We can manually execute this target using the command make run_external_makefile.

If we want to execute this target every time we build, we can add it as a dependency of another target. For example, we can use the following command to add run_external_makefile as a dependency of my_target:

add_dependencies(my_target run_external_makefile)

Thus, every time we build my_target, the run_external_makefile target will be executed first.

The above outlines the basic methods for using external Makefile in CMake. In practical use, we may need to adjust the parameters of these commands according to specific requirements.

6.1.3 Other Parameters of add_custom_command

In addition to the OUTPUT, COMMAND, and DEPENDS parameters, the add_custom_command command has several other parameters that can control the behavior of the command.

• The WORKING_DIRECTORY parameter specifies the working directory of the command. If this parameter is not specified, the working directory of the command will be the current build directory.

• The COMMENT parameter specifies a comment that will be displayed in the console when the command is executed.

• The VERBATIM parameter controls whether the command’s parameters need to be escaped. If set to TRUE, the command’s parameters will be escaped, allowing for safe handling of parameters containing special characters.

For example, we can use the following command to run an external Makefile and display a comment:

add_custom_command(
  OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/generated_file
  COMMAND make -C ${CMAKE_CURRENT_SOURCE_DIR}/external_project
  DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/external_project/Makefile
  WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
  COMMENT "Running external Makefile"
  VERBATIM
)

This command indicates that if generated_file does not exist or external_project/Makefile has any changes, the command will be executed in the ${CMAKE_CURRENT_BINARY_DIR} directory to generate generated_file, displaying the comment “Running external Makefile”.

The above outlines the basic methods for using external Makefile in CMake. In practical use, we may need to adjust the parameters of these commands according to specific requirements.

6.2 How External Makefile Affects Makefile Generated by CMake

In CMake, we can use the add_custom_command or add_custom_target commands to insert an external Makefile, thereby affecting the Makefile generated by CMake. Below is a diagram of this process:

In this process, CMake first parses the CMakeLists.txt file and generates the CMakeCache.txt file. Then, based on the CMakeCache.txt file, CMake generates the Makefile. During the generation of the Makefile, CMake executes the add_custom_command or add_custom_target commands to insert the external Makefile.

The primary purpose of inserting an external Makefile is to add custom build rules. For example, we may need to execute special commands during the build process or generate special files. By inserting an external Makefile, we can execute these custom build rules during the CMake build process.

However, inserting an external Makefile may also bring some issues. For instance, if the build rules in the external Makefile conflict with the build rules generated by CMake, it may lead to build failures. Therefore, when inserting an external Makefile, we need to ensure that the build rules in the external Makefile are compatible with those generated by CMake.

In practical use, we may need to adjust the way we insert external Makefile according to specific requirements. For example, we can control the insertion position of the external Makefile or the execution method of the external Makefile by modifying the parameters of the add_custom_command or add_custom_target commands.

6.3 Advanced Techniques: Freely Control CMake Generation Rules

CMake provides a series of commands that allow us to freely control the generation rules. These commands can be used to define custom targets, add dependencies, set compilation options, and more. Below, we will introduce some advanced techniques that can help you better control CMake’s generation rules.

6.3.1 Custom Targets

In CMake, we can use the add_custom_target command to define a custom target. This target does not generate any files and is not automatically executed during the build. We need to manually execute this target or add it as a dependency of other targets.

For example, we can use the following command to define a target that runs an external Makefile:

add_custom_target(
  run_external_makefile
  COMMAND make -C ${CMAKE_CURRENT_SOURCE_DIR}/external_project
)

This command defines a target named run_external_makefile. We can manually execute this target using the command make run_external_makefile.

6.3.2 Adding Dependencies

In CMake, we can use the add_dependencies command to add dependencies between targets. This command accepts two or more parameters, with the first parameter being the target and the subsequent parameters being the targets it depends on.

For example, we can use the following command to add run_external_makefile as a dependency of my_target:

add_dependencies(my_target run_external_makefile)

Thus, every time we build my_target, the run_external_makefile target will be executed first.

6.3.3 Setting Compilation Options

In CMake, we can use the target_compile_options command to set the compilation options for a target. This command accepts two parameters, with the first parameter being the target and the second parameter being the compilation options.

For example, we can use the following command to set compilation options for my_target:

target_compile_options(my_target PRIVATE -Wall -Wextra)

This command will add the -Wall and -Wextra compilation options to my_target.

The above outlines some advanced techniques for freely controlling the generation rules in CMake. In practical use, we may need to adjust the parameters of these commands according to specific requirements.