add_executable

add_executable 是 CMake 用于定义一个可执行目标的命令。它指定了生成可执行文件所需的源文件。

基本语法

add_executable( [WIN32] [MACOSX_BUNDLE]
               [EXCLUDE_FROM_ALL]
               source1 source2 ... )

参数说明

• ：可执行目标的名称。
• WIN32：在 Windows 上创建一个窗口应用程序，而不是控制台应用程序。这仅影响 Windows 平台。
• MACOSX_BUNDLE：在 macOS 上创建一个应用程序包。
• EXCLUDE_FROM_ALL：不将目标包含在默认构建中，需要显式构建。
• source1 source2 ...：构成可执行文件的源文件列表。

使用示例

add_executable(MyApp main.cpp utils.cpp)

示例：创建一个 Windows GUI 应用

add_executable(MyApp WIN32 main.cpp)

示例：创建一个 macOS 应用程序包

add_executable(MyApp MACOSX_BUNDLE main.cpp)

通过这些参数，你可以灵活地定义不同类型的平台特定应用程序。

add_library

add_library 命令用于在 CMake 中定义一个库目标。你可以创建静态库、共享库或模块库。以下是 add_library 的基本用法和选项：

基本语法

add_library( [STATIC | SHARED | MODULE] [EXCLUDE_FROM_ALL]
              ...)

参数说明

• ：指定库的名称。
• STATIC：创建静态库（默认类型）。
• SHARED：创建共享库（动态库）。
• MODULE：创建模块库，通常用于插件。
• EXCLUDE_FROM_ALL：不将库添加到默认构建目标中。

示例

1.创建静态库

add_library(MyStaticLib STATIC utils.cpp helper.cpp)

2.创建共享库

add_library(MySharedLib SHARED utils.cpp helper.cpp)

3.创建模块库

add_library(MyModule MODULE plugin.cpp)

使用选项和属性

设置库的输出目录

set_target_properties(MySharedLib PROPERTIES
                      ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib
                      LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib
                      RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)

链接其他库

target_link_libraries(MySharedLib PUBLIC AnotherLib)

设置编译选项

target_compile_options(MyStaticLib PRIVATE -Wall -Wextra)

注意事项

• 库的类型（STATIC, SHARED, MODULE）通常在项目开始时决定，因为不同类型的库有不同的使用场景。
• 使用 target_link_libraries 可以指定库的依赖关系。
• 使用 target_include_directories 可以指定头文件搜索路径。

通过 add_library，你可以灵活地管理项目中的库构建，支持多种类型的库目标和配置选项。

add_library OBJECT 参数

在 CMake 中，add_library 的 OBJECT 参数用于创建对象库。对象库不会生成可链接的库文件，而是生成目标文件（.o 或 .obj），这些目标文件可以在其他目标中复用。

用法

add_library(MyObjectLib OBJECT file1.cpp file2.cpp)

特点

• 不生成库文件：对象库仅生成目标文件，不生成静态或动态库。
• 复用编译结果：可以在多个目标中复用相同的编译结果，避免重复编译。
• 提高编译效率：减少编译时间和磁盘空间占用。

使用示例

假设你有一组源文件需要在多个可执行文件或库中使用：

# 创建对象库
add_library(MyObjectLib OBJECT common1.cpp common2.cpp)

# 使用对象库的目标文件
add_executable(MyExecutable main.cpp $)
add_library(MySharedLib SHARED $)

注意事项

• 依赖管理：对象库可以管理源文件的编译选项、头文件路径等，和普通库目标类似。
• 目标文件引用：使用 $ 引用对象库的目标文件。
• 不能直接链接：对象库不能被其他目标直接链接，只能通过目标文件引用。

对象库在需要复用一组源文件的编译结果时非常有用，尤其是在大型项目中，可以显著提高编译效率。

add_library INTERFACE 参数

在 CMake 中，add_library 的 INTERFACE 参数用于创建接口库。接口库本身不包含源文件或生成库文件，而是用于定义和传播编译选项、链接库、包含路径等。

用法

add_library(MyInterfaceLib INTERFACE)

特点

• 不生成输出文件：接口库不生成任何可链接的输出文件。
• 传播属性：主要用于传播编译选项和其他属性给依赖它的目标。
• 依赖管理：可以通过接口库管理项目的依赖关系。

使用示例

# 创建接口库
add_library(MyInterfaceLib INTERFACE)

# 设置接口库的属性
target_include_directories(MyInterfaceLib INTERFACE include/)
target_compile_definitions(MyInterfaceLib INTERFACE USE_MY_FEATURE)

# 使用接口库
add_executable(MyApp main.cpp)
target_link_libraries(MyApp PRIVATE MyInterfaceLib)

常用属性

• target_include_directories：设置包含路径。
• target_compile_definitions：设置编译定义。
• target_compile_options：设置编译选项。
• target_link_libraries：设置链接库。

注意事项

• 仅用于属性传播：接口库不能包含源文件或生成实际的库文件。
• 灵活性：非常适合用于模块化项目，帮助在不同组件之间传播编译选项和依赖。

接口库在需要共享编译设置或依赖关系时非常有用，尤其是在大型项目或模块化设计中。

add_library 库类型汇总

以下是 CMake 中 add_library 的不同参数类型的比较：

说明

• 静态库 (STATIC)：用于将库代码编译到目标中，生成的可执行文件包含所有依赖的库代码。
• 动态库 (SHARED)：库代码在运行时加载，节省内存并允许库的更新而不重新编译依赖的程序。
• 模块库 (MODULE)：通常用于插件机制，动态加载而不是链接。
• 未知类型 (UNKNOWN)：库类型不明确，通常由其他配置或上下文决定。
• 对象库 (OBJECT)：用于将源文件编译为对象文件，供其他目标（如静态或动态库）使用。
• 接口库 (INTERFACE)：用于传播编译选项和依赖关系，不生成实际的库文件。

每种类型适用于不同的场景，选择时需根据项目需求和构建策略进行权衡。

aux_source_directory 是 CMake 中的一个命令，用于自动收集指定目录中的源文件并将其添加到一个变量中。这个命令可以简化管理大量源文件的过程。

用法

aux_source_directory( )

• ：指定要搜索源文件的目录。
• ：用于存储找到的源文件列表的变量名。

示例

假设你有一个目录 src，其中包含多个源文件：

aux_source_directory(src SRC_LIST)
add_executable(MyApp ${SRC_LIST})

注意事项

1. 文件类型：aux_source_directory 仅会查找符合源文件扩展名的文件（如 .cpp, .c）。
2. 递归搜索：这个命令不会递归搜索子目录，只会在指定目录中查找文件。
3. 可读性：虽然 aux_source_directory 可以减少手动列出文件的工作量，但在大型项目中，显式列出源文件可能更有助于项目的可读性和维护性。

替代方法

对于大型项目，手动管理源文件或使用 file(GLOB ...) 可能会更清晰，尤其是当需要递归搜索或更复杂的文件组织时：

file(GLOB_RECURSE SRC_LIST "src/*.cpp")
add_executable(MyApp ${SRC_LIST})

使用 aux_source_directory 可以快速收集源文件，但在复杂项目中，考虑到可维护性和透明度，可能需要更灵活的方法。

add_subdirectory

add_subdirectory 是 CMake 中用于在项目中添加子目录的命令。它允许你在主项目中包含其他目录中的 CMakeLists.txt 文件，从而组织和构建大型项目。

用法

add_subdirectory(source_dir [binary_dir] [EXCLUDE_FROM_ALL])

参数说明

• source_dir：指定子目录的路径，必须包含一个 CMakeLists.txt 文件。
• binary_dir：可选参数，指定生成文件的输出目录。如果不指定，使用 source_dir。
• EXCLUDE_FROM_ALL：可选标志，表示不将子目录中的目标添加到默认构建中。

示例

假设项目结构如下：

/MyProject
  /src
    CMakeLists.txt
  /tests
    CMakeLists.txt
  CMakeLists.txt

顶层的 CMakeLists.txt 可以这样写：

cmake_minimum_required(VERSION 3.10)
project(MyProject)

add_subdirectory(src)
add_subdirectory(tests)

说明

• 模块化管理：通过 add_subdirectory，可以将项目拆分为多个模块或组件，每个模块有自己的 CMakeLists.txt 文件。
• 独立构建：每个子目录可以独立定义自己的目标和设置。
• 层次化结构：有助于保持项目结构的清晰和可维护性。

注意事项

• 确保每个子目录中有一个 CMakeLists.txt 文件。
• 使用相对路径或绝对路径都可以，但通常建议使用相对路径以保持项目的可移植性。
• EXCLUDE_FROM_ALL 标志可以用于测试目录或不常用的模块，以避免在默认构建中包含它们。

通过合理使用 add_subdirectory，可以有效地管理复杂项目的构建过程。

get_property 和 set_property 是 CMake 中用于获取和设置属性的命令。它们可以用于目标、目录、源文件等多种实体。

set_property

用于为指定的实体设置属性。

基本用法

set_property(TARGET target_name PROPERTY property_name value)
set_property(SOURCE source_file PROPERTY property_name value)
set_property(DIRECTORY dir_path PROPERTY property_name value)

示例

set_property(TARGET MyLibrary PROPERTY VERSION 1.0.0)
set_property(SOURCE main.cpp PROPERTY COMPILE_FLAGS "-Wall")

get_property

用于获取指定实体的属性。

基本用法

get_property(var_name TARGET target_name PROPERTY property_name)
get_property(var_name SOURCE source_file PROPERTY property_name)
get_property(var_name DIRECTORY dir_path PROPERTY property_name)

示例

get_property(version TARGET MyLibrary PROPERTY VERSION)
message("MyLibrary version: ${version}")

说明

• TARGET：指目标，如库或可执行文件。
• SOURCE：指源文件。
• DIRECTORY：指目录。
• PROPERTY：指定要设置或获取的属性名称。

注意事项

• 确保属性名称与实体类型匹配。
• get_property 会将结果存储在指定的变量中。
• 使用这些命令可以灵活地控制项目的构建行为。

通过合理使用 get_property 和 set_property，可以在 CMake 中实现更细粒度的构建配置和管理。

get_directory_properties 和 set_directory_properties

以下是一些实际应用 get_directory_properties 和 set_directory_properties 的示例：

示例 1：设置和获取包含目录

目标

在一个项目中，设置某个目录的包含目录，并在其他地方获取和使用这些包含目录。

CMakeLists.txt

# 设置 src 目录的包含目录
set_directory_properties(DIRECTORY ${CMAKE_SOURCE_DIR}/src PROPERTIES INCLUDE_DIRECTORIES ${CMAKE_SOURCE_DIR}/include)

# 获取并打印 src 目录的包含目录
get_directory_property(includes DIRECTORY ${CMAKE_SOURCE_DIR}/src PROPERTY INCLUDE_DIRECTORIES)
message("Include directories for src: ${includes}")

示例 2：条件编译

目标

根据目录属性设置编译定义，实现条件编译。

CMakeLists.txt

# 设置编译定义 DEBUG_MODE
set_directory_properties(PROPERTIES COMPILE_DEFINITIONS "DEBUG_MODE")

# 在代码中使用 DEBUG_MODE 进行条件编译
get_directory_property(definitions PROPERTY COMPILE_DEFINITIONS)
if("DEBUG_MODE" IN_LIST definitions)
    message("Debug mode is enabled")
endif()

示例 3：统一编译选项

目标

为某个目录及其子目录中的所有目标设置统一的编译选项。

CMakeLists.txt

# 设置编译选项
set_directory_properties(PROPERTIES COMPILE_OPTIONS "-Wall;-Wextra")

# 获取并打印当前目录的编译选项
get_directory_property(compile_options PROPERTY COMPILE_OPTIONS)
message("Compile options: ${compile_options}")

示例 4：跨平台编译配置

目标

根据操作系统设置不同的目录属性。

CMakeLists.txt

if(WIN32)
    set_directory_properties(PROPERTIES COMPILE_DEFINITIONS "WINDOWS_BUILD")
elseif(UNIX)
    set_directory_properties(PROPERTIES COMPILE_DEFINITIONS "UNIX_BUILD")
endif()

# 获取并打印编译定义
get_directory_property(definitions PROPERTY COMPILE_DEFINITIONS)
message("Compile definitions: ${definitions}")

这些示例展示了如何使用 set_directory_properties 和 get_directory_properties 在项目中设置和获取目录级别的编译配置，从而实现更灵活的构建系统管理。

target_link_libraries

target_link_libraries 是 CMake 中用于指定目标（如可执行文件或库）所需链接的库的命令。这个命令可以设置目标的链接依赖关系，包括系统库、第三方库或其他项目中的库。

基本用法

target_link_libraries(target_name [item1 [item2 [...]]])

参数说明

• target_name：要链接库的目标名称。
• item1, item2, ...：要链接的库，可以是：
• 库名称（如 mylib）。
• 库路径（如 /path/to/mylib.a）。
• 链接选项（如 -lm）。
• 其他目标（如 another_target）。

关键字

• PRIVATE：库仅在目标内部可见，不会传播到依赖该目标的其他目标。
• PUBLIC：库在目标内部可见，同时也会传播到依赖该目标的其他目标。
• INTERFACE：库不会在目标内部使用，但会传播到依赖该目标的其他目标。

示例

示例 1：简单链接

add_executable(my_app main.cpp)
target_link_libraries(my_app mylib)

示例 2：使用关键字

add_library(mylib STATIC mylib.cpp)
add_executable(my_app main.cpp)

# mylib 对 my_app 是 PRIVATE 的，mylib 不会传播
target_link_libraries(my_app PRIVATE mylib)

# mylib 对 my_app 是 PUBLIC 的，mylib 会传播
target_link_libraries(my_app PUBLIC mylib)

# mylib 对 my_app 是 INTERFACE 的，mylib 会传播，但不在 my_app 中使用
target_link_libraries(my_app INTERFACE mylib)

示例 3：链接系统库

add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE m)

注意事项

• 确保目标和库名称正确。
• 根据需求选择合适的关键字（PRIVATE、PUBLIC、INTERFACE）。
• 链接顺序可能会影响构建，通常依赖项放在后面。

target_link_libraries 是 CMake 项目中管理和配置依赖关系的核心工具，理解其用法有助于构建复杂的项目结构。

add_dependencies

add_dependencies 是 CMake 中用于指定目标之间构建依赖关系的命令。它确保一个目标在另一个目标之前构建。

基本用法

add_dependencies(target-name dependency1 dependency2 ...)

参数说明

• target-name：需要依赖其他目标的目标名称。
• dependency1, dependency2, ...：target-name 所依赖的其他目标名称。

示例

示例 1：简单用法

add_executable(main_app main.cpp)
add_library(helper_lib helper.cpp)

# Ensure helper_lib is built before main_app
add_dependencies(main_app helper_lib)

在这个例子中，main_app 会在 helper_lib 构建完成后再进行构建。

使用场景

• Custom Commands: 当你使用 add_custom_command 和 add_custom_target 时，add_dependencies 可以确保自定义命令或目标在特定顺序内执行。
• Complex Build Systems: 在复杂的构建系统中，明确目标之间的依赖关系有助于正确构建。

注意事项

• add_dependencies 只影响构建顺序，不会自动添加链接依赖。如果需要链接库，还需要使用 target_link_libraries。
• 确保依赖的目标已经被定义，否则会导致错误。

通过使用 add_dependencies，你可以更好地控制构建流程，确保构建顺序符合项目需求。

link_directories

link_directories 是 CMake 中用于指定链接库的搜索路径的命令。它设置全局范围的库目录，会影响到所有后续定义的目标。

基本用法

link_directories(directory1 directory2 ...)

参数说明

• directory1, directory2, ...：要添加的库目录路径列表。

示例

示例 1：简单用法

link_directories(${CMAKE_SOURCE_DIR}/lib)
add_executable(my_app main.cpp)
target_link_libraries(my_app mylib)

在这个例子中，CMake 会在 ${CMAKE_SOURCE_DIR}/lib 中查找 mylib。

注意事项

• link_directories 是全局性的，影响所有后续的目标。
• 使用时要小心，因为它可能导致意外链接到不正确的库，尤其是在有多个库版本时。

推荐做法

尽量避免使用 link_directories，而是使用 target_link_libraries 指定库的完整路径或通过 CMake 的 find_package、find_library 来管理库路径和依赖关系，从而提高项目的可维护性和可移植性。

link_libraries

link_libraries 是 CMake 中用于指定目标链接库的命令。它设置全局范围的链接库，会影响到所有后续定义的目标。

基本用法

link_libraries(library1 library2 ...)

参数说明

• library1, library2, ...：要链接的库名称或路径。

示例

示例 1：简单用法

link_libraries(mylib anotherlib)
add_executable(my_app main.cpp)

在这个例子中，my_app 会链接到 mylib 和 anotherlib。

注意事项

• link_libraries 是全局性的，影响所有后续的目标。
• 不推荐在现代 CMake 项目中使用这种方式，因为它可能导致意外的链接问题。

推荐用法

使用 target_link_libraries 可以更精细地控制每个目标的链接依赖：

add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE mylib anotherlib)

这样可以确保每个目标只链接其需要的库，避免全局设置带来的不必要的复杂性和潜在错误。

target_include_directories

target_include_directories 是 CMake 中用于为特定目标指定头文件搜索路径的命令。与全局性的 include_directories 不同，它仅影响指定的目标，从而提供更精细的控制。

基本用法

target_include_directories(target
                           [SYSTEM]
                           [BEFORE]
                           [PRIVATE|PUBLIC|INTERFACE]
                           dir1 [dir2 ...])

参数说明

• target：要设置包含目录的目标名称。
• dir1, dir2, ...：要添加的包含目录列表。
• SYSTEM：将目录标记为系统包含目录，抑制编译器对这些目录中头文件的警告。
• BEFORE：将目录添加到搜索路径的开头。
• PRIVATE：目录仅对目标可见，不会传播到依赖该目标的其他目标。
• PUBLIC：目录对目标可见，并传播到依赖该目标的其他目标。
• INTERFACE：目录不会在目标内部使用，但会传播到依赖该目标的其他目标。

示例

示例 1：简单用法

add_executable(my_app main.cpp)
target_include_directories(my_app PRIVATE ${CMAKE_SOURCE_DIR}/include)

示例 2：使用 PUBLIC

add_library(mylib mylib.cpp)
target_include_directories(mylib PUBLIC ${CMAKE_SOURCE_DIR}/include)

示例 3：使用 INTERFACE

add_library(mylib INTERFACE)
target_include_directories(mylib INTERFACE ${CMAKE_SOURCE_DIR}/include)

示例 4：标记为系统目录

add_executable(my_app main.cpp)
target_include_directories(my_app SYSTEM PRIVATE ${CMAKE_SOURCE_DIR}/third_party/include)

注意事项

• 使用 PRIVATE、PUBLIC 和 INTERFACE 可以精确控制包含目录的可见性。
• target_include_directories 提供的目标级别控制有助于避免全局设置导致的潜在问题。
• 推荐使用 target_include_directories 来替代 include_directories，以实现更好的项目结构管理。

include_directories

include_directories 是 CMake 中用于指定项目中包含文件的搜索路径的命令。它影响到编译器在寻找头文件时的路径设置。

基本用法

include_directories([AFTER|BEFORE] [SYSTEM] dir1 [dir2 ...])

参数说明

• dir1, dir2, ...：要添加的目录列表，编译器会在这些目录中查找头文件。
• AFTER/BEFORE：控制目录的搜索顺序。
• BEFORE：将目录添加到搜索路径的开头。
• AFTER：将目录添加到搜索路径的末尾（默认行为）。
• SYSTEM：将目录标记为系统包含目录，这样可以抑制编译器对这些目录中头文件的警告。

示例

示例 1：简单用法

include_directories(${CMAKE_SOURCE_DIR}/include)

示例 2：多个目录

include_directories(${CMAKE_SOURCE_DIR}/include ${CMAKE_SOURCE_DIR}/third_party/include)

示例 3：使用 BEFORE

include_directories(BEFORE ${CMAKE_SOURCE_DIR}/include)

示例 4：标记为系统目录

include_directories(SYSTEM ${CMAKE_SOURCE_DIR}/third_party/include)

注意事项

• include_directories 是全局性的，影响所有后续定义的目标。
• 对于现代 CMake 项目，推荐使用 target_include_directories 来设置目标级别的包含目录，以避免全局影响。

推荐用法

对于现代 CMake 项目，使用
target_include_directories 可以更好地控制目标的包含目录：

add_executable(my_app main.cpp)
target_include_directories(my_app PRIVATE ${CMAKE_SOURCE_DIR}/include)

这样可以更精确地管理每个目标的依赖关系，避免不必要的全局设置。

target_link_libraries

target_link_libraries 是 CMake 中用于指定目标（如可执行文件或库）所需链接的库的命令。这个命令可以设置目标的链接依赖关系，包括系统库、第三方库或其他项目中的库。

基本用法

target_link_libraries(target_name [item1 [item2 [...]]])

参数说明

• target_name：要链接库的目标名称。
• item1, item2, ...：要链接的库，可以是：
• 库名称（如 mylib）。
• 库路径（如 /path/to/mylib.a）。
• 链接选项（如 -lm）。
• 其他目标（如 another_target）。

关键字

• PRIVATE：库仅在目标内部可见，不会传播到依赖该目标的其他目标。
• PUBLIC：库在目标内部可见，同时也会传播到依赖该目标的其他目标。
• INTERFACE：库不会在目标内部使用，但会传播到依赖该目标的其他目标。

示例

示例 1：简单链接

add_executable(my_app main.cpp)
target_link_libraries(my_app mylib)

示例 2：使用关键字

add_library(mylib STATIC mylib.cpp)
add_executable(my_app main.cpp)

# mylib 对 my_app 是 PRIVATE 的，mylib 不会传播
target_link_libraries(my_app PRIVATE mylib)

# mylib 对 my_app 是 PUBLIC 的，mylib 会传播
target_link_libraries(my_app PUBLIC mylib)

# mylib 对 my_app 是 INTERFACE 的，mylib 会传播，但不在 my_app 中使用
target_link_libraries(my_app INTERFACE mylib)

示例 3：链接系统库

add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE m)

注意事项

• 确保目标和库名称正确。
• 根据需求选择合适的关键字（PRIVATE、PUBLIC、INTERFACE）。
• 链接顺序可能会影响构建，通常依赖项放在后面。

target_link_libraries 是 CMake 项目中管理和配置依赖关系的核心工具，理解其用法有助于构建复杂的项目结构。