Documentation

Bắt đầu với lệnh đầu tiên

Trang này bao gồm cài đặt, chọn GCC đích, các dòng lệnh thường dùng, PCH, chẩn đoán và khắc phục sự cố. Phần triển khai đầy đủ và ma trận kiểm thử lấy theo repo GitHub.

Cài đặt

Tải gói nén Windows x64 và giải nén vào thư mục bất kỳ. CrucibleCpp là chương trình một tệp liên kết tĩnh, không cần cài runtime.

cruciblecpp-preprocessor.exe --version # cruciblecpp-preprocessor 3.0.1
Mục tiêu sản xuất hiện tại: Windows x64 + MinGW-w64 UCRT64. Các nền tảng, ABI và phiên bản GCC khác không được cam kết hỗ trợ.

Bắt đầu nhanh

Trước tiên hãy kiểm tra PATH có g++.exe. Sau đó chỉ cần thay thế g++ -E:

# Tiền xử lý .\cruciblecpp-preprocessor.exe -P -std=c++20 src\main.cpp -o build\main.i # Biên dịch bằng cùng một GCC g++ -std=c++20 build\main.i -o build\main.exe

Nếu chưa đưa GCC đích vào PATH, hãy dùng --gcc để chỉ định rõ:

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

Chọn GCC

CrucibleCpp sẽ dùng macro định nghĩa sẵn của GCC đích,__has_* dữ liệu và đường dẫn tìm kiếm include. Không dùng profile GCC15 để tiền xử lý header của GCC14.

Cách thứcHành vi
--gcc-version=13|14|15Tìm trong PATH trình biên dịch được hỗ trợ cao nhất khớp với phiên bản chính
--gcc <g++.exe>Dùng trực tiếp trình biên dịch đã chỉ định và đọc phiên bản cùng đường dẫn include của nó
Không chỉ địnhQuét PATH, mặc định chọn phiên bản được hỗ trợ cao nhất (15 → 14 → 13)
Tự động dò chỉ quét PATH. Nếu cài ở thư mục khác, hãy thêm nó vào PATH, hoặc dùng --gcc, và đừng phụ thuộc vào ký tự ổ đĩa cố định.

Các profile chuẩn được hỗ trợ:

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

Các dòng lệnh thường dùng

Tham sốMục đích
-PKhông xuất line markers
-o <file>Tệp đầu ra
-I <dir>Thêm thư mục include
-isystem <dir>Thư mục header hệ thống
-D / -UĐịnh nghĩa / hủy định nghĩa macro
-include <file>Buộc include
-MD -MF -MTTạo tệp phụ thuộc Make/CMake
-finput-charset / -fexec-charsetBộ ký tự đầu vào / thực thi
--embed-dir <dir>#embed — thư mục tìm kiếm
--analysis-json <file>Xuất đồ thị include, macro trace, bản ghi PCH

PCH

Lệnh g++ -E của GCC không dùng .gch; PCH chỉ được dùng khi biên dịch thực sự. CrucibleCpp mặc định đọc mã nguồn của header, và có thể tùy chọn xác thực, đăng ký và lưu đệm các PCH do bên ngoài tạo ra.

# Cảnh báo khi phát hiện .gch --pch=warn # Báo lỗi ngay khi phát hiện .gch --pch=error # Ghi các PCH bị bỏ qua vào analysis JSON --pch=report

Bật bộ đệm PCH:

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

Manifest của bộ đệm ghi lại đường dẫn trình biên dịch, phiên bản, hash trình biên dịch và hash tùy chọn. PCH của GCC13/14/15 không trúng nhầm lẫn nhau.

Chẩn đoán

Mặc định xuất dòng mã nguồn và caret kiểu GCC. Có thể tắt hoặc điều chỉnh:

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

Hỗ trợ #pragma GCC diagnostic push/pop/ignored/warning/error và #pragma GCC system_header. Các header đến từ -isystem mặc định ức chế cảnh báo thông thường, và-Wsystem-headers có thể hiển thị lại chúng.

Khắc phục sự cố

Không tìm thấy header thư viện chuẩn

Trình biên dịch đích không có trong PATH. Hãy dùng --gcc để chỉ định, hoặc thêm thư mục bin vào PATH. Bạn cũng có thể dùng -isystem để truyền vào một cách tường minh.

Đã chọn sai phiên bản GCC

Dùng --gcc-version=13|14|15 để cố định phiên bản chính, hoặc dùng --gcc để trỏ tới một tệp g++.exe. Không trộn profile đích với header của phiên bản khác.

Bộ đệm PCH báo corrupt

PCH không khớp với trình biên dịch/tùy chọn hiện tại, hoặc tệp bị hỏng. Hãy xóa mục bộ đệm tương ứng rồi tạo lại; cũng có thể tắt hẳn bộ đệm PCH để nó đọc mã nguồn của header.

Đầu ra không thể được GCC biên dịch

Trước tiên hãy chắc rằng tiền xử lý và biên dịch dùng cùng một phiên bản GCC và -std. Sau đó biên dịch riêng “.i do CrucibleCpp tạo ra” để xác định xem vấn đề có đến từ giai đoạn tiền xử lý hay không.

CrucibleCpp là bộ tiền xử lý, không phải trình biên dịch. Nó không chịu trách nhiệm sinh mã, tối ưu hóa, liên kết và phân tích định dạng bên trong của PCH nhị phân GCC.