关于CMake

关于CMake

cmake-help

核心内容

设置项目名称

# 设置项目名称
project(<PROJECT-NAME>
        [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]
        [DESCRIPTION <project-description-string>]
        [HOMEPAGE_URL <url-string>]
        [LANGUAGES <language-name>...])

目标程序

可执行程序

# 创建可执行程序 Target
add_executable(<name> [WIN32] [MACOSX_BUNDLE]
    [EXCLUDE_FROM_ALL]
    [source1] [source2 ...])

• 此操作将填充属性 SOURCES

静态/动态运行库

# 创建静态/动态运行库 Target
add_library(<name> [STATIC | SHARED| MODULE | OBJECT  | INTERFACE]
    [EXCLUDE_FROM_ALL]
    [IMPORTED [GLOBAL]]
    [<source>...])

• OBJECT : 源代码被编译成obj文件，但不会将目标文件打包成库文件。
• STATIC : 将多个obj文件打包成一个静态库文件。
• SHARED : 总是有一个关联的符号（symbols）导出。
• MODULE : 通常是指插件，没有输出任何符号（symbols）。
• INTERFACE : 并不直接创建输出，可在上面设置属性，像其他目标一样被用作 target_link_libraries(...) 的参数。
• IMPORTED : 通过设置名称以 IMPORTED_ 和 INTERFACE_ 开头的属性来指定导入的库的细节。
• add_library操作将填充属性 SOURCES

源文件

# 增加源文件
target_sources(<target>
    <INTERFACE|PUBLIC|PRIVATE> [items1...]
    [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])

• PRIVATE : 填充属性 SOURCES
• PUBLIC : 填充属性 SOURCES 和 INTERFACE_SOURCES
• INTERFACE: 填充属性 INTERFACE_SOURCES

SOURCES属性通常用于指定当前目录下的源文件，而INTERFACE_SOURCES属性可以从接口源目录导出源文件，以便共享给其他目标使用。

头文件（include）

# 头文件搜索目录
target_include_directories(<target> [SYSTEM] [AFTER|BEFORE]
    <INTERFACE|PUBLIC|PRIVATE> [items1...]
    [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])

• PRIVATE : 填充属性 INCLUDE_DIRECTORIES
• PUBLIC : 填充属性 INCLUDE_DIRECTORIES 和 INTERFACE_INCLUDE_DIRECTORIES
• INTERFACE: 填充属性 INTERFACE_INCLUDE_DIRECTORIES

库文件（library）

# 库文件搜索目录
target_link_directories(<target> [BEFORE]
    <INTERFACE|PUBLIC|PRIVATE> [items1...]
    [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])

• PRIVATE : 填充属性 LINK_DIRECTORIES
• PUBLIC : 填充属性 LINK_DIRECTORIES 和 INTERFACE_LINK_DIRECTORIES
• INTERFACE: 填充属性 INTERFACE_LINK_DIRECTORIES

# 连接库文件
target_link_libraries(<target>
    <PRIVATE|PUBLIC|INTERFACE> <item>...
    [<PRIVATE|PUBLIC|INTERFACE> <item>...]...)

• PRIVATE : 仅连接
• PUBLIC : 连接并创建接口
• INTERFACE: 仅创建接口

宏定义（definition）

target_compile_definitions(<target>
    <INTERFACE|PUBLIC|PRIVATE> <key>[=<value>] ...
    [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])

• PRIVATE : 填充属性 COMPILE_DEFINITIONS
• PUBLIC : 填充属性 COMPILE_DEFINITIONS 和 INTERFACE_COMPILE_DEFINITIONS
• INTERFACE: 填充属性 INTERFACE_COMPILE_DEFINITIONS

配置（property）

cmake-properties

# 获取配置
get_target_property(<outVar> <target> <property>)

# 写入配置
set_target_properties(target1 target2 ...
    PROPERTIES <prop1> <value1>
    [<prop2> <value2>] ...)

拷贝命令

构建前后拷贝

# cmake -E <command> [<options>]
#     copy <file>... <destination>
#     copy -t <file>... <directory>
#     copy_directory <dir>... <destination>
#     copy_if_different <file>... <destination>
#     copy_directory_if_different <dir>... <destination>

# add_custom_command(TARGET <target>
#     PRE_BUILD | PRE_LINK | POST_BUILD
#     COMMAND command1 [ARGS] [args1...]
#     [COMMAND command2 [ARGS] [args2...] ...]
# )

# 构建完成后，拷贝文件到指定目录
add_custom_command(TARGET ${PROJECT_NAME} POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E copy -t
        "..."
        "$<TARGET_FILE_DIR:${PROJECT_NAME}>")

# 构建完成后，拷贝目录到指定目录
add_custom_command(TARGET ${PROJECT_NAME} POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E copy_directory
        "..."
        "$<TARGET_FILE_DIR:${PROJECT_NAME}>")

配置拷贝

# 拷贝配置，允许使用 @ONLY 激活 @VAR@ 变量替换。
configure_file(<input> <output>
               [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS |
                FILE_PERMISSIONS <permissions>...]
               [COPYONLY] [ESCAPE_QUOTES] [@ONLY]
               [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])

文件拷贝

# 拷贝一个文件到新的文件路径
file(COPY_FILE <oldname> <newname>
    [RESULT <outVar>]   # 返回不为0的值则表示错误
    [ONLY_IF_DIFFERENT] # 仅当文件变化时拷贝
)

# 拷贝文件到指定目录，并设置相关权限
file(<COPY|INSTALL> <files>... DESTINATION <dir>
    [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS]
    [FILE_PERMISSIONS <permissions>...]
    [DIRECTORY_PERMISSIONS <permissions>...]
    [FOLLOW_SYMLINK_CHAIN]                  # 也拷贝与其关联的链接（适用于动态库及其链接的拷贝）
    [FILES_MATCHING]
    [[PATTERN <pattern> | REGEX <regex>]
    [EXCLUDE] [PERMISSIONS <permissions>...]] [...])

安装命令

基于目标

Type	Variable	Value
RUNTIME	${CMAKE_INSTALL_BINDIR}	bin
LIBRARY	${CMAKE_INSTALL_LIBDIR}	lib
ARCHIVE	${CMAKE_INSTALL_LIBDIR}	lib
PRIVATE_HEADER	${CMAKE_INSTALL_INCLUDEDIR}	include
PUBLIC_HEADER	${CMAKE_INSTALL_INCLUDEDIR}	include

install(TARGETS <target>
    [EXPORT <导出名称>] # 导出模块的配置文件以便被其它cmake引入
    [
        [
            ARCHIVE | LIBRARY|RUNTIME |
            OBJECTS | FRAMEWORK|BUNDLE |
            PRIVATE_HEADER | PUBLIC_HEADER | RESOURCE
        ]
        [DESTINATION <dir>]
        [PERMISSIONS permissions...]
        [...]
        [CONFIGURATIONS [Debug|Release|...]]
        [COMPONENT <component>]
        [NAMELINK_ONLY | NAMELINK_SKIP]
    ] [...]
)
# NAMELINK_DEFAULT: 生成 SONAME 、 SOVERSION 和 so 文件
# NAMELINK_ONLY   : 仅生成 so 文件
# NAMELINK_SKIP   : 生成 SONAME 和 SOVERSION 不生成 so 文件

Example：

install(TARGETS TestShared TestStatic TestApp
        CONFIGURATIONS Release
        PUBLIC_HEADER DESTINATION include
        PRIVATE_HEADER DESTINATION src/include
        RUNTIME DESTINATION bin # Executables、DLLs
        LIBRARY DESTINATION lib # Shared libraries
        ARCHIVE DESTINATION lib # Static libraries、DLL import libraries
        # [NAMELINK_ONLY | NAMELINK_SKIP]
        )

cmake --install cmake-build-release --prefix D:/TestCMakeInstall

基于文件

Type	Variable	Value
BIN	${CMAKE_INSTALL_BINDIR}	bin
SBIN	${CMAKE_INSTALL_SBINDIR}	sbin
LIB	${CMAKE_INSTALL_LIBDIR}	lib
INCLUDE	${CMAKE_INSTALL_INCLUDEDIR}	include
SYSCONF	${CMAKE_INSTALL_SYSCONFDIR}	etc
SHAREDSTATE	${CMAKE_INSTALL_SHARESTATEDIR}	com
LOCALSTATE	${CMAKE_INSTALL_LOCALSTATEDIR}	var
RUNSTATE	${CMAKE_INSTALL_RUNSTATEDIR}	<LOCALSTATE dir>/run
DATA	${CMAKE_INSTALL_DATADIR}	<DATAROOT dir>
INFO	${CMAKE_INSTALL_INFODIR}	<DATAROOT dir>/info
LOCALE	${CMAKE_INSTALL_LOCALEDIR}	<DATAROOT dir>/locale
MAN	${CMAKE_INSTALL_MANDIR}	<DATAROOT dir>/man
DOC	${CMAKE_INSTALL_DOCDIR}	<DATAROOT dir>/doc

install(<FILES|PROGRAMS> files...
    TYPE <type> | DESTINATION <dir>
    [PERMISSIONS permissions...]
    [CONFIGURATIONS [Debug|Release|...]]
    [COMPONENT <component>]
    [RENAME <name>] [OPTIONAL] [EXCLUDE_FROM_ALL])

install(DIRECTORY dirs...
        TYPE <type> | DESTINATION <dir>
        [FILE_PERMISSIONS permissions...]
        [DIRECTORY_PERMISSIONS permissions...]
        [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER]
        [CONFIGURATIONS [Debug|Release|...]]
        [COMPONENT <component>] [EXCLUDE_FROM_ALL]
        [FILES_MATCHING]
        [[PATTERN <pattern> | REGEX <regex>]
         [EXCLUDE] [PERMISSIONS permissions...]] [...])

Example：

install(FILES CMakeLists.txt
        DESTINATION cmake
        )
install(DIRECTORY docs
        DESTINATION .
        )

cmake --install cmake-build-release --prefix D:/TestCMakeInstall