CMake指定安装目录实战指南从入门到精通的安装路径控制全攻略

威震华夏关云长

引言

CMake作为跨平台的构建系统生成器，已成为现代C++项目的事实标准。在软件开发过程中，安装目录的控制是一个至关重要的环节，它决定了软件在用户系统中的位置和组织方式。正确地控制安装目录不仅可以使软件安装更加规范，还能提高软件的可维护性和用户体验。

本文将从基础到高级，全面介绍CMake中安装路径的控制方法，帮助您掌握CMake安装路径管理的各种技巧，从而能够灵活地控制软件的安装位置。

CMake安装基础

在CMake中，安装是通过install()命令来实现的。install()命令可以将构建产物（如可执行文件、库文件、头文件等）安装到指定目录。基本语法如下：

2. install(TARGETS target1 target2 ...
3.         [[ARCHIVE|LIBRARY|RUNTIME]
4.          [DESTINATION <dir>]
5.          [PERMISSIONS permissions...]
6.          [CONFIGURATIONS [Debug|Release|...]]
7.          [COMPONENT <component>]
8.          [OPTIONAL]
9.          [NAMELINK_ONLY|NAMELINK_SKIP]
10.         ] [...])

复制代码

其中，DESTINATION参数用于指定安装目录。例如：

2. install(TARGETS myexe DESTINATION bin)

复制代码

这将把myexe可执行文件安装到bin目录下。

常用安装路径变量

CMake提供了一些预定义的变量，用于控制安装路径。这些变量遵循GNU编码标准，可以在不同平台上保持一致的行为。以下是一些常用的安装路径变量：

• CMAKE_INSTALL_PREFIX：安装前缀，所有其他安装路径都基于此路径。默认值通常是/usr/local（Unix）或C:/Program Files/${PROJECT_NAME}（Windows）。
• CMAKE_INSTALL_BINDIR：用户可执行文件的安装目录，相对于CMAKE_INSTALL_PREFIX。默认值是bin。
• CMAKE_INSTALL_LIBDIR：对象库文件的安装目录，相对于CMAKE_INSTALL_PREFIX。默认值通常是lib或lib64。
• CMAKE_INSTALL_INCLUDEDIR：C头文件的安装目录，相对于CMAKE_INSTALL_PREFIX。默认值是include。
• CMAKE_INSTALL_DATADIR：只读架构独立数据的安装目录，相对于CMAKE_INSTALL_PREFIX。默认值是share。
• CMAKE_INSTALL_DOCDIR：文档根目录的安装目录，相对于CMAKE_INSTALL_PREFIX。默认值通常是share/doc/${PROJECT_NAME}。
• CMAKE_INSTALL_MANDIR：手册页的安装目录，相对于CMAKE_INSTALL_PREFIX。默认值通常是share/man。

这些变量可以通过命令行设置，也可以在CMakeLists.txt文件中设置。例如：

2. set(CMAKE_INSTALL_PREFIX /opt/myapp)

复制代码

或者在命令行中：

2. cmake -DCMAKE_INSTALL_PREFIX=/opt/myapp ..

复制代码

基本安装路径控制

设置安装前缀

安装前缀是所有安装路径的基础，通过设置CMAKE_INSTALL_PREFIX可以控制整个安装的根目录。例如：

2. # 在CMakeLists.txt中设置
3. set(CMAKE_INSTALL_PREFIX /opt/myapp)
5. # 或者通过命令行设置
6. # cmake -DCMAKE_INSTALL_PREFIX=/opt/myapp ..

复制代码

使用相对路径和绝对路径

在install()命令中，可以使用相对路径或绝对路径指定安装目录。如果使用相对路径，它将相对于CMAKE_INSTALL_PREFIX。例如：

2. # 相对路径，将安装到 ${CMAKE_INSTALL_PREFIX}/bin
3. install(TARGETS myexe DESTINATION bin)
5. # 绝对路径，将安装到 /usr/local/bin
6. install(TARGETS myexe DESTINATION /usr/local/bin)

复制代码

使用变量控制安装路径

使用变量可以更灵活地控制安装路径。例如：

2. # 定义自定义变量
3. set(MYAPP_INSTALL_BINDIR bin)
4. set(MYAPP_INSTALL_LIBDIR lib)
6. # 使用变量
7. install(TARGETS myexe DESTINATION ${MYAPP_INSTALL_BINDIR})
8. install(TARGETS mylib DESTINATION ${MYAPP_INSTALL_LIBDIR})

复制代码

高级安装路径控制

使用GNUInstallDirs模块

CMake提供了GNUInstallDirs模块，它定义了一组符合GNU编码标准的安装路径变量。使用这个模块可以使安装路径更加标准化。例如：

2. include(GNUInstallDirs)
4. # 使用GNUInstallDirs定义的变量
5. install(TARGETS myexe DESTINATION ${CMAKE_INSTALL_BINDIR})
6. install(TARGETS mylib DESTINATION ${CMAKE_INSTALL_LIBDIR})
7. install(FILES myheader.h DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})

复制代码

条件安装路径

根据不同的条件设置不同的安装路径。例如，根据构建类型设置不同的安装路径：

2. if(CMAKE_BUILD_TYPE STREQUAL "Debug")
3.     set(DEBUG_SUFFIX "-debug")
4. else()
5.     set(DEBUG_SUFFIX "")
6. endif()
8. install(TARGETS mylib DESTINATION lib${DEBUG_SUFFIX})

复制代码

根据平台设置安装路径

不同的平台可能有不同的安装路径约定。例如：

2. if(WIN32)
3.     set(CMAKE_INSTALL_BINDIR bin)
4.     set(CMAKE_INSTALL_LIBDIR bin)
5.     set(CMAKE_INSTALL_INCLUDEDIR include)
6. elseif(UNIX AND NOT APPLE)
7.     # Linux系统
8.     if(CMAKE_SIZEOF_VOID_P EQUAL 8)
9.         set(CMAKE_INSTALL_LIBDIR lib64)
10.     else()
11.         set(CMAKE_INSTALL_LIBDIR lib)
12.     endif()
13. else()
14.     # macOS或其他Unix系统
15.     set(CMAKE_INSTALL_LIBDIR lib)
16. endif()

复制代码

使用生成器表达式

生成器表达式可以在生成时根据不同的配置或属性计算不同的值。例如：

2. install(TARGETS mylib
3.         ARCHIVE DESTINATION lib
4.         LIBRARY DESTINATION lib
5.         RUNTIME DESTINATION bin
6.         PUBLIC_HEADER DESTINATION include
7.         )

复制代码

或者使用生成器表达式根据配置类型设置不同的安装路径：

2. install(TARGETS mylib
3.         LIBRARY DESTINATION lib/$<CONFIG>
4.         )

复制代码

跨平台安装路径处理

Windows平台下的安装路径

在Windows平台上，安装路径通常使用反斜杠（\）或正斜杠（/）作为分隔符。CMake可以处理这两种格式，但为了保持跨平台兼容性，建议使用正斜杠。例如：

2. if(WIN32)
3.     set(CMAKE_INSTALL_PREFIX "C:/Program Files/${PROJECT_NAME}")
4.     set(CMAKE_INSTALL_BINDIR bin)
5.     set(CMAKE_INSTALL_LIBDIR bin)
6.     set(CMAKE_INSTALL_INCLUDEDIR include)
7. endif()

复制代码

Unix-like平台下的安装路径

在Unix-like平台（包括Linux和macOS）上，安装路径通常遵循FHS（Filesystem Hierarchy Standard）。例如：

2. if(UNIX AND NOT APPLE)
3.     # Linux系统
4.     set(CMAKE_INSTALL_PREFIX /usr/local)
5.     set(CMAKE_INSTALL_BINDIR bin)
6.     set(CMAKE_INSTALL_LIBDIR lib)
7.     set(CMAKE_INSTALL_INCLUDEDIR include)
8.     set(CMAKE_INSTALL_DATADIR share)
9.     set(CMAKE_INSTALL_DOCDIR share/doc/${PROJECT_NAME})
10.     set(CMAKE_INSTALL_MANDIR share/man)
11. elseif(APPLE)
12.     # macOS系统
13.     set(CMAKE_INSTALL_PREFIX /usr/local)
14.     set(CMAKE_INSTALL_BINDIR bin)
15.     set(CMAKE_INSTALL_LIBDIR lib)
16.     set(CMAKE_INSTALL_INCLUDEDIR include)
17.     set(CMAKE_INSTALL_DATADIR share)
18.     set(CMAKE_INSTALL_DOCDIR share/doc/${PROJECT_NAME})
19.     set(CMAKE_INSTALL_MANDIR share/man)
20. endif()

复制代码

使用file(TO_CMAKE_PATH)转换路径

为了处理不同平台的路径格式，可以使用file(TO_CMAKE_PATH)命令将路径转换为CMake格式。例如：

2. file(TO_CMAKE_PATH "$ENV{PROGRAMFILES}/MyApp" INSTALL_PATH)
3. set(CMAKE_INSTALL_PREFIX ${INSTALL_PATH})

复制代码

自定义安装方案

创建安装组件

安装组件允许将软件的不同部分分组，用户可以选择安装哪些组件。例如：

2. # 定义组件
3. install(TARGETS myexe
4.         DESTINATION bin
5.         COMPONENT Runtime)
6. install(TARGETS mylib
7.         DESTINATION lib
8.         COMPONENT Library)
9. install(FILES myheader.h
10.         DESTINATION include
11.         COMPONENT Development)
13. # 设置组件描述
14. set(CPACK_COMPONENT_RUNTIME_DISPLAY_NAME "Runtime")
15. set(CPACK_COMPONENT_RUNTIME_DESCRIPTION "Runtime components")
16. set(CPACK_COMPONENT_LIBRARY_DISPLAY_NAME "Library")
17. set(CPACK_COMPONENT_LIBRARY_DESCRIPTION "Library files")
18. set(CPACK_COMPONENT_DEVELOPMENT_DISPLAY_NAME "Development")
19. set(CPACK_COMPONENT_DEVELOPMENT_DESCRIPTION "Development files")

复制代码

自定义安装脚本

除了安装文件，还可以执行自定义的安装脚本。例如：

2. install(SCRIPT cmake_install.cmake)
4. # 或者执行代码
5. install(CODE "
6.     message(STATUS "Performing custom installation step")
7.     file(MAKE_DIRECTORY \$ENV{DESTDIR}\${CMAKE_INSTALL_PREFIX}/etc)
8.     file(WRITE \$ENV{DESTDIR}\${CMAKE_INSTALL_PREFIX}/etc/config.ini "[Default]")
9.     ")

复制代码

安装时文件处理

可以在安装时对文件进行处理，例如重命名、修改权限等。例如：

2. install(FILES README.md
3.         DESTINATION .
4.         PERMISSIONS OWNER_READ OWNER_WRITE GROUP_READ WORLD_READ
5.         RENAME README_${PROJECT_NAME}.md)

复制代码

实战案例

案例1：基础库的安装

假设我们有一个名为mylib的基础库，需要安装库文件、头文件和CMake配置文件。CMakeLists.txt可能如下：

2. cmake_minimum_required(VERSION 3.10)
3. project(MyLib VERSION 1.0.0)
5. include(GNUInstallDirs)
7. # 创建库
8. add_library(mylib src/mylib.cpp)
9. target_include_directories(mylib PUBLIC
10.     $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
11.     $<INSTALL_INTERFACE:include>)
13. # 安装库
14. install(TARGETS mylib
15.         EXPORT MyLibTargets
16.         LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
17.         ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
18.         RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
19.         PUBLIC_HEADER DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/mylib)
21. # 安装CMake配置文件
22. include(CMakePackageConfigHelpers)
23. write_basic_package_version_file(
24.     "${CMAKE_CURRENT_BINARY_DIR}/MyLibConfigVersion.cmake"
25.     VERSION ${PROJECT_VERSION}
26.     COMPATIBILITY AnyNewerVersion)
28. install(EXPORT MyLibTargets
29.         FILE MyLibTargets.cmake
30.         NAMESPACE MyLib::
31.         DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MyLib)
33. install(FILES "${CMAKE_CURRENT_BINARY_DIR}/MyLibConfigVersion.cmake"
34.         DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MyLib)

复制代码

案例2：可执行文件和插件的安装

假设我们有一个主程序myapp和一组插件plugin1、plugin2，需要将它们安装到不同的目录。CMakeLists.txt可能如下：

2. cmake_minimum_required(VERSION 3.10)
3. project(MyApp VERSION 1.0.0)
5. include(GNUInstallDirs)
7. # 创建主程序
8. add_executable(myapp src/main.cpp)
9. target_include_directories(myapp PRIVATE include)
11. # 创建插件
12. add_library(plugin1 SHARED src/plugin1.cpp)
13. target_include_directories(plugin1 PRIVATE include)
15. add_library(plugin2 SHARED src/plugin2.cpp)
16. target_include_directories(plugin2 PRIVATE include)
18. # 安装主程序
19. install(TARGETS myapp
20.         DESTINATION ${CMAKE_INSTALL_BINDIR}
21.         COMPONENT Runtime)
23. # 安装插件
24. install(TARGETS plugin1 plugin2
25.         DESTINATION ${CMAKE_INSTALL_LIBDIR}/myapp/plugins
26.         COMPONENT Plugins)
28. # 安装资源文件
29. install(DIRECTORY resources/
30.         DESTINATION ${CMAKE_INSTALL_DATADIR}/myapp
31.         COMPONENT Resources)
33. # 安装配置文件
34. install(FILES config.ini
35.         DESTINATION ${CMAKE_INSTALL_SYSCONFDIR}/myapp
36.         COMPONENT Config)
38. # 设置组件描述
39. set(CPACK_COMPONENT_RUNTIME_DISPLAY_NAME "Runtime")
40. set(CPACK_COMPONENT_RUNTIME_DESCRIPTION "Main application")
41. set(CPACK_COMPONENT_PLUGINS_DISPLAY_NAME "Plugins")
42. set(CPACK_COMPONENT_PLUGINS_DESCRIPTION "Application plugins")
43. set(CPACK_COMPONENT_RESOURCES_DISPLAY_NAME "Resources")
44. set(CPACK_COMPONENT_RESOURCES_DESCRIPTION "Application resources")
45. set(CPACK_COMPONENT_CONFIG_DISPLAY_NAME "Configuration")
46. set(CPACK_COMPONENT_CONFIG_DESCRIPTION "Configuration files")

复制代码

案例3：跨平台安装方案

假设我们需要创建一个跨平台的安装方案，针对不同平台使用不同的安装路径。CMakeLists.txt可能如下：

2. cmake_minimum_required(VERSION 3.10)
3. project(MyApp VERSION 1.0.0)
5. include(GNUInstallDirs)
7. # 根据平台设置安装路径
8. if(WIN32)
9.     set(CMAKE_INSTALL_PREFIX "$ENV{PROGRAMFILES}/${PROJECT_NAME}")
10.     set(CMAKE_INSTALL_BINDIR bin)
11.     set(CMAKE_INSTALL_LIBDIR bin)
12.     set(CMAKE_INSTALL_INCLUDEDIR include)
13.     set(CMAKE_INSTALL_DATADIR data)
14.     set(CMAKE_INSTALL_SYSCONFDIR config)
15. elseif(APPLE)
16.     set(CMAKE_INSTALL_PREFIX "/Applications/${PROJECT_NAME}.app/Contents")
17.     set(CMAKE_INSTALL_BINDIR MacOS)
18.     set(CMAKE_INSTALL_LIBDIR Frameworks)
19.     set(CMAKE_INSTALL_INCLUDEDIR Headers)
20.     set(CMAKE_INSTALL_DATADIR Resources)
21.     set(CMAKE_INSTALL_SYSCONFDIR Resources)
22. else()
23.     # Linux和其他Unix系统
24.     set(CMAKE_INSTALL_PREFIX /usr/local)
25.     if(CMAKE_SIZEOF_VOID_P EQUAL 8)
26.         set(CMAKE_INSTALL_LIBDIR lib64)
27.     else()
28.         set(CMAKE_INSTALL_LIBDIR lib)
29.     endif()
30. endif()
32. # 创建可执行文件
33. add_executable(myapp src/main.cpp)
34. target_include_directories(myapp PRIVATE include)
36. # 创建库
37. add_library(mylib SHARED src/mylib.cpp)
38. target_include_directories(mylib PUBLIC
39.     $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
40.     $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>)
42. # 安装可执行文件
43. install(TARGETS myapp
44.         DESTINATION ${CMAKE_INSTALL_BINDIR}
45.         COMPONENT Runtime)
47. # 安装库
48. install(TARGETS mylib
49.         LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
50.         ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
51.         RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
52.         PUBLIC_HEADER DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/mylib
53.         COMPONENT Library)
55. # 安装资源文件
56. if(WIN32)
57.     install(DIRECTORY resources/
58.             DESTINATION ${CMAKE_INSTALL_DATADIR}
59.             COMPONENT Resources)
60. elseif(APPLE)
61.     # 在macOS上，资源文件需要特殊处理
62.     install(DIRECTORY resources/
63.             DESTINATION ${CMAKE_INSTALL_DATADIR}
64.             COMPONENT Resources)
65. else()
66.     install(DIRECTORY resources/
67.             DESTINATION ${CMAKE_INSTALL_DATADIR}/${PROJECT_NAME}
68.             COMPONENT Resources)
69. endif()
71. # 安装桌面文件（仅限Linux）
72. if(UNIX AND NOT APPLE)
73.     install(FILES ${PROJECT_NAME}.desktop
74.             DESTINATION ${CMAKE_INSTALL_DATADIR}/applications
75.             COMPONENT Desktop)
76. endif()
78. # 安装图标文件
79. if(WIN32)
80.     install(FILES icons/myapp.ico
81.             DESTINATION ${CMAKE_INSTALL_DATADIR}
82.             COMPONENT Resources)
83. elseif(APPLE)
84.     # 在macOS上，图标通常包含在app bundle中
85.     install(FILES icons/myapp.icns
86.             DESTINATION ${CMAKE_INSTALL_DATADIR}
87.             COMPONENT Resources)
88. else()
89.     # Linux和其他Unix系统
90.     install(FILES icons/myapp.png
91.             DESTINATION ${CMAKE_INSTALL_DATADIR}/icons/hicolor/256x256/apps
92.             COMPONENT Resources)
93. endif()

复制代码

最佳实践和常见问题

最佳实践

1. 使用GNUInstallDirs模块：这个模块提供了一组符合GNU编码标准的安装路径变量，可以使安装路径更加标准化。
2. 使用相对路径：在install()命令中使用相对路径，而不是绝对路径，这样用户可以通过设置CMAKE_INSTALL_PREFIX来改变整个安装的根目录。
3. 考虑多架构支持：在支持多架构的系统（如Linux）上，考虑使用lib64目录存放64位库。
4. 使用组件安装：对于复杂的软件，使用组件安装可以让用户选择安装哪些部分，减少不必要的文件安装。
5. 遵循平台约定：不同平台有不同的安装路径约定，遵循这些约定可以使软件更好地融入系统。

使用GNUInstallDirs模块：这个模块提供了一组符合GNU编码标准的安装路径变量，可以使安装路径更加标准化。

使用相对路径：在install()命令中使用相对路径，而不是绝对路径，这样用户可以通过设置CMAKE_INSTALL_PREFIX来改变整个安装的根目录。

考虑多架构支持：在支持多架构的系统（如Linux）上，考虑使用lib64目录存放64位库。

使用组件安装：对于复杂的软件，使用组件安装可以让用户选择安装哪些部分，减少不必要的文件安装。

遵循平台约定：不同平台有不同的安装路径约定，遵循这些约定可以使软件更好地融入系统。

常见问题

问题描述：在安装路径中使用变量，但变量没有被正确展开。

解决方案：确保变量在install()命令执行前已经定义。如果使用生成器表达式，确保语法正确。例如：

2. # 错误示例
3. install(TARGETS mylib DESTINATION lib/${PROJECT_NAME})
5. # 正确示例
6. set(MYLIB_INSTALL_DIR lib/${PROJECT_NAME})
7. install(TARGETS mylib DESTINATION ${MYLIB_INSTALL_DIR})

复制代码

问题描述：在Windows上，安装路径包含反斜杠，导致路径不正确。

解决方案：使用正斜杠作为路径分隔符，或者使用file(TO_CMAKE_PATH)命令转换路径。例如：

2. # 使用正斜杠
3. set(CMAKE_INSTALL_PREFIX "C:/Program Files/${PROJECT_NAME}")
5. # 或者使用file(TO_CMAKE_PATH)
6. file(TO_CMAKE_PATH "$ENV{PROGRAMFILES}\\${PROJECT_NAME}" CMAKE_INSTALL_PREFIX)

复制代码

问题描述：安装路径在不同平台上不一致，导致软件行为不一致。

解决方案：使用条件语句根据不同平台设置不同的安装路径，并尽量保持结构一致。例如：

2. if(WIN32)
3.     set(CMAKE_INSTALL_BINDIR bin)
4.     set(CMAKE_INSTALL_LIBDIR bin)
5.     set(CMAKE_INSTALL_INCLUDEDIR include)
6. else()
7.     set(CMAKE_INSTALL_BINDIR bin)
8.     set(CMAKE_INSTALL_LIBDIR lib)
9.     set(CMAKE_INSTALL_INCLUDEDIR include)
10. endif()

复制代码

问题描述：在安装时，CMake报告找不到要安装的文件。

解决方案：确保文件路径正确，并且文件在构建目录中存在。使用CMAKE_CURRENT_SOURCE_DIR和CMAKE_CURRENT_BINARY_DIR变量来指定正确的路径。例如：

2. # 安装源目录中的文件
3. install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/README.md
4.         DESTINATION .)
6. # 安装构建目录中生成的文件
7. install(FILES ${CMAKE_CURRENT_BINARY_DIR}/config.h
8.         DESTINATION include)

复制代码

问题描述：在Windows上，安装路径可能很长或包含空格，导致问题。

解决方案：使用引号包围路径，或者使用短路径名。例如：

2. # 使用引号
3. set(CMAKE_INSTALL_PREFIX "C:/Program Files/${PROJECT_NAME}")
5. # 或者使用短路径名
6. file(TO_CMAKE_PATH "$ENV{PROGRAMFILES}" PROG_FILES)
7. set(CMAKE_INSTALL_PREFIX "${PROG_FILES}/${PROJECT_NAME}")

复制代码

总结

CMake提供了灵活而强大的安装路径控制机制，通过合理使用这些机制，可以创建出符合不同平台标准的安装方案。本文从基础到高级，全面介绍了CMake中安装路径的控制方法，包括：

1. 使用基本变量如CMAKE_INSTALL_PREFIX控制安装根目录。
2. 使用GNUInstallDirs模块获取标准的安装路径变量。
3. 根据不同平台和条件设置不同的安装路径。
4. 使用组件安装创建灵活的安装方案。
5. 通过实际案例演示了不同场景下的安装路径控制。

掌握这些技巧，可以帮助开发者创建出更加专业、标准化的软件安装方案，提高软件的用户体验和可维护性。

希望本文能够帮助您更好地理解和掌握CMake中安装路径的控制方法，在实际项目中灵活应用这些技巧，创建出优秀的软件安装方案。

mai2

感謝分享