حزم Zero: شرح ملف zero.json ومجلد src/ والأهداف

لماذا الحزم

ملف .0 واحد يكفي حين تتعلّم اللغة أو تجرّب مقتطفًا. لكن في اللحظة التي يكبر فيها مشروعك ويتجاوز ملفًا واحدًا، تريد حزمة — مجلدًا فيه بيان وتخطيط معروف تفهمه سلسلة الأدوات.

فوائد الانتقال من ملفات متفرّقة إلى حزمة:

• مكان واحد موحَّد لاسم المشروع وإصداره وبياناته الوصفية.
• نقاط دخول متعدّدة (ملف تنفيذي، مكتبة، اختبارات) في شجرة واحدة.
• تخطيط متوقَّع: تستطيع الأدوات إيجاد مصدرك دون إعدادات.
• zero check وzero build على الشجرة كاملةً، لا ملفًا تلو الآخر.

إنشاء حزمة من قالب

أسرع طريقة للبدء هي zero new:

zero new cli hello

يُنشئ مجلد hello/ بهذا التخطيط:

hello/
├── zero.json
└── src/
    └── main.0

‏cli اسم القالب — يُنتج برنامج سطر أوامر تنفيذي. القوالب الأخرى (مكتبة، برنامج نظام) تتبع الشكل نفسه بقيم افتراضية مختلفة.

ادخل إلى المجلد الجديد، شغّله، وانطلق:

cd hello
zero run

عندما تستدعي zero run من داخل مجلد حزمة دون تسمية ملف، يأخذ الهدف الافتراضي من zero.json ويُشغّله.

بيان zero.json

البيان من حزمة cli المنشأة من قالب يبدو هكذا:

{
    "package": { "name": "hello", "version": "0.1.0" },
    "targets": { "cli": { "kind": "exe", "main": "src/main.0" } }
}

مفتاحان على المستوى الأعلى: package وtargets. الأوّل يُعرّف الحزمة؛ والثاني يُخبر المترجم بما يُبنى.

package

"package": {
    "name": "hello",
    "version": "0.1.0"
}

• name — مُعرِّف يُحدّد الحزمة. استخدم أحرفًا صغيرة وشرطات.
• version — سلسلة semver. الحزم قبل الإصدار 1.0 تستخدم 0.x.y.

قد تُدعَم حقول بيانات وصفية أخرى (وصف، مؤلّف، رخصة، مستودع) — راجع توثيق Zero الحالي للحصول على المخطّط الموثَّق لأن البيان لا يزال يتطوّر.

targets

"targets": {
    "cli": { "kind": "exe", "main": "src/main.0" }
}

المفاتيح (cli هنا) هي أسماء أهداف تختارها أنت. القيم تصف كل هدف:

• kind — ما هو الهدف. exe لملف تنفيذي. أنواع أخرى (مكتبة، اختبار) تتبع الشكل نفسه.
• main — ملف مصدر نقطة الدخول، نسبةً إلى جذر الحزمة.

تستطيع تعريف أكثر من هدف في الحزمة نفسها:

{
    "package": { "name": "image-tools", "version": "0.1.0" },
    "targets": {
        "convert": { "kind": "exe", "main": "src/convert.0" },
        "resize":  { "kind": "exe", "main": "src/resize.0" },
        "lib":     { "kind": "lib", "main": "src/lib.0" }
    }
}

ابنِ هدفًا محدّدًا من سطر الأوامر بتسميته:

zero build convert
zero run resize

مجلد src/

كل ملفات المصدر تعيش تحت src/. يمشي المترجم هذا المجلد تلقائيًا — لا داعي لذكر كل ملف في البيان. حقل main لكل هدف يُشير إلى ملف نقطة الدخول الخاص به؛ يتتبّع المترجم الاستيرادات من هناك ليجد كل شيء آخر يحتاجه.

حزمة فيها بعض الوحدات المساعدة قد تبدو هكذا:

image-tools/
├── zero.json
└── src/
    ├── convert.0
    ├── resize.0
    ├── lib.0
    └── internal/
        ├── decoder.0
        └── encoder.0

المجلد الفرعي internal/ مجرّد اتّفاق — لا شيء في البيان يُسمّي هذه الملفات. الاستيرادات داخل convert.0 تصل إلى internal/decoder.0 مباشرة.

البناء والتشغيل

سير عمل شائع عندما تكون داخل حزمة:

zero check        # فحص أنواع الشجرة كاملةً
zero run          # بناء الهدف الافتراضي وتشغيله
zero run convert  # بناء هدف مسمّى وتشغيله
zero build        # بناء الهدف الافتراضي
zero build --all  # بناء كل الأهداف (حين يكون مدعومًا)
zero test         # تشغيل كل أهداف الاختبار

تقرأ واجهة سطر الأوامر zero.json، وتكتشف ما يجب فعله، وتنطلق. نادرًا ما تحتاج لكتابة مسارات بالكامل عندما تعمل داخل حزمة.

ملفات مصدر متعدّدة: مثال سريع

لنفترض أن src/main.0 يستدعي مساعدًا من src/math.0. الملف المساعد:

pub fun double(value: i32) -> i32 {
    return value * 2
}

ملف نقطة الدخول:

pub fun main(world: World) -> Void raises {
    let result = double(21)
    if result == 42 {
        check world.out.write("forty two\n")
    }
}

شغّله بـ zero run. يحلّ المترجم الإشارة إلى double بمسح شجرة المصدر دون أي تصريح استيراد صريح في هذه الحالة البسيطة. كلّما كبرت الحزم، يتولّى نظام استيراد صريح إدارة الرؤية بين الوحدات — راجع توثيق Zero الحالي لصياغة الاستيراد، وهي من المساحات الأكثر احتمالًا للتغيّر قبل 1.0.

ما لا تضعه في git

ملف .gitignore لحزمة Zero عادةً يريد:

# منتجات البناء والمؤقتات
/build/
/target/

# ملفات المحرّر
.DS_Store
*.swp

اسم مجلد مخرجات البناء الدقيق قد يختلف — راجع توثيق سلسلة الأدوات الحالي — لكن القاعدة: المصدر يدخل، ومنتجات البناء تبقى خارجًا.

مشاركة الحزم

‏Zero قبل الإصدار 1.0، ومستودع الحزم ليس جزءًا من الواجهة المستقرّة بعد. في الوقت الحالي، الطرق العملية لمشاركة حزمة هي:

• Git: استنسخ المستودع وشغّل zero check عليه.
• نسخة محلية: ضع نسخة من المصدر داخل مشروع آخر.

حين يصل المستودع، ستنتقل مراجع الحزم على الأرجح إلى حقل dependencies في zero.json. تعامل مع ذلك كميزة مستقبلية، لا شيئًا تكتب له برنامجًا اليوم.

التالي: أساسيات اللغة

أصبح لديك الآن كل ما تحتاجه لتنظيم مشروع Zero حقيقي. الفصل التالي يُركّز على اللغة نفسها، بدءًا من ربط let — كيف تحصل قيم Zero على أسماء.