التوثيق
التطوير المحلي باستخدام LayerFS
تتضمن مستودعات Native Shell سير عمل محلي لـ LayerFS لاختبار مساحات البناء القابلة لإعادة الاستخدام. يستورد سير العمل شجرة مصدرية تم إيداعها (commit)، ثم يشغّل Cargo داخل Linux Sandbox، ويحفظ الملفات الناتجة، ثم يعيد تشغيل الاختبارات من fork للحالة المحفوظة. يتم تحرير المصدر وإيداعات Git في نسخة NSH الحالية لديك.
#ما الذي تحفظه اللقطة
يحفظ LayerFS شجرة نظام ملفات: ملفات المصدر، وبيانات Git الوصفية، والملفات المتجاهَلة، ومخرجات البناء التي أُنشئت داخل مساحة العمل. يبدأ الـ fork من شجرة محفوظة ويسجّل تغييراته الخاصة. هذا يتيح لعدة مهام أن تبدأ من الحالة المبنية نفسها مع إبقاء تغييراتها منفصلة.
في التجربة المحلية لـ NSH، يشغّل الفرع الأول اختبارات nsh-package ويحفظ target/ بالإضافة إلى ملف اختبار متجاهَل. يبدأ الفرع الثاني من ذلك الإيداع، ويتحقق من تلك الملفات، ويعيد تشغيل الاختبارات دون اتصال بالإنترنت. ويبدأ فرع ثالث من حالة المصدر الأصلية للتحقق من العزل.
| المرحلة | ما الذي يحدث |
|---|---|
| التهيئة (Init) | استيراد تصدير لإيداع HEAD في النسخة الحالية ودليل .git جديد |
| البناء (Build) | إنشاء fork لمساحة عمل وتشغيل cargo +1.98.1 test --locked -p nsh-package |
| الإيداع (Commit) | حفظ target/ الناتج وملف الاختبار في سجل LayerFS |
| إعادة الاستخدام (Reuse) | إنشاء fork للفرع المحفوظ وتركيبه وإعادة تشغيل الاختبارات باستخدام --offline |
| التحقق (Verify) | قراءة سجل الإيداعات والتأكد من أن فرع المصدر الأصلي ما زال نظيفًا |
ينشئ كل استدعاء Store جديدًا وينفّذ هذا التسلسل الكامل. تحدث إعادة استخدام اللقطة بين فروع ذلك الاستدعاء. الفائدة التي تقيسها التجربة هي تكلفة الوصول إلى مساحة عمل أخرى قابلة للاستخدام ومختبَرة، بما في ذلك وقت التركيب والإيداع وإلغاء التركيب.
#تجهيز بيئة التطوير
استخدم نسخة من مستودع NSH مع ما يلي:
- محرك Docker محلي على Linux مع ext4 أو XFS أو Btrfs لحجم Store الخاص به، ويعمل على Linux أو عبر بيئة macOS مثل OrbStack.
- Docker Engine يخدم API بالإصدار 1.54 أو أحدث؛ يستخدم الإعداد المحلي الذي جرى التحقق منه Engine 29.7.2.
/dev/fuse، مع السماح لـ Docker بإتاحة ذلك الجهاز وCAP_SYS_ADMINلـ Sandbox.- Git وPython 3.12 أو أحدث؛ وعلى Linux، rustup ومترجم C/C++.
- اتصال بالشبكة لجلب مصدر LayerFS المثبّت وتبعيات Cargo وصورة وقت التشغيل.
تبني التجربة LayerFS 1.0.0، المثبّت على إيداع المصدر
2aaf2552ce21154928b9f9c83582e41a637f5910. توفر صورة وقت التشغيل الخاصة به Rust 1.98.1 وNode وclang لعمليات Linux. يصف دليل SDK الأصلي
دورة حياة Store وSandbox.
شغّل هذه الأوامر من جذر نسخة NSH:
./scripts/layerfs prepare
./scripts/layerfs smoke
./scripts/layerfs statusيختار الملف التنفيذي Python 3.12 أو أحدث، بما في ذلك تثبيت Homebrew على macOS، ويكتشف المقبس (socket) من سياق Docker النشط. استخدم --docker-socket PATH لتحديد مقبس محلي صراحةً.
يتحقق prepare من Docker API، ويثبّت Rust 1.85.1، ويبني الخدمة الخلفية (daemon) المثبّتة وإضافة Node وصورة وقت التشغيل. على macOS يجهّز هذه المكونات في حاوية بناء Linux مؤقتة. ويعيد استخدام سجل Cargo المعتاد وtarget/، بما في ذلك إعداد CARGO_TARGET_DIR الموجود. يُسجَّل المعرّف الدقيق لصورة وقت التشغيل ومسار daemon في
.nsh/layerfs/deployment.json. يتحقق status من مخرجات البناء المحفوظة والصورة ويعرض أحدث نتيجة تحقق.
ينشئ smoke الملف .nsh/layerfs/nsh-<id>/input من HEAD المودَع في النسخة الحالية، ثم يستورد هذا المدخل إلى Store جديد. لتضمين تعديلات المصدر، أودِعها في فرع الموضوع الخاص بك قبل تشغيله. يبدأ المدخل المُنشأ بمستودع Git جديد ويحصل على مخرجات البناء داخل Sandbox.
تفتح عملية التحكم Store في حجم Docker محلي مسمّى. تفتح خدمة Sandbox الخلفية Store نفسه وتركّب عرض نظام ملفات الفرع؛ وينفَّذ Cargo في مساحة العمل المركّبة تلك. تبقى نسخة الإيداع العادية لديك هي المكان الذي تحرر فيه تغييرات المصدر وتودعها.
#قراءة النتيجة
يطبع الأمر دليل الإيصالات (receipt) واسم حجم Store. افتح result.json المُنشأ للتحقق من
"ok": true والوقت المنقضي لكل مرحلة. يحتوي الدليل نفسه على settings.json، الذي يحدد إيداع المصدر والصورة، وtrace.jsonl، الذي يسجّل استدعاءات SDK.
شغّل التحقق المحلي 22 اختبار حزمة في كل من مرحلتي البناء وإعادة الاستخدام. تضمنت مرحلة البناء/الاختبار الأولية تنزيل التبعيات؛ أما المرحلة دون اتصال فاستخدمت target/ المحفوظ وسجل Cargo الخاص بـ Sandbox نفسه. قارن الدورة الكاملة ببناءات Cargo العادية على حمل العمل لديك عند تقييم قيمتها.
استخدم أنظمة تشغيل ومعماريات وسلاسل أدوات وتبعيات متطابقة عند إعادة استخدام حالة مبنية. حمل العمل في هذا الدليل هو مجموعة اختبارات Linux nsh-package؛ أما فحوصات واجهة المستخدم الخاصة بالمنصات فتستخدم بيئات منصاتها الخاصة
(الاختبار).
#الاحتفاظ بالعمل المفيد وإدارة Store
أبقِ تغييرات المصدر في Git وقدّمها عبر pull requests. تستخدم التجربة ملف تعريف Store من نوع Disposable في LayerFS لسجل مساحات العمل القابلة لإعادة البناء. احتفظ بالإيصالات المفيدة بشكل منفصل عند تسجيل القياسات.
يعطّل المدخل المُنشأ صيانة Git التلقائية أثناء إيداعه الأولي، مما يبقي قاعدة بيانات الكائنات مستقرة بينما يستوردها LayerFS. تستخدم فحوصات حالة Git داخل التجربة --no-optional-locks حتى تحافظ قراءة الحالة على الفهرس (index) الأصلي. وبالنسبة إلى السكربتات المخصصة، أنهِ كل عمليات الكتابة في الخلفية قبل استيراد شجرة أو إيداعها.
تتوقف Sandboxes غير المركّبة الناجحة بعد مهلة الخمول في LayerFS. تحتفظ كل تجربة بحجم Store الخاص بها؛ أدِر ذلك الحجم المحدد وحاوياته وفق المعرّفات الموجودة في الإيصال. تحتفظ العملية الفاشلة بحالتها المسجّلة للتشخيص. يغطي مرجع المشرفين السكربتات والإيصالات وتنظيف الموارد.