ה-CLI של Zero: check, run, build, test, fix ו-explain

מה ה-CLI נותן לכם

הקובץ הבינארי zero הוא כל ערכת כלי הפיתוח. אין מנהל חבילות, כלי עיצוב קוד, linter או מריץ בדיקות נפרדים: כולם פקודות משנה של zero. כך המשטח נשאר קטן וצפוי, וזה בדיוק העניין.

תפריט קצר של הפקודות שתשתמשו בהן הכי הרבה:

כל אחת מהן מקבלת --json כדי להפיק פלט קריא למכונה במקום טקסט מעוצב לבני אדם.

zero check

סוס העבודה. zero check מריץ את הבדיקות הסטטיות של הקומפיילר, ניתוח, בדיקת טיפוסים, הסקת יכולות ואפקטים, זיהוי ייבואים חסרים, ועוצר לפני יצירת הקוד. הוא מהיר, וזה חשוב כי סוכנים ועורכים קוראים לו כל הזמן.

zero check hello.0

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

zero check hello.0 --json

{
    "ok": false,
    "diagnostics": [
        {
            "code": "NAM003",
            "message": "unknown identifier",
            "line": 3,
            "repair": { "id": "declare-missing-symbol" }
        }
    ]
}

המבנה של הדיאגנוסטיקה מתועד במלואו בדיאגנוסטיקות JSON. שימו לב לשדה ה-code היציב: NAM003 תמיד פירושו "unknown identifier", בלי קשר לגרסת הקומפיילר.

אפשר גם להפנות את check לתיקיית חבילה במקום לקובץ בודד:

zero check ./my-package

הוא קורא את zero.json, עובר על עץ קוד המקור ומדווח על כל בעיה בכל היעדים.

zero run

run מקמפל ומריץ בצעד אחד. הכי מתאים כשאתם עובדים בסבבים על תוכנית קטנה ולא אכפת לכם מהפקת קובץ בינארי בדיסק.

zero run hello.0

זה שקול להרצת zero build ואז הפעלת הקובץ הבינארי שנוצר, רק שהתוצר נזרק. ה-stdout של התוכנית מועבר ל-stdout של הטרמינל שלכם: הקריאות ל-world.out.write בתוכנית מגיעות למסך שלכם.

אם התוכנית צריכה ארגומנטים, העבירו אותם אחרי --:

zero run greet.0 -- Alice

סביבת הריצה נותנת לתוכנית גישה לארגומנטים האלה דרך אותה יכולת World שחושפת קלט/פלט.

zero build

כשרוצים תוצר, משתמשים ב-build:

zero build hello.0

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

הקבצים הבינאריים של Zero קטנים. מטרת העיצוב של הפרויקט היא קובצי הרצה של פחות מ-10KB לתוכניות פשוטות, והיא מושגת על ידי ויתור על ערכת הכלים של LLVM ויצירה ישירה של מסלולי קוד קומפקטיים.

zero test

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

zero test

הבדיקות נמצאות לצד קוד המקור תחת src/, ומוצהרות כיעדי בדיקה בקובץ zero.json של החבילה. המריץ מגלה אותן, מריץ כל אחת ומדווח על הצלחה או כישלון. עם --json, הפלט מובנה לכל בדיקה, שם, סטטוס, משך, דיאגנוסטיקות שנלכדו, עבור סוכנים וכלי CI.

חבילות Zero מסביר איך מצהירים על יעדי בדיקה ב-zero.json.

zero fix

fix צורך את המטא-דאטה לתיקון ש-check --json מפיק. יש לו שני מצבים:

zero fix --plan --json   # מציג את התוכנית המובנית, בלי להחיל אותה
zero fix                 # מחיל את התוכנית במקום

תוכנית נראית בערך כך (המבנה להמחשה):

{
    "diagnostic": { "code": "NAM003", "line": 3 },
    "plan": {
        "id": "declare-missing-symbol",
        "edits": [
            { "kind": "insert", "line": 1, "text": "fun answer() -> i32 { return 42 }\n" }
        ]
    }
}

הרעיון הוא שסוכן שולף את התוכנית, מחליט אם לסמוך עליה, ואז מחיל אותה ישירות או מעביר אותה לשלב חשיבה ברמה גבוהה יותר. תוכניות הן נתונים; סוכנים לא צריכים לפרש טקסט חופשי כדי לפעול.

zero explain

explain הוא הצד הטקסטואלי של מערכת הדיאגנוסטיקות:

zero explain NAM003

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

• אדם מדבג ורוצה תשובה ארוכה יותר מההודעה שבשורה.
• סוכן נתקל בקוד דיאגנוסטיקה שלא היה בנתוני האימון שלו ורוצה יותר הקשר.

הקוד עצמו יציב בין גרסאות של הקומפיילר, ולכן הסברים שנשמרו במטמון נשארים תקפים.

zero new

יוצרים שלד לחבילה חדשה:

zero new cli hello

הפקודה יוצרת תיקייה hello/ עם מניפסט zero.json וקובץ התחלתי src/main.0. הארגומנט הראשון (cli כאן) בוחר תבנית, במקרה הזה אפליקציית שורת פקודה ברת הרצה. חבילות Zero מסביר את המבנה בפירוט.

ההרגל של --json

כמעט כל פקודה תומכת ב---json. אם אתם בונים כלים, סביבה להרצת סוכנים או צינור CI סביב Zero, השתמשו כברירת מחדל בצורת ה-JSON. היא:

• יציבה. לסכמה יש גרסאות והצוות מתייחס אליה כחוזה.
• שלמה. מקבלים שדות שלא מופיעים בפלט לבני אדם (טווחים מדויקים, מזהי תוכניות תיקון, נתוני גרף תלויות).
• ניתנת לניתוח. בלי ביטויים רגולריים על טקסט באנגלית כדי לחלץ מספר שורה.

לבני אדם, השאירו את --json בחוץ: הטקסט המעוצב הוא מה שרוצים לראות בטרמינל.

פקודות שימושיות נוספות

כמה פקודות שמשתמשים בהן פחות, אבל כדאי להכיר:

• zero graph --json: מפיק את גרף התלויות של חבילה כנתונים מובנים. שימושי כדי להבין מה תלוי במה, ולסוכנים שרוצים לחשוב על מקומות קריאה.
• zero size --json: מדווח על הגודל בדיסק של התוצרים המקומפלים, מפולח לפי יעד. עוזר כשחשוב לכם גודל הקובץ הבינארי (שזו מטרת עיצוב של Zero).
• zero --version: מדפיס את גרסת ערכת הכלים. תעדו אותה איפשהו אם אתם עובדים בצוות: Zero נמצאת לפני גרסה 1.0 ושינויים שוברים אכן נכנסים.

הבא בתור: חבילות Zero

קובץ .0 בודד מספיק ל-hello world. פרויקטים אמיתיים משתמשים בחבילות עם מניפסט zero.json ותיקיית src/. חבילות Zero מראה איך ליצור שלד לחבילה ומסביר כל שדה.