Documentation

从第一条命令开始

本页覆盖安装、目标 GCC 选择、常用命令行、PCH、诊断和故障排查。完整实现和测试矩阵以 GitHub 仓库为准。

安装

下载 Windows x64 压缩包,解压到任意目录即可。CrucibleCpp 是静态链接的单文件程序,不需要安装运行时。

cruciblecpp-preprocessor.exe --version # cruciblecpp-preprocessor 3.0.1
当前生产目标:Windows x64 + MinGW-w64 UCRT64。其他平台、ABI 和 GCC 版本未承诺支持。

快速开始

先确认 PATH 中能找到目标 g++.exe。然后直接替换原来的 g++ -E:

# 预处理 .\cruciblecpp-preprocessor.exe -P -std=c++20 src\main.cpp -o build\main.i # 用同一个 GCC 编译 g++ -std=c++20 build\main.i -o build\main.exe

如果没有把目标 GCC 放进 PATH,用 --gcc 明确指定:

.\cruciblecpp-preprocessor.exe ` --gcc "D:\GCC1413\gcc14\bin\g++.exe" ` -P -std=c++20 src\main.cpp -o build\main.i

选择 GCC

CrucibleCpp 会使用目标 GCC 的预定义宏、__has_* 数据和 include 搜索路径。不要用 GCC15 的 profile 去预处理 GCC14 的头文件。

方式行为
--gcc-version=13|14|15在 PATH 中寻找匹配大版本的最高支持编译器
--gcc <g++.exe>直接使用指定编译器,并读取其版本和 include 路径
不指定扫描 PATH,默认选择最高支持版本(15 → 14 → 13)
自动检测只扫描 PATH。安装在其他目录时,把它加入 PATH,或使用 --gcc,不要依赖固定盘符。

支持的标准 profile:

-std=c++11 C++11 profile -std=c++14 C++14 profile -std=c++17 C++17 profile -std=c++20 C++20 profile

常用命令行

参数作用
-P不输出 line markers
-o <file>输出文件
-I <dir>增加 include 目录
-isystem <dir>系统头目录
-D / -U定义 / 取消宏
-include <file>强制包含
-MD -MF -MT生成 Make/CMake 依赖文件
-finput-charset / -fexec-charset输入 / 执行字符集
--embed-dir <dir>#embed 搜索目录
--analysis-json <file>输出 include 图、宏 trace、PCH 记录

PCH

GCC 的 g++ -E 不会使用 .gch;PCH 只在真正编译时使用。CrucibleCpp 默认读取头文件源码,并可选地验证、登记和缓存外部生成的 PCH。

# 发现 .gch 时输出 warning --pch=warn # 发现 .gch 时直接报错 --pch=error # 在 analysis JSON 中记录被忽略的 PCH --pch=report

启用 PCH 缓存:

.\cruciblecpp-preprocessor.exe ` --pch-cache .cache\pch ` --pch-cache-stats .cache\pch\stats.json ` -P src\main.cpp -o build\main.i

缓存 manifest 会记录编译器路径、版本、编译器哈希和选项 hash。GCC13/14/15 的 PCH 不会互相误命中。

诊断

默认输出 GCC 风格源码行和 caret。可以关闭或调整:

-fdiagnostics-color=auto|always|never -fno-diagnostics-show-caret -fno-diagnostics-show-option -Werror -Wno-error=name --max-errors 20

支持 #pragma GCC diagnostic push/pop/ignored/warning/error 和 #pragma GCC system_header。来自 -isystem 的头默认抑制普通警告,-Wsystem-headers 可以重新显示。

故障排查

找不到标准库头文件

目标编译器不在 PATH。用 --gcc 指定,或把它的 bin 目录加入 PATH。也可以用 -isystem 显式传入。

选择了错误的 GCC 版本

用 --gcc-version=13|14|15 固定大版本,或用 --gcc 指向具体 g++.exe。不要混用 target profile 和另一版本的头文件。

PCH 缓存报 corrupt

PCH 与当前编译器/选项不匹配,或文件损坏。删除对应缓存条目后重新生成;也可以直接关闭 PCH 缓存,让它读取头文件源码。

输出无法被 GCC 编译

先确认预处理和编译使用的是同一个 GCC 版本与 -std。再用“CrucibleCpp 生成的 .i”单独编译,确认问题是否来自预处理阶段。

CrucibleCpp 是预处理器,不是编译器。它不负责代码生成、优化、链接和 GCC 二进制 PCH 的内部格式解析。