构建工具开发工具CLI【免费下载链接】CMakeMirror of CMake upstream repository项目地址https://gitcode.com/gh_mirrors/cm/CMake点击查看免费下载导读CMake 除了通过命令行-D选项和 CMakeLists.txt 传递配置外还从操作系统环境读取一批具有特殊含义的环境变量它们能够在配置阶段改变查找路径、TLS 行为在构建阶段控制并行度、生成器选择与输出细节并为各编程语言指定编译器与编译选项。本文以 CMake 官方手册 Help/manual/cmake-env-variables.7.rst 为骨架逐一解读这些变量的作用、默认约定、使用场景与底层实现帮助你在实际项目中精准地用环境变量接管 CMake 行为。环境变量在 CMake 中的地位环境变量与普通 CMake 变量的区别在 CMake 语言中环境变量是一类特殊的变量其行为在 Help/manual/cmake-language.7.rst 的 Environment Variables 一节中有明确定义。与普通变量相比环境变量有以下关键差异作用域环境变量在 CMake 进程内具有全局作用域且永远不会被缓存不会进入 CMakeCache.txt引用方式通过$ENV{variable}语法读取例如$ENV{HOME}初始化CMake 进程启动时环境变量的初始值来自调用进程即你运行cmake命令时的 shell 环境修改方式可以用 set 与 unset 命令修改但修改只影响当前运行的 CMake 进程不会写回系统环境也不会被后续的构建或测试进程看到辅助工具需要带着修改后的环境运行子命令时用cmake -E env varvalue command需要查看当前全部环境变量时用cmake -E environment。正因环境变量具有进程级、不缓存的特性它们非常适合承载不应写入 CMakeCache.txt 的临时性配置例如凭据、本机特有的工具路径、以及希望每次配置都重新读取的开关。手册的变量分类框架手册 cmake-env-variables.7.rst 将全部特殊环境变量分为五大类这也是本文的讲解主线分类关注点Environment Variables that Change Behavior改变 CMake 自身行为查找路径、颜色输出、TLS、策略版本Environment Variables that Control the Build控制构建过程并行度、生成器、安装前缀、编译/链接启动器Environment Variables for Languages为各语言指定编译器与编译选项CC、CXX、CFLAGS 等Environment Variables for CTest控制 CTest 测试行为并行度、失败输出、仪表化Environment Variables for the CMake curses interface控制ccmake界面如 CCMAKE_COLORS每一类对应的单变量文档都存放在 Help/envvar 目录下共 100 余个.rst文件手册只是按主题聚合了它们的目录。所有变量条目都遵循统一模板见 Help/envvar/include/ENV_VAR.rst初始值取自调用进程环境也就是说你设置了它就生效你没设置就使用 CMake 内置默认值。改变 CMake 行为的环境变量这一类变量直接作用于配置阶段configure影响 CMake 如何寻找依赖、如何展示输出、如何验证远端证书等基础行为。查找路径四件套PREFIX / INCLUDE / LIBRARY / PROGRAMCMake 的find_*系列命令是依赖管理的核心它们不仅搜索系统默认路径还会依次检查一批专用环境变量CMAKE_PREFIX_PATH见 Help/envvar/CMAKE_PREFIX_PATH.rst存放一个或多个**安装前缀prefix**目录列表会被 find_package、find_program、find_library、find_file、find_path 共同使用。每个命令会依据自身文档在该前缀下继续查找bin、lib、include等标准子目录。这是把第三方库装在非标准位置如/opt/mylib后让 CMake 找到它最常用的手段CMAKE_INCLUDE_PATH见 Help/envvar/CMAKE_INCLUDE_PATH.rst供 find_file 与 find_path 搜索头文件/文件所在目录CMAKE_LIBRARY_PATH见 Help/envvar/CMAKE_LIBRARY_PATH.rst供 find_library 搜索库文件所在目录CMAKE_PROGRAM_PATH见 Help/envvar/CMAKE_PROGRAM_PATH.rst供 find_program 搜索可执行程序所在目录。这四个变量的共同语法约定是在 UNIX 上以:分隔多个路径在 Windows 上以;分隔与各平台PATH的惯例一致。以CMAKE_PREFIX_PATH为例一个典型用法是# Linux/macOS export CMAKE_PREFIX_PATH/opt/mylib:/opt/toolchain cmake -S . -B build # Windows PowerShell $env:CMAKE_PREFIX_PATH C:\libs\mylib;C:\libs\toolchain cmake -S . -B build值得注意这四个变量在 CMake 中都有同名的CMake 变量CMAKE_PREFIX_PATH等环境变量与同名 CMake 变量协同工作。若在 CMakeLists.txt 或命令行中同时设置了两者查找顺序以 find_package 等命令的完整搜索规则为准环境变量版本特别适合在不修改项目代码的情况下为整个构建脚本补充搜索路径。macOS 专属路径FRAMEWORK 与 APPBUNDLE针对 Apple 平台的生态特性还有两个查找路径变量CMAKE_FRAMEWORK_PATH见 Help/envvar/CMAKE_FRAMEWORK_PATH.rst存放搜索 macOS framework.framework目录的路径列表被 find_library、find_package、find_path、find_file 使用CMAKE_APPBUNDLE_PATH见 Help/envvar/CMAKE_APPBUNDLE_PATH.rst存放搜索 macOS应用包application bundle的路径列表被 find_program 与 find_package 使用。二者同样遵循:UNIX/;Windows分隔约定且都有同名 CMake 变量版本。输出颜色控制CLICOLOR 家族与 NO_COLOR终端输出是否带颜色会影响 CI 日志的可读性与日志文件的解析CLICOLOR与CLICOLOR_FORCE控制 CMake 输出是否启用颜色遵循通用终端约定CLICOLOR_FORCE强制启用颜色NO_COLOR遵循社区通用的 NO_COLOR 惯例设置后禁用输出颜色。当脚本或日志系统无法处理 ANSI 转义序列时在 CI 中设置export NO_COLOR1可以保证输出纯净。这三个变量决定了 CMake 配置与构建过程中的彩色输出行为。与它们配套的还有构建诊断着色变量 CMAKE_COLOR_DIAGNOSTICS见下文控制构建一节。网络与 TLS证书与校验CMake 的file(DOWNLOAD)、file(UPLOAD)及FetchContent等网络操作遵循标准的 OpenSSL 证书环境变量SSL_CERT_FILE指定包含 CA 证书的文件路径SSL_CERT_DIR指定包含 CA 证书的目录路径CMAKE_TLS_VERIFY设为非空值可强制开启 TLS 证书校验对应 CMake 变量 CMAKE_TLS_VERIFY 的行为CMAKE_TLS_VERSION指定 TLS 协议版本。在企业内网使用自签名证书或私有 CA 时正确设置SSL_CERT_FILE/SSL_CERT_DIR能避免下载失败反之在完全受控的内网环境中可用CMAKE_TLS_VERIFY关闭校验需评估安全风险。安全与兼容递归深度与策略版本CMAKE_MAXIMUM_RECURSION_DEPTH限制add_subdirectory等导致的目录递归深度防止配置阶段因失控递归而栈溢出CMAKE_POLICY_VERSION_MINIMUM为整个项目设置 CMake策略policy版本下限。当项目引用的依赖如通过find_package拉入的包要求更高的策略版本或你希望统一跨模块的策略行为时通过该变量或同名 CMake 变量 CMAKE_POLICY_VERSION_MINIMUM可以避免因策略版本不一致导致的兼容性问题。这是 CMake 3.21 之后处理依赖项目最低版本问题的关键开关。系统环境探测CMAKE_SYSTEM_ENVIRONMENT_ACTION与CMAKE_SYSTEM_ENVIRONMENT_ID分别影响 CMake 对系统环境的处理方式与系统环境标识system environment id的读取涉及 CMake 对平台环境的识别与记录。控制构建过程的环境变量这一类变量作用于生成阶段generate与构建阶段build决定用什么生成器、并行度多少、装到哪里、输出多详细。生成器选择CMAKE_GENERATOR 及其配套CMAKE_GENERATOR3.15 新增见 Help/envvar/CMAKE_GENERATOR.rst指定当命令行未提供-G选项时使用的默认生成器。若提供的值不是 CMake 已知的生成器名则回退到内部默认值无论如何最终选定的生成器会记录到 CMake 变量CMAKE_GENERATOR中CMAKE_GENERATOR_PLATFORM为生成器指定目标平台如 Visual Studio 的x64、ARM64CMAKE_GENERATOR_TOOLSET为生成器指定工具集如 Visual Studio 的v143CMAKE_GENERATOR_INSTANCE为生成器指定实例如多实例安装的 Visual Studio 实例 ID。这三个配套变量可在多平台 CI 中无参数化地切换生成器与工具链例如export CMAKE_GENERATORNinja export CMAKE_GENERATOR_PLATFORMx64 cmake -S . -B build # 等价于 cmake -G Ninja -A x64 -S . -B build并行构建CMAKE_BUILD_PARALLEL_LEVELCMAKE_BUILD_PARALLEL_LEVEL3.12 新增见 Help/envvar/CMAKE_BUILD_PARALLEL_LEVEL.rst指定cmake --buildBuild Tool Mode可使用的最大并发进程数。例如设为 8等价于调用cmake --build dir --parallel 8。若该变量被定义为空值则使用底层构建工具自身的默认并发数。它不修改 CMakeLists.txt适合在 CI 中按机器核数动态控制export CMAKE_BUILD_PARALLEL_LEVEL$(nproc) cmake --build build安装相关CMAKE_INSTALL_PREFIX / CMAKE_INSTALL_MODE / DESTDIRCMAKE_INSTALL_PREFIX指定cmake --install与install()规则默认使用的安装前缀即cmake --install dir --prefix未显式给出时的默认值对应同名 CMake 变量 CMAKE_INSTALL_PREFIXCMAKE_INSTALL_MODE控制安装行为模式DESTDIR见 Help/envvar/DESTDIR.rst用于staged install把安装内容重定向到临时根目录下便于打包成 deb/rpm 等软件包时收集文件列表。典型用法export DESTDIR/tmp/stage cmake --install build # 文件被安装到 /tmp/stage/usr/local/...输出与诊断VERBOSE / CMAKE_NO_VERBOSE / 导出编译数据库VERBOSE3.14 新增见 Help/envvar/VERBOSE.rst只要该变量存在其值被忽略就激活 CMake 与底层构建工具的详细输出——也就是说export VERBOSE1和export VERBOSE效果相同。构建时它会展开实际编译命令便于排查头文件包含路径与链接参数CMAKE_NO_VERBOSE与VERBOSE相反抑制详细输出CMAKE_EXPORT_COMPILE_COMMANDS设为非空值后CMake 会在构建目录生成compile_commands.json其中记录每个编译单元的实际编译命令。这是 clangd、ccls 等编辑器语言服务器和静态分析工具的输入CMAKE_EXPORT_BUILD_DATABASE导出构建数据库CMAKE_FASTBUILD_VERBOSE_GENERATOR控制 Fastbuild 生成器的详细输出。编译/链接启动器与隐式链接控制CMAKE_LANG_COMPILER_LAUNCHER如CMAKE_CXX_COMPILER_LAUNCHER为编译命令前置启动器最常见的用途是接入ccache或sccache以加速重复构建export CMAKE_CXX_COMPILER_LAUNCHERccacheCMAKE_LANG_LINKER_LAUNCHER如CMAKE_CXX_LINKER_LAUNCHER为链接命令前置启动器同样可接ccache/sccacheCMAKE_LANG_IMPLICIT_LINK_DIRECTORIES_EXCLUDE与CMAKE_LANG_IMPLICIT_LINK_LIBRARIES_EXCLUDE从隐式链接目录/隐式链接库中排除指定项用于精细控制链接命令规避某些系统库带来的符号冲突。其他构建控制变量CMAKE_TOOLCHAIN_FILE指定交叉编译工具链文件路径对应 CMAKE_TOOLCHAIN_FILE跨平台构建时配合-DCMAKE_TOOLCHAIN_FILE使用CMAKE_OSX_ARCHITECTURES与CMAKE_APPLE_SILICON_PROCESSOR控制 macOS 构建的目标架构如arm64、x86_64MACOSX_DEPLOYMENT_TARGET指定 macOS 最低部署版本CMAKE_MSVCIDE_RUN_PATHMSVC IDE 场景下运行可执行文件时的附加路径CMAKE_CONFIG_DIR / CMAKE_CONFIG_TYPE / CMAKE_CONFIGURATION_TYPES控制多配置生成器的配置目录与配置类型Debug/Release 等CMAKE_DISABLE_PRECOMPILE_HEADERS全局禁用预编译头CMAKE_CROSSCOMPILING_EMULATOR交叉编译时为运行测试指定的模拟器CMAKE_TEST_LAUNCHER运行测试时前置的启动器如catch_discover_tests场景下的执行环境包装CMAKE_INTERMEDIATE_DIR_STRATEGY与CMAKE_AUTOGEN_INTERMEDIATE_DIR_STRATEGY控制中间目录生成策略影响 AUTOMOC/AUTOUIC/AUTORCC 的中间文件布局PackageName_ROOTPackageName_ROOT形式的环境变量为单个包指定根目录供 find_package 的PackageName_ROOT搜索阶段使用与同名 CMake 变量一致LDFLAGS为链接阶段附加链接器标志ADSP_ROOTAnalog Devices DSP 工具链根目录用于 ADSP 交叉编译场景。各语言编译器与编译选项环境变量CMake 确定编译器时遵循一套环境变量优先的规则CC/CXX/FC等环境变量可以被视为默认编译器选择。这一节按语言分组列出手册收录的全部变量。C 与 CCC默认 C 编译器例如export CCclang后配置C 编译器将优先使用 clangCXX默认 C 编译器例如export CXXg-13CFLAGSC 编译器的附加编译选项会被追加到编译命令中CXXFLAGSC 编译器的附加编译选项。典型用法是在构建只读项目时不改 CMakeLists.txt 就能切换工具链export CCclang export CXXclang export CFLAGS-O2 -Wall export CXXFLAGS-O2 -Wall -stdc17 cmake -S . -B build注意这些环境变量通常在首次配置时生效并固化进CMakeCache.txtCMAKE_C_COMPILER、CMAKE_CXX_COMPILER若需更换编译器更可靠的做法是删除构建目录重新配置或显式传递-DCMAKE_C_COMPILER...。CUDA 系列CUDACXX默认 CUDA 编译器nvccCUDAHOSTCXXCUDA 编译时用于编译主机侧代码的 C 编译器CUDAARCHS指定 CUDA 架构列表如export CUDAARCHS80;86对应CMAKE_CUDA_ARCHITECTURES决定生成的 PTX/SASS 面向哪些 GPU 架构CUDAFLAGSCUDA 编译器附加选项。Fortran 与 HIPFC默认 Fortran 编译器gfortran/flang 等FFLAGSFortran 编译器附加选项HIPCXX默认 HIP 编译器hipccHIPHOSTCXXHIP 编译时主机侧 C 编译器HIPFLAGSHIP 编译器附加选项。其他语言与方言OBJC/OBJCFLAGSObjective-C 编译器与附加选项OBJCXX/OBJCXXFLAGSObjective-C 编译器与附加选项ISPC/ISPCFLAGSIntel ISPC 编译器与附加选项RC/RCFLAGSWindows 资源编译器windres/rc与附加选项CSFLAGSC# 编译器附加选项SWIFTCSwift 编译器ASM_DIALECT与ASM_DIALECTFLAGS汇编语言方言选择与附加选项。关于CMAKE_LANG_*形式的通用约定手册同时收录了一批以CMAKE_LANG_...命名的变量如CMAKE_LANG_COMPILER_LAUNCHER、CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES_EXCLUDE其中LANG是占位符实际使用时替换为具体语言名C、CXX、CUDA、Fortran 等例如CMAKE_CUDA_COMPILER_LAUNCHER、CMAKE_Fortran_IMPLICIT_LINK_LIBRARIES_EXCLUDE。CTest 与 curses 界面的环境变量CTest 行为控制手册的第四类变量全部作用于 CTest 测试流程CTEST_PARALLEL_LEVELCTest 并行运行测试的最大并发数CTEST_OUTPUT_ON_FAILURE设置后测试失败时输出完整测试输出对应ctest --output-on-failure是 CI 排查失败用例的标配export CTEST_OUTPUT_ON_FAILURE1 ctest --test-dir buildCTEST_NO_TESTS_ACTION当没有测试可运行时 CTest 的行为如报错或跳过CTEST_PROGRESS_OUTPUT控制进度输出CTEST_INTERACTIVE_DEBUG_MODE交互式调试模式CTEST_USE_INSTRUMENTATION与CTEST_USE_VERBOSE_INSTRUMENTATION控制仪表化instrumentation输出CTEST_USE_LAUNCHERS_DEFAULT控制 CTest 是否默认使用 launcher配合 Makefile/Ninja 的CMAKE_USE_LAUNCHERSCMAKE_CONFIG_TYPE多配置构建下 CTest 运行所针对的配置类型DASHBOARD_TEST_FROM_CTEST标识当前测试由 CTest dashboard 驱动供脚本区分执行上下文。ccmake 界面CCMAKE_COLORS控制 curses 界面ccmake的配色方案见 Help/envvar/CCMAKE_COLORS.rst可自定义前景/背景色组合改善终端配色不佳环境下的可读性。在源码与测试中的印证以上变量并非文档虚构均可在仓库源码与测试中找到对应实现编译器环境变量CC/CXX/FC等的读取逻辑位于 Source/Modules/CMakeDetermineCompiler.cmake 及各语言对应的CMakeDetermine*Compiler.cmake如 Source/Modules/CMakeDetermineCXXCompiler.cmake这些模块在确定编译器时会查询对应环境变量查找路径变量CMAKE_PREFIX_PATH、CMAKE_INCLUDE_PATH等由find_*命令的实现如 Source/cmFindPackageCommand.cxx、Source/cmFindLibraryCommand.cxx在搜索阶段读取并行构建CMAKE_BUILD_PARALLEL_LEVEL与--parallel选项在cmake --buildBuild Tool Mode实现中处理最终转换为底层构建工具的-j参数环境变量语义$ENV{}的解析与set/unset对环境的修改由 Source/cmMakefile.cxx 与 Source/cmSetCommand.cxx 等实现可结合 Help/command/set.rst 与 Help/command/unset.rst 文档查看测试覆盖Tests目录中存在大量以环境变量为主题的测试用例例如通过设置VERBOSE、CMAKE_BUILD_PARALLEL_LEVEL验证构建行为、通过CC/CXX验证编译器切换、通过DESTDIR验证 staged install 的RunCMake类测试可用于回归验证这些变量的实际效果。实战组合一套零参数的 CI 构建方案综合上述变量可以在不改动任何 CMakeLists.txt 的情况下用纯环境变量驱动一次完整构建与测试# 1. 工具链与编译选项Languages 类 export CCclang export CXXclang export CFLAGS-O2 export CXXFLAGS-O2 -stdc17 # 2. 依赖查找Behavior 类 export CMAKE_PREFIX_PATH/opt/deps:/opt/qt # 3. 生成器与并行度Build 类 export CMAKE_GENERATORNinja export CMAKE_BUILD_PARALLEL_LEVEL8 # 4. 输出控制Build 类 export VERBOSE1 export CMAKE_EXPORT_COMPILE_COMMANDS1 # 5. 配置、构建、测试 cmake -S . -B build cmake --build build export CTEST_OUTPUT_ON_FAILURE1 ctest --test-dir build这套模式在 CI 矩阵matrix中尤其有用同一份作业定义通过注入不同的环境变量组合即可覆盖多编译器、多生成器、多依赖前缀的测试矩阵且所有选择都显式可见、可审计。小结CMake 的特殊环境变量体系覆盖了配置行为、构建控制、语言工具链、测试执行、交互界面五个维度其设计哲学与普通 CMake 变量互补环境变量进程级、不缓存、来自调用环境天然适合存放临时性、本机性、矩阵化的配置。建议读者在需要时先查 Help/manual/cmake-env-variables.7.rst 确认变量属于哪一分类再进入 Help/envvar 目录阅读对应单变量条目确认引入版本、语义与同名 CMake 变量关系最后对照 Help/manual/cmake-language.7.rst 的 Environment Variables 一节理解$ENV{}引用与set/unset修改的作用范围限制。掌握这套变量体系你便能在不改项目源码的前提下从外部精准控制 CMake 的每一次配置与构建。赞分享构建工具开发工具CLI【免费下载链接】CMakeMirror of CMake upstream repository项目地址https://gitcode.com/gh_mirrors/cm/CMake点击查看免费下载相关推荐CMake 环境变量 OBJC 完全指南为 Objective-C 语言指定首选编译器CMake 环境变量 OBJC 完全指南为 Objective C 语言指定首选编译器 导读 OBJC 是 CMake 在首次配置项目时用于定位 Object构建工具开发工具CLICMake 环境变量 MACOSX_DEPLOYMENT_TARGET 完全指南从环境变量到 CMAKE_OSX_DEPLOYMENT_TARGET 的 macOS 最低部署版本控制CMake 环境变量 MACOSX_DEPLOYMENT_TARGET 完全指南从环境变量到 CMAKE_OSX_DEPLOYMENT_TARGET 的 ma构建工具开发工具CLICMake 环境变量 CMAKE_BUILD_PARALLEL_LEVEL 完全指南控制 cmake --build 并发构建进程数CMake 环境变量 CMAKE_BUILD_PARALLEL_LEVEL 完全指南控制 cmake build 并发构建进程数 本文围绕 CMake 的 C构建工具开发工具CLI上一篇Namshi/JOSE常见问题解答解决开发者遇到的10大难题下一篇polkadot/apps 与 IPFS 集成去中心化存储如何增强区块链应用体验创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考