Documentation

از نخستین دستور شروع کنید

این صفحه نصب، انتخاب GCC هدف، دستورهای پرکاربرد خط فرمان، PCH، تشخیص و عیب‌یابی را پوشش می‌دهد. پیاده‌سازی کامل و ماتریس آزمون‌ها در مخزن GitHub مرجع است.

نصب

بسته Windows x64 را دانلود و در هر دایرکتوری که خواستید استخراج کنید. CrucibleCpp برنامه‌ای تک‌فایل و لینک‌شده به‌صورت استاتیک است و نیازی به نصب runtime ندارد.

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 استفاده می‌کند. برای پیش‌پردازش هدرهای GCC14 از پروفایل GCC15 استفاده نکنید.

روشرفتار
--gcc-version=13|14|15جست‌وجو در PATH برای بالاترین کامپایلر پشتیبانی‌شده با همان نسخه اصلی
--gcc <g++.exe>استفاده مستقیم از کامپایلر مشخص‌شده و خواندن نسخه و مسیرهای include آن
بدون تعییناسکن PATH با انتخاب پیش‌فرض بالاترین نسخه پشتیبانی‌شده (15 → 14 → 13)
تشخیص خودکار فقط PATH را اسکن می‌کند. اگر در دایرکتوری دیگری نصب شده است، آن را به PATH اضافه کنید یا از --gccاستفاده کنید و به حرف درایو ثابت وابسته نباشید.

پروفایل‌های استاندارد پشتیبانی‌شده:

-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>include اجباری
-MD -MF -MTتولید فایل‌های وابستگی Make/CMake
-finput-charset / -fexec-charsetمجموعه نویسه ورودی / اجرا
--embed-dir <dir>#embed دایرکتوری جست‌وجو
--analysis-json <file>خروجی گراف include، trace ماکرو و رکوردهای PCH

PCH

دستور g++ -E فایل‌های .gchرا به کار نمی‌برد؛ PCH فقط هنگام کامپایل واقعی استفاده می‌شود. CrucibleCpp به‌طور پیش‌فرض سورس هدرها را می‌خواند و به‌صورت اختیاری PCHهای تولیدشده در بیرون را اعتبارسنجی، ثبت و کش می‌کند.

# هنگام یافتن .gch هشدار تولید کن --pch=warn # هنگام یافتن .gch مستقیماً خطا بده --pch=error # ثبت PCHهای نادیده‌گرفته‌شده در analysis JSON --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 گزینه‌ها را ثبت می‌کند. PCHهای GCC13/14/15 به‌اشتباه روی هم نمی‌افتند.

تشخیص

به‌طور پیش‌فرض سطرهای منبع و caret را به سبک GCC خروجی می‌دهد. می‌توان خاموش یا تنظیم کرد:

-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. پروفایل هدف را با هدرهای نسخه دیگر مخلوط نکنید.

کش PCH خطای corrupt می‌دهد

PCH با کامپایلر/گزینه‌های فعلی هم‌خوان نیست یا فایل آسیب دیده است. ورودی کش مربوطه را حذف و دوباره تولید کنید؛ می‌توانید کش PCH را کاملاً خاموش کنید تا سورس هدرها خوانده شود.

خروجی با GCC کامپایل نمی‌شود

ابتدا مطمئن شوید که پیش‌پردازش و کامپایل از یک نسخه GCC و همان -std استفاده می‌کنند. سپس فایل «.i تولیدشده توسط CrucibleCpp» را جداگانه کامپایل کنید تا ببینید مشکل از مرحله پیش‌پردازش است یا نه.

CrucibleCpp یک پیش‌پردازنده است، نه کامپایلر. تولید کد، بهینه‌سازی، پیوند و تجزیه ساختار داخلی PCH باینری GCC وظیفه آن نیست.