חבילות Zero: הסבר על zero.json, src/ ויעדים

למה חבילות

קובץ .0 בודד מספיק כשלומדים את השפה או מנסים קטע קוד. ברגע שהפרויקט גדל מעבר לקובץ אחד, צריך חבילה: תיקייה עם מניפסט ומבנה ידוע שערכת הכלים מבינה.

היתרונות של מעבר מקבצים בודדים לחבילה:

• מקום קנוני אחד לשם הפרויקט, לגרסה ולמטא-דאטה שלו.
• כמה נקודות כניסה (קובץ הרצה, ספרייה, בדיקות) בעץ אחד.
• מבנה צפוי: כלים יכולים למצוא את קוד המקור שלכם בלי הגדרות.
• zero check / zero build על כל העץ, ולא קובץ אחר קובץ.

יצירת שלד לחבילה

הדרך המהירה ביותר להתחיל היא zero new:

zero new cli hello

הפקודה יוצרת תיקייה hello/ במבנה הזה:

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

cli הוא שם התבנית: היא מפיקה תוכנית שורת פקודה ברת הרצה. תבניות אחרות (ספרייה, תוכנית מערכת) בנויות באותה צורה עם ברירות מחדל שונות.

היכנסו לתיקייה החדשה עם cd, הריצו אותה, ואתם בדרך:

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: מזהה קצר (slug) של החבילה. השתמשו באותיות קטנות ובמקפים.
• 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" }
    }
}

בונים יעד מסוים מה-CLI על ידי ציון השם שלו:

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         # הרצה של כל יעדי הבדיקה

ה-CLI קורא את 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.
• עותק מוטמע: מעתיקים את קוד המקור לתוך פרויקט אחר.

כשיגיע מאגר חבילות, סביר שההפניות לחבילות יעברו לשדה תלויות ב-zero.json. התייחסו לזה כפיצ'ר עתידי, לא כמשהו לכתוב מולו סקריפטים היום.

הבא בתור: יסודות השפה

עכשיו יש לכם כל מה שצריך כדי לארגן פרויקט Zero אמיתי. הפרק הבא מתמקד בשפה עצמה, ומתחיל בקישורי let: איך ערכים ב-Zero מקבלים שמות.