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 的內部格式解析。