>_ ash

المساهمة · البناء · تصحيح الأخطاء

دليل المطور

دليل عملي لإعداد الخروج، واختيار تحديد الأهداف، وفهم منشئي الإصدارات، وتشخيص سجلات وقت التشغيل، واختبار عمليات تثبيت الحزم الأصلية في أجهزة Tart الافتراضية.

قم بإعداد سلسلة أدوات المطور

يستخدم المشروع Go لـ CLI والوسيط، بالإضافة إلى سلاسل أدوات المكونات الإضافية الأصلية وأدوات جودة الموقع. على نظام التشغيل ماك،make configيستخدم البيرة. على Debian أو Ubuntu يستخدم apt. يقوم بتثبيت Go وNode.js/npm وPython،uvوالصدأ/البضائع والوبر وأدوات الأمان الخاصة بالمشروع. تحدد وحدة Go الخاصة بالمستودع إصدار Go المتوقع بواسطة البناء.

make config

تستخدم أدوات تثبيت macOS أيضًا أدوات سطر أوامر Xcode من Apple. التعبئة والتغليف لينكس.debو.rpmالتحف تتطلب روبي،fpm، وأدوات التغليف RPM. يقوم البرنامج النصي للإعداد بتثبيت المتطلبات الأساسية الشائعة، ولكن قد تظل هناك حاجة إلى أدوات التعبئة الخاصة بالنظام الأساسي لبناء الإصدار.

للحصول على تفاصيل الإعداد لأول مرة وتوقعات المساهمة، راجعالمساهمة.md.

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

لتغيير الكود العادي، قم بتشغيل الاختبارات المركزة أثناء التكرار، ثم قم بتشغيل الوبر المطلوب للمستودع وبوابات الاختبار قبل الانتهاء:

go test ./internal/app -run 'TestName'
make check-static
make check-security
make test

يتم استخدام معظم الأهدافscripts/dev/run-quiet.sh: الخطوات الناجحة طباعة واحدة مختصرةokسطر، في حين أن الخطوات الفاشلة تطبع مخرجاتها التي تم التقاطها. بادئة الهدف بـV=1لدفق الإخراج الكامل أثناء تشغيله:

make V=1 lint
make V=1 test
make V=1 verify

V=1يتحكم في غلاف Make الهادئ. إنه منفصل عنASH_VERBOSE، والذي يتيح تشخيص وقت التشغيل فيAshبرنامج.

إنشاء مرجع الهدف

make pre-push
يشغّل الفحوصات الثابتة وفحوصات الأمان والتبعيات واكتشاف الأسرار والاختبارات على عمليات الإيداع الصادرة نفسها. يثبّت make config خطاف المستودع. يمكن تجاوز الخطافات المحلية، وهي ليست فحوصات يفرضها الخادم.
make lint
التحقق من كتالوجات الترجمة، وبناء جملة Shell لمثبت الموقع، وسير العمل YAML، وPython Lint/format، وMarkdown، وPlugin Lint، وGo lint.
make test
يبني ويختبر المكونات الإضافية الأصلية، ثم يقوم بتشغيلهاgo test ./....
make verify-ci
يشغّل فحوصات ما قبل الدفع قبل إنشاء وسم الإصدار الليلي. لا تعيد CI الخاصة بالملفات، التي يبدأها الوسم، فحوصات المصدر.
make verify
يدير بوابة الجودة المحلية الكاملة: الوبر، والاختبارات، واختبارات السباق، والتغطية، والطبيب البيطري، والتحليل الثابت، والأمن، والمسح السري، والتشويش، والمعايير.
make test-race
يجري اختبارات Go باستخدام كاشف السباق.
make test-cover
يكتبcoverage.outويتحقق من المجموع ضدCOVERAGE_MIN(60% بشكل افتراضي).
make test-fuzz
تشغيل اختبارات زغب التطبيق لـFUZZ_TIME(10 ثواني بشكل افتراضي).
make security
يشغّل gosec وgovulncheck وتدقيق تبعيات npm وCargo وPython.
make build
يقوم بتشغيل الوبر والاختبار، ويبني ويثبت المكونات الإضافية الأصلية، ويبنيashزائدash-brokerتحت~/.local/bin.
make install
يدير الاختبارات، والوبر،gosec، وبناء/تثبيت البرنامج المساعد، يبني كلا الثنائيات، ثم يعملash install --shell bash --shell-integration --overwrite. استخدمه عندما تنوي تحديث تكامل Bash المحلي.
make plugins-build,plugins-test,plugins-lint
قم ببناء أو اختبار أو فحص كل مكون إضافي تحتهinternal/app/ash_bootstrap/plugins_src.make plugins-cleanيزيل مخرجات بناء البرنامج المساعد المحلي.
make site-locales
يقوم بإنشاء صفحات مترجمة وتحديث خريطة الموقع. يستخدمmake site-locales SITE_LOCALES="zh-TW lb_LU"لتحديد اللغات.

make allيديرverifyوثمinstall. الوصفات المستهدفة الكاملة والمتغيرات القابلة للتجاوز موجودة في ملفملف تعريف.

بناة البرنامج المساعد

المكونات الإضافية هي ملفات تنفيذية مستقلة بعقد مستقل عن اللغة. يقوم البرنامج المساعد Makefiles بتحديد سلسلة أدوات كل مكون إضافي؛ تستهدف الإصدارات المحلية المضيف افتراضيًا. إصدار يبني تمريرةPLUGIN_TARGET_GOOSوPLUGIN_TARGET_GOARCHلذا فإن Rust والثنائيات الإضافية الأخرى غير التابعة لـ Go تتطابق مع قطعة الإصدار.

يستخدمmake plugins-buildلبناء لهم فيbin/plugins,make plugins-testلإجراء اختباراتهم، وmake plugins-installلنسخها إلى دليل البرنامج المساعد للمستخدم. انظرعقد البرنامج المساعد الأصليقبل إضافة أو تغيير البرنامج المساعد.

الافراج عن بناة والتحف

بعد فحوص الجودة، يشغّل GitHub الأمر make release-artifacts على Linux. تبني مهمة Ubuntu واحدة أرشيفات macOS لمعالجَي Intel وApple Silicon لصالح Homebrew، دون مشغّلات macOS أو مثبّتات .pkg. تستبعد أهداف macOS جميع إضافات Rust، ومنها flip_a_coin، حتى في البناء المحلي. يحتفظ Linux وFreeBSD بإضافات Rust.

تتحقق CI من محتويات أرشيفات macOS وبنى Mach-O دون تشغيل ملفاتها التنفيذية. يحتفظ Linux وFreeBSD باختبارات تشغيل الأرشيفات المستخرجة؛ لا تُثبّت الحزم أو تكاملات الصدفة. لبناء macOS على Linux: make release-artifacts RELEASE_TARGET_OSES=darwin RELEASE_TARGET_ARCHES="amd64 arm64" RELEASE_MACOS_PKG=0 RELEASE_VERSION=v1.2.3. ما زال make release ينشئ .pkg محليًا على macOS دون إرسال الملفات التنفيذية المحلية إلى CI.

بالنسبة إلى تصميمات القطع الأثرية المحلية، حدد نظام التشغيل المستهدف والبنية والإصدار بشكل صريح:

make release-artifacts \
  RELEASE_TARGET_OSES=linux \
  RELEASE_TARGET_ARCHES="arm64 amd64" \
  RELEASE_VERSION=v1.2.3

release-artifactsيبني ويتحقق من صحة التنسيقات المدعومة لهذا الهدف. الإعدادات الافتراضية هي نظام التشغيل المضيف (auto) وكلاهماamd64 arm64; يقتصر النشر على FreeBSD علىamd64. التحف تذهب تحتdist/release. لإنشاء ثنائي/مكون إضافي واحد، استخدمmake release-build-one RELEASE_GOOS=linux RELEASE_ARCH=arm64 RELEASE_VERSION=v1.2.3.

make versionيدير عمليات التحقق من الإصدار ويبني القطع الأثرية دون نشرها. في المقابل،make releaseهو سير عمل نشر: فهو يتطلب نظام التشغيل macOS، وشجرة عمل نظيفة وهوية Git التي تم تكوينها، وينشئ ملاحظات الإصدار، وينشئ/يدفع مراجع الإصدار، ويراقب سير عمل GitHub. قناتها الافتراضية هي النسخة التجريبية. حدد مستقرًا أو ليلاً معCHANNEL=stableأوCHANNEL=nightly. تتطلب ملاحظات الإصدار التي تم إنشاؤهاASH_AI_ENDPOINTوASH_AI_MODEL، ما لم يتم توفير الملاحظات معRELEASE_NOTES_INPUT.

اقرأالافراج عن سير العملودليل أسرار الافراجقبل النشر.

تسجيل وقت التشغيل مطول

ASH_VERBOSEتمكين تسجيل تصحيح أخطاء JSON المنظم وطباعة لوحة معلومات التنفيذ من قبلAshمخارج. القيم المقبولة هي1,y,yes,true,on، وdebug، غير حساس لحالة الأحرف. تلخص لوحة المعلومات توقيتات المرحلة وعدد استدعاءات الأدوات وإجماليات الرموز المميزة عند توفرها وإجمالي الوقت الفعلي.

ASH_VERBOSE=1 ash "investigate this error"

ASH_VERBOSE=1 \
ASH_LOG_FILE="$HOME/.local/state/ash/debug.jsonl" \
ASH_LOG_MAX_BYTES=10485760 \
ash "investigate this error"

متىASH_LOG_FILEتم تعيينه، تتم كتابة سجلات سجل JSON المطولة على هذا المسار؛ يتم إنشاء الدليل الأصلي حسب الحاجة.ASH_LOG_MAX_BYTESيتحكم في التدوير والإعدادات الافتراضية1048576بايت (1 ميجابايت). بدون ملف سجل صريح، يستخدم إخراج التصحيح كاتب تشخيص العملية. حافظ على خصوصية السجلات وراجعها قبل مشاركتها.

وهذا يختلف عن MakeV=1: يستخدمV=1لرؤية إخراج أمر البناء/الاختبار وASH_VERBOSE=1لتشخيصAshاستدعاء وقت التشغيل.

ابحث عن مصدر سجل السجل

كل استدعاء تسجيل Ash يحتوي على حقل EID فريد. انسخ معرف EID من سجل JSON وابحث عن حرفه في مصدر Go للعثور على موقع الاتصال:

rg '"EID", "EpbG2YtZ"' internal/

على سبيل المثال، يقوم استدعاء المصدر بتسجيل الرسالة ومعرف EID مع السياق المنظم. تعد معرفات EID معرفات ثابتة لمواقع السجل: لا تقم بترجمتها أو إعادة تسميتها أو إعادة استخدامها. يتم تنفيذ مسجل التصحيح وسلوك التدوير الخاص بهInternal/app/debuglog.go.

اختبار عمليات تثبيت الحزمة الأصلية باستخدام vm.sh

scripts/vm.sh يكتشف نظام التشغيل المضيف ويحدد واجهة VM الخلفية: Tart على Apple Silicon macOS، أو QEMU/KVM على x86_64 Linux. يمكن لكلا الواجهتين الخلفيتين اختبار APT على Ubuntu/Debian وDNF على Fedora/Rocky Linux. يمكن لـ Tart على macOS أيضًا اختبار حزمة macOS Homebrew؛ لا يمكن لمضيفي Linux تشغيل ضيوف macOS، وبالتالي لا يمكنهم اختبار هذا المسار.

المتطلبات الأساسية لمضيف macOS

استخدم جهاز Apple Silicon Mac يعمل بنظام macOS 13 أو أحدث، مع تثبيت Tart، والوصول إلى الشبكة إلى صورة VM ومستودع Ash، ومساحة كافية على القرص لجهاز VM. قم بتثبيت Tart باستخدام Homebrew إذا لزم الأمر:

brew install openai/tools/tart

المتطلبات الأساسية لمضيف Linux

استخدم مضيف Linux x86_64 مع تمكين المحاكاة الافتراضية للأجهزة وحساب مستخدم يمكنه القراءة والكتابة/dev/kvm(عادة عن طريق الانضمام إلىkvmالمجموعة وتسجيل الدخول مرة أخرى). قم بتثبيت QEMU/KVM وأدوات الصور السحابية لـcloud-localdsوcurl وأدوات عميل OpenSSH وPython 3. أمثلة لأوامر الحزمة:

# Debian or Ubuntu
sudo apt-get install qemu-system-x86 qemu-utils cloud-image-utils curl openssh-client python3

# Fedora or Rocky Linux
sudo dnf install qemu-kvm qemu-img cloud-utils curl openssh-clients python3

تقوم الواجهة الخلفية لنظام التشغيل Linux بتشغيل الصور السحابية x86_64 Ubuntu أو Debian أو Fedora أو Rocky باستخدام QEMU/KVM وcloud-init. يستخدم شبكة وضع المستخدم QEMU مع إعادة توجيه SSH إلى المضيف المحلي؛ ليست هناك حاجة إلى إعداد شبكة libvirt. لا يقوم بتشغيل ضيوف macOS، ولا يختبر Homebrew على macOS، ويتطلب حاليًا مضيف Linux x86_64. Arch وFreeBSD ليست أهدافًا مدعومة.

قم بإجراء اختبار الحزمة

الوضع التلقائي هو الوضع الافتراضي ويقوم بإزالة الجهاز الظاهري بعد الاختبار. يتبع النظام الأساسي الافتراضي المضيف: يختاره macOSmacosلينكس يختارubuntu. اختر نظامًا أساسيًا ووضعًا مدعومًا آخر بشكل صريح. قناة الحزمة الافتراضية هيbeta; يستخدم--channel nightly,--channel beta، أو--channel releaseلاختيار واحد.--channel stableهو اسم مستعار لrelease.

scripts/vm.sh --platform macos --mode interactive
scripts/vm.sh --platform ubuntu --channel nightly --mode automated
scripts/vm.sh --platform debian --mode interactive
scripts/vm.sh --platform fedora --mode automated
scripts/vm.sh --platform rocky --mode interactive

يترك الوضع التفاعلي الجهاز الظاهري المثبت قيد التشغيل للاختبار اليدوي. على نظام التشغيل macOS، قم بتشغيل الأمر tart exec -it المطبوع في الوحدة الطرفية لفتح shell الضيف. يؤدي الخروج من تلك الصدفة إلى ترك الجهاز الظاهري قيد التشغيل؛ إغلاق الضيف أو إيقافه عن المضيف. لإيقاف جهاز Tart VM المحتجز وحذفه، استخدم:

tart stop VM_NAME && tart delete VM_NAME

في Linux، يقوم البرنامج النصي بطباعة أمر SSH وأمر إيقاف؛ أوقف الجهاز الافتراضي وأزل حالته باستخدام:

scripts/vm.sh --stop VM_NAME

يعمل الوضع التلقائي على تشغيل عمليات التثبيت وفحص دخان إعداد الغلاف، ثم يقوم بإيقاف الجهاز الظاهري وإزالته. تظل الصور الأساسية التي تم تنزيلها مخزنة مؤقتًا. يمكن تغيير الصور اللاذعة معASH_TEST_VM_IMAGE; يمكن تجاوز عناوين URL للصور السحابية لنظام Linux باستخدامASH_TEST_QEMU_IMAGE. يتم تخزين صور Linux مؤقتًا ضمن${XDG_CACHE_HOME:-~/.cache}/ash/vm-images، ويتم الاحتفاظ بأقراص VM التفاعلية ومفاتيح SSH بالأسفل${XDG_STATE_HOME:-~/.local/state}/ash/vm. تعيينASH_TEST_VM_CACHE_DIRأوASH_TEST_VM_STATE_DIRلتغيير تلك المواقع.

للسماح للضيف بالاتصال بنفس خدمة الذكاء الاصطناعي مثل المضيف، قم بتصدير ما هو مطلوبASH_AI_*المتغيرات قبل تشغيل البرنامج النصي، على سبيل المثالASH_AI_ENDPOINT,ASH_AI_MODEL، وعند الحاجة،ASH_AI_AUTH_TOKEN. يتم إرسال القيم المصدرة إلى الضيف؛ متغيرات الصدفة غير المصدرة ليست كذلك. تحتفظ أجهزة VM التفاعلية ببيانات الاعتماد هذه في ملف تعريف الضيف باستخدام الوضع0600; أقراص Linux VM غير مشفرة، لذا قم بحماية دليل الحالة وأوقف/أزل VM عند الانتهاء.

يرىscripts/vm.sh --helpللمتطلبات الأساسية الحالية للواجهة الخلفية والأنظمة الأساسية المدعومة والخيارات.

أدلة مصدر المشروع

  • دليل المساهمة- الإعداد والاختبارات وتوقعات الإصدار وملاحظات CI.
  • بنيان— تخطيط المشروع والأنظمة الفرعية لوقت التشغيل.
  • التمهيدي- مرجع المنتج والتثبيت والتكوين والبيئة.
  • ملف تعريف- وصفات الهدف الموثوقة وبناء المتغيرات.
  • سير عمل جيثب— CI، وبناة المنصات، وأتمتة النشر.