دليل تشغيل البناء والإصدار وتصحيح الأخطاء للمكونات الأصيلة

يصف هذا الدليل كيفية إنتاج خط أنابيب البناء الخاص بـ @f5-sales-demo/pi-natives لإضافات .node، وكيفية تحميل التوزيعات المُجمَّعة لها، وكيفية تصحيح أخطاء المُحمِّل/فشل البناء.

يتبع هذا الدليل مصطلحات البنية المعمارية من docs/natives-architecture.md:

• إنتاج القطع الأثرية في وقت البناء (scripts/build-native.ts)
• توليد بيان الإضافة المضمّنة (scripts/embed-native.ts)
• تحميل الإضافة في وقت التشغيل + بوابة التحقق (src/native.ts)

ملفات التنفيذ

• packages/natives/scripts/build-native.ts
• packages/natives/scripts/embed-native.ts
• packages/natives/package.json
• packages/natives/src/native.ts
• crates/pi-natives/Cargo.toml

نظرة عامة على خط أنابيب البناء

1) نقاط دخول البناء

سكريبتات packages/natives/package.json:

• bun scripts/build-native.ts (build) → بناء إصدار الإنتاج
• bun scripts/build-native.ts --dev (dev:native) → بناء ملف التصحيح/التطوير (نفس تسمية المخرجات)
• bun scripts/embed-native.ts (embed:native) → توليد src/embedded-addon.ts من الملفات المبنية

2) بناء القطعة الأثرية بلغة Rust

يشغّل build-native.ts أداة Cargo في crates/pi-natives:

• الأمر الأساسي: cargo build
• يضيف وضع الإصدار --release ما لم يُمرَّر --dev
• يضيف الهدف العابر للمنصات --target <CROSS_TARGET>

يُعلن crates/pi-natives/Cargo.toml عن crate-type = ["cdylib"]، لذا تُصدر أداة Cargo مكتبة مشتركة (.so/.dylib/.dll) يتم نسخها/إعادة تسميتها لاحقاً إلى اسم ملف إضافة .node.

3) اكتشاف القطعة الأثرية وتثبيتها

بعد اكتمال Cargo، يفحص build-native.ts أدلة المخرجات المرشّحة بالترتيب:

1. ${CARGO_TARGET_DIR} (إن كان مُعيَّناً)
2. <repo>/target
3. crates/pi-natives/target

لكل جذر يتحقق من أدلة الملفات الشخصية:

• البناء العابر للمنصات: <root>/<crossTarget>/<profile> ثم <root>/<profile>
• البناء الأصيل: <root>/<profile>

ثم يبحث عن أحد الملفات:

• libpi_natives.so
• libpi_natives.dylib
• pi_natives.dll
• libpi_natives.dll

عند الاكتشاف، يُثبِّت الملف بصورة ذرية في packages/natives/native/ باستخدام دلالات الملف المؤقت + إعادة التسمية (يعالج احتياط Windows صراحةً حالات فشل استبدال DLL المقفولة).

نموذج الهدف/المتغير واصطلاحات التسمية

وسم المنصة

يستخدم كل من البناء ووقت التشغيل وسم المنصة:

<platform>-<arch> (مثال: darwin-arm64، linux-x64)

نموذج المتغير (x64 فقط)

يدعم x64 متغيرات المعالج:

• modern (مسار قادر على AVX2)
• baseline (احتياطي)

تستخدم المنصات غير x64 قطعة أثرية افتراضية واحدة (بدون لاحقة متغير).

أسماء ملفات المخرجات

بناءات الإصدار:

• x64: pi_natives.<platform>-<arch>-modern.node أو ...-baseline.node
• غير x64: pi_natives.<platform>-<arch>.node

بناء التطوير (--dev):

• يستخدم علامات ملف التصحيح لكنه يحتفظ بتسمية المخرجات القياسية ذات الوسم الخاص بالمنصة

ترتيب مرشّحات المُحمِّل في native.ts:

• مرشّحات الإصدار
• يُقدِّم وضع التجميع المرشّحات المستخرجة/المخزنة مؤقتاً قبل الملفات المحلية للحزمة

علامات البيئة وخيارات البناء

علامات وقت التشغيل

• PI_DEV (سلوك المُحمِّل): تمكين تشخيصات المُحمِّل
• PI_NATIVE_VARIANT (سلوك المُحمِّل، x64 فقط): فرض اختيار modern أو baseline في وقت التشغيل
• PI_COMPILED (سلوك المُحمِّل): تمكين سلوك مرشّح/استخراج الثنائيات المُجمَّعة

علامات/خيارات وقت البناء

• --dev (معامل السكريبت): بناء ملف التصحيح
• CROSS_TARGET: يُمرَّر إلى Cargo --target
• TARGET_PLATFORM: تجاوز تسمية وسم منصة المخرجات
• TARGET_ARCH: تجاوز تسمية بنية المخرجات
• TARGET_VARIANT (x64 فقط): فرض modern أو baseline لاسم ملف المخرجات وسياسة RUSTFLAGS
• CARGO_TARGET_DIR: جذر إضافي عند البحث في مخرجات Cargo
• RUSTFLAGS:
  • إذا لم تكن مُعيَّنة وليس هناك تجميع عابر للمنصات، يضبط السكريبت:
    • modern: -C target-cpu=x86-64-v3
    • baseline: -C target-cpu=x86-64-v2
    • غير x64 / بدون متغير: -C target-cpu=native
  • إذا كانت مُعيَّنة مسبقاً، لا يتجاوزها السكريبت

حالات البناء/انتقالات دورة الحياة

دورة حياة البناء (build-native.ts)

1. التهيئة: تحليل المعامِلات/البيئة (--dev، تجاوزات الهدف، علامات التجميع العابر)
2. تحديد المتغير:
   • غير x64 → لا متغير
   • x64 + TARGET_VARIANT → متغير صريح
   • بناء x64 عابر للمنصات بدون TARGET_VARIANT → خطأ فادح
   • بناء x64 محلي بدون تجاوز → اكتشاف AVX2 للمضيف
3. التجميع: تشغيل Cargo مع الملف الشخصي/الهدف المحدَّدين
4. تحديد موقع القطعة الأثرية: فحص جذور الهدف/أدلة الملف الشخصي/أسماء المكتبات
5. التثبيت: النسخ + إعادة التسمية الذرية في packages/natives/native
6. الاكتمال: الإضافة جاهزة لمرشّحات المُحمِّل

تحدث حالات الخروج بالفشل في أي مرحلة مع نص خطأ صريح (متغير غير صالح، فشل بناء cargo، مكتبة الإخراج مفقودة، فشل التثبيت/إعادة التسمية).

دورة حياة التضمين (embed-native.ts)

1. التهيئة: حساب وسم المنصة من TARGET_PLATFORM/TARGET_ARCH أو قيم المضيف
2. مجموعة المرشّحات:
   • يتوقع x64 كلاً من modern وbaseline
   • يتوقع غير x64 ملفاً افتراضياً واحداً
3. التحقق من التوفر في packages/natives/native
4. توليد البيان (src/embedded-addon.ts) مع استيرادات file لـ Bun وإصدار الحزمة
5. جاهزية استخراج وقت التشغيل لوضع التجميع

يتجاوز --reset التحقق ويكتب بذرة بيان فارغة (embeddedAddon = null).

سير عمل التطوير مقابل السلوك المشحون/المُجمَّع

سير عمل التطوير المحلي

الحلقة المحلية النموذجية:

1. بناء الإضافة:
   • إصدار الإنتاج: bun --cwd=packages/natives run build
   • ملف التصحيح: bun --cwd=packages/natives run dev:native
2. تعيين PI_DEV=1 عند اختبار تشخيصات المُحمِّل
3. يحلّ المُحمِّل في native.ts المرشّحات المحلية للحزمة native/ (واحتياط دليل الملف التنفيذي)
4. يفرض validateNative توافق الصادرات قبل استخدام الأغلفة للربط

سير عمل الثنائي المشحون/المُجمَّع

في وضع التجميع (PI_COMPILED أو علامات Bun المضمّنة):

1. يحسب المُحمِّل دليل ذاكرة التخزين المؤقت ذا الإصدار: <getNativesDir()>/<packageVersion> (تشغيلياً ~/.xcsh/natives/<version>)
2. إذا تطابق البيان المضمَّن مع المنصة+الإصدار الحاليَّين، قد يستخرج المُحمِّل الملف المضمَّن المحدَّد في ذلك الدليل ذي الإصدار
3. يتضمن ترتيب مرشّحات وقت التشغيل:
   • دليل ذاكرة التخزين المؤقت ذو الإصدار
   • دليل الثنائي المُجمَّع القديم (%LOCALAPPDATA%/xcsh على Windows، ~/.local/bin في غيره)
   • أدلة الحزمة/الملف التنفيذي
4. لا تزال أول إضافة تُحمَّل بنجاح يجب أن تجتاز validateNative

هذا هو السبب في ضرورة توافق توقعات التعبئة + مُحمِّل وقت التشغيل: يجب أن تتطابق أسماء الملفات ووسوم المنصات والرموز المُصدَّرة مع ما يفحصه native.ts ويتحقق منه.

تعيين JS API ↔ صادرات Rust (مجموعة فرعية من بوابة التحقق)

يتطلب native.ts وجود هذه الصادرات المرئية من JS على الإضافة المحمَّلة. تُعيَّن إلى صادرات N-API في Rust ضمن crates/pi-natives/src:

اسم JS المطلوب بواسطة validateNative	إعلان صادر Rust	ملف مصدر Rust
glob	#[napi] pub fn glob(...)	crates/pi-natives/src/glob.rs
grep	#[napi] pub fn grep(...)	crates/pi-natives/src/grep.rs
search	#[napi] pub fn search(...)	crates/pi-natives/src/grep.rs
highlightCode	#[napi] pub fn highlight_code(...)	crates/pi-natives/src/highlight.rs
getSystemInfo	#[napi] pub fn get_system_info(...)	crates/pi-natives/src/system_info.rs
getWorkProfile	#[napi] pub fn get_work_profile(...) (صادر بصيغة camelCase)	crates/pi-natives/src/prof.rs
invalidateFsScanCache	#[napi] pub fn invalidate_fs_scan_cache(...)	crates/pi-natives/src/fs_cache.rs

إذا كان أي رمز مطلوب مفقوداً، يفشل المُحمِّل بسرعة مع تلميح بإعادة البناء.

سلوك الفشل والتشخيصات

أعطال وقت البناء

• تكوين متغير غير صالح:
  • TARGET_VARIANT مُعيَّن على غير x64 → خطأ فوري
  • بناء x64 عابر للمنصات بدون TARGET_VARIANT صريح → خطأ فوري
• فشل بناء Cargo:
  • يعرض السكريبت الخروج غير الصفري ومخرجات stderr
• القطعة الأثرية غير موجودة:
  • يطبع السكريبت كل دليل ملف شخصي تم التحقق منه
• فشل التثبيت:
  • رسالة صريحة؛ يتضمن Windows تلميحاً بالملف المقفول

أعطال مُحمِّل وقت التشغيل (native.ts)

• وسم منصة غير مدعومة:
  • يطرح استثناءً مع قائمة المنصات المدعومة
• لا يمكن تحميل أي مرشّح:
  • يطرح استثناءً مع قائمة أخطاء المرشّحات الكاملة وتلميحات المعالجة الخاصة بالوضع
• صادرات مفقودة:
  • يطرح استثناءً مع أسماء الرموز المفقودة بالضبط وأمر إعادة البناء
• مشاكل استخراج التضمين:
  • يتم تسجيل أخطاء mkdir/write الخاصة بالاستخراج وتضمينها في التشخيصات النهائية

مصفوفة استكشاف الأخطاء وإصلاحها

العَرَض	السبب المحتمل	التحقق	الإصلاح
Native addon missing exports ... Missing: <name>	ثنائي .node قديم، عدم تطابق اسم صادر Rust، أو تحميل ثنائي خاطئ	التشغيل مع PI_DEV=1 لرؤية المسار المحمَّل؛ فحص قائمة الصادرات لذلك الملف	إعادة البناء build؛ التأكد من تطابق اسم صادر Rust #[napi] (أو الاسم المستعار الصريح عند الحاجة) مع مفتاح JS؛ حذف الملفات المخزنة/ذات الإصدار القديمة
جهاز x64 يحمّل baseline عندما يُتوقع modern	PI_NATIVE_VARIANT=baseline، عدم اكتشاف AVX2، أو وجود ملف baseline فقط	التحقق من PI_NATIVE_VARIANT؛ فحص native/ للملف -modern	بناء متغير modern (TARGET_VARIANT=modern ... build) والتأكد من شحن الملف
البناء العابر للمنصات ينتج ثنائياً غير قابل للاستخدام/مُوسَماً بشكل خاطئ	عدم تطابق بين CROSS_TARGET وTARGET_PLATFORM/TARGET_ARCH، أو غياب TARGET_VARIANT لـ x64	تأكيد مجموعة env واسم ملف المخرجات	إعادة التشغيل بقيم env متسقة وTARGET_VARIANT صريح لـ x64
فشل الثنائي المُجمَّع بعد الترقية	ذاكرة تخزين مؤقت مستخرجة قديمة (~/.xcsh/natives/<old-or-mismatched-version>) أو عدم تطابق البيان المضمَّن	فحص دليل natives ذي الإصدار وقائمة أخطاء المُحمِّل	حذف ذاكرة التخزين المؤقت لـ natives ذات الإصدار الخاص بإصدار الحزمة وإعادة التشغيل؛ إعادة توليد البيان المضمَّن أثناء التعبئة
يفحص المُحمِّل مسارات كثيرة ولا يجد أياً منها	عدم تطابق المنصة أو غياب القطعة الأثرية للإصدار في native/ الخاص بالحزمة	التحقق من platformTag مقابل اسم/أسماء الملف الفعلية	التأكد من أن اسم الملف المبني يتطابق تماماً مع اصطلاح pi_natives.<platform>-<arch>(-variant).node وأن الحزمة تتضمن native/
يفشل embed:native بـ “Incomplete native addons”	ملفات المتغير المطلوبة لم تُبنَ قبل التضمين	التحقق من قائمة المتوقع مقابل الموجود في نص الخطأ	بناء الملفات المطلوبة أولاً (x64: كلاً من modern+baseline؛ غير x64: الافتراضي)، ثم إعادة تشغيل embed:native

أوامر التشغيل

# قطعة أثرية للإصدار للمضيف الحالي
bun --cwd=packages/natives run build

# بناء قطعة أثرية لملف التصحيح
bun --cwd=packages/natives run dev:native

# بناء متغيرات x64 الصريحة
TARGET_VARIANT=modern bun --cwd=packages/natives run build
TARGET_VARIANT=baseline bun --cwd=packages/natives run build

# توليد بيان الإضافة المضمّنة من الملفات الأصيلة المبنية
bun --cwd=packages/natives run embed:native

# إعادة تعيين البيان المضمَّن إلى بذرة فارغة
bun --cwd=packages/natives run embed:native -- --reset