Documentation

ابدأ من أول أمر

تغطي هذه الصفحة التثبيت، واختيار GCC الهدف، واستخدامات سطر الأوامر الشائعة، وPCH، والتشخيص، واستكشاف الأخطاء وإصلاحها. التنفيذ الكامل ومصفوفة الاختبارات معتمدان في مستودع GitHub.

التثبيت

نزّل أرشيف Windows x64 وفكّ ضغطه في أي دليل. CrucibleCpp برنامج أحادي الملف مرتبط ساكنيًا، لذلك لا حاجة إلى تثبيت وقت تشغيل.

cruciblecpp-preprocessor.exe --version # cruciblecpp-preprocessor 3.0.1
هدف الإنتاج الحالي: Windows x64 + MinGW-w64 UCRT64. لا يضمن الدعم على منصات أو ABIs أو إصدارات 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. لا تستخدم profile الخاص بـ GCC15 لمعالجة رؤوس 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 المولّدة خارجيًا وتسجيلها وتخزينها مؤقتًا.

# إخراج warning عند العثور على ملف .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 المترجم وhash الخيارات. ولا تتصادم ملفات PCH الخاصة بـ GCC13/14/15 بعضها مع بعض.

التشخيص

يُخرِج افتراضيًا أسطر مصدر بأسلوب 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. ثم جمّع ملف «.i» الناتج عن CrucibleCpp منفردًا للتأكد مما إذا كانت المشكلة من مرحلة المعالجة المسبقة.

CrucibleCpp معالج مسبق، وليس مترجمًا. وهو غير مسؤول عن توليد الشيفرة أو التحسين أو الربط أو تحليل التنسيق الداخلي لملفات PCH الثنائية الخاصة بـ GCC.