סקריפטים ל-Buildly'

הצוות ב-Blockly מורכב מיותר ממאה קובצי TypeScript. כדי להשתמש בהם, צריך לבצע את ההדרה של TypeScript, tsc, ל-JavaScript. כך נוצר מספר גדול באותה מידה של קובצי .js שמתאימים לבדיקות מקומיות, אבל טעינת מספר כזה גדול של קבצים באינטרנט יוצרת חוויה איטית למשתמשי קצה. כדי לגרום ל-Blockly להיטען מהר יותר, נעשה שימוש במהדר סגירה כדי לדחוס (להקטין) ולשלב אותם לחצי תריסר קבצים ("bundles" או "גושים") שהגודל הכולל שלהם קטן מחצי מזה של קבצים לא דחוסים.

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

המאגר של google/blockly מכיל רק את קוד המקור. בעבר היא הכילה גם את מוצרי ה-build, אבל מאז 2019, החבילות המוקטנות פורסמו כחבילת ה-NPM blockly והחל מ-2022 הן גם צורפו כקובץ .tgz לכל גרסה של GitHub, כך שאין צורך ליצור אתBlockly אלא אם מנסים לפרוץ ל-Blockly עצמה — במיוחד על קבצים בספריות core, blocks, generators או msg.

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

מצב דחוס או לא דחוס

טעינה ב-Blockly ישירות מקובצי .js הנפרדים שנוצרו על ידי מהדר TypeScript נקראת 'מצב לא דחוס'. היא מונעת מספר שלבי build איטיים, וכך מאפשרת מחזור מהיר של הרצת עריכה והידור וגם ניפוי באגים, מכיוון שקוד JavaScript שמתבצע קריא כמעט כמו מקורות TypeScript המקוריים, כך שאין צורך להסתמך על מפות המקור.

טעינה של חסימת ערוץ מהחבילות המוקטנות נקראת 'מצב דחוס'. זו הדרך הטובה ביותר לבדוק שינויים ב-Blockly כאשר משתמשים בו כתלות של חבילה אחרת, כי היא בודקת (גרסה שלא פורסמה) של חבילת ה-npm blockly.

N.B.: במאגר החסימה של החסימה יש כמה מקומות שבהם המונחים "uncomדוחות" ו "מצב הידור" משמשים כמילים נרדפות ל "מצב לא דחוס" ו "מצב דחוס", בהתאמה. בעבר השתמשו בפורמט הזה כדי לדחוס (להקטין) את הקוד, אבל כיום צריך להשתמש בהידור TypeScript גם במצב לא דחוס, ולכן הטרמינולוגיה החלופית שלו עלולה לבלבל ולא להיות מומלצת.

התחלה מהירה

  • אם ביצעתם שינויים מקומיים ואתם רוצים לוודא שהם לא שברו את גרסת ה-build או את הבדיקות האחרות,

    npm test

    ל-buildly ולהריץ את חבילת הבדיקה שלה.

  • אם ברצונך לבדוק שינויים מקומיים בדפדפן, הפעל

    npm start

    הפעולה הזו מבצעת את היווצרות שלBlockly ופותחת דפדפן אינטרנט שמצביע על blockly Playground שפעיל אתBlockly במצב לא דחוס.

    כל הקבצים ב-core/, ב-blocks/ וב-generators/ שישונו עוברים הידור מחדש באופן אוטומטי. כדאי לטעון מחדש את כרטיסיית הדפדפן כדי לראות את השינויים.

  • כדי ליצור גרסה של blockly שעברה שינוי מקומי ולבדוק אותה, במצב דחוס, כתלות של חבילת npm אחרת, מריצים את

    npm run package

    כדי לבנות חבילת Blockly,

    cd dist && npm link

    כדי להורות ל-npm איפה למצוא את הקבצים ההדורים, ואז cd לספריית הפרויקט לפני שמריצים

    npm link blockly

    כדי שהחבילה תשתמש בגרסה מהחדשה שלBlockly במקום חבילת blockly שפורסמה.

הפניה מפורטת לסקריפט

בקטע הזה מופיע העיקרון scripts בקובץ package.json שלBlockly, והוא כולל הסבר לגבי הפעולות שהוא מבצע.

הסקריפטים האלה יוצרים קבצים בשני מקומות:

  • הקבצים בספריית המשנה build/ הם קובצי ביניים שמשמשים לבדיקה מקומית או להטמעת נתונים בחלקים מאוחרים יותר בצינור עיבוד הנתונים של ה-build.
  • קבצים בספריית המשנה dist/ יוצרים את התוכן של חבילת ה-npm שפורסמה.

במאגר של blockly git מתבצע מעקב אחרי אף אחת מהספריות.

clean

כדי לנקות גרסאות build קודמות, npm run clean מוחק את הספריות build/ ו-dist/. שימושי לתיקון כשלים ב-build של מקודד, במיוחד כשלים שנגרמו כתוצאה משינוי שם של קובץ מקור.

messages

ב-npm run messages מתבצע עדכון של קובצי ההודעות ב-msg/json/ אם בוצעו שינויים ב-msg/messages.js, וצריך להריץ אותם אחרי כל שינוי בקובץ.

langfiles

npm run langfiles יוצר את קובצי השפה המהודרים ב-build/msg/ מקובצי ההודעות ב-msg/json.

tsc

npm run tsc מפעיל את מהדר TypeScript על תוכן הספריות core/, blocks/ ו-generators/, ומפיק פלט של קובצי .js בודדים אל build/src/.

minify

npm run minify מפעיל את closure-make-deps ואת closure-calculate-chunks כדי לקבוע איך לחלק את קובצי .js המפוזרים למקטעים (חבילות מוקטנות), ולאחר מכן להריץ closure-compiler כדי ליצור את המקטעים באופן הבא:

  • התוכן של build/src/core/ הופך ל-dist/blockly_compressed.js.
  • התוכן של build/src/blocks/ הופך ל-dist/blocs_compressed.js.
  • התוכן של build/src/generators/javascript/ (וגם build/src/generators/javascript.js) הופך ל-dist/javascript_compressed.js.
  • וכך גם עבור dart, lua, php ו-python.

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

build

npm run build מפעיל את המשימות minify ו-langfiles. צריך לעשות את כל מה שצריך כדי לטעון את מגרש המשחקים שלBlockly במצב דחוס או במצב לא דחוס.

package

npm run package מריץ את המשימות clean ו-build ואז:

  • הפונקציה מחילה wrapper של UMD על הקבצים ב-build/msg/, ומוסיפה את הגרסאות הארוזות ל-dist/msg/.
  • אפשר להוסיף ל-dist/ קובצי תמיכה שונים, עם רכיבי wrapper של UMD כשזה רלוונטי.

publish

צוות החסימה משתמש ב-npm run publish כדי לפרסם את חבילת blockly npm. היא תלויה בתשתית הפנימית של Google, לכן היא לא שימושית למפתחים חיצוניים.

lint

npm run lint מריץ את ESLint ומבצע ניתוח סטטי של קוד המקור שלBlockly כדי לאתר בעיות.

test

npm test (או npm run test) מפעיל את המשימה package ולאחר מכן מריץ בדיקות אוטומטיות שונות (כולל הרצת ESLint). צריך להריץ את הפקודה הזו – ולהעביר אותה – לכל קוד שנשלח כבקשת משיכה למאגר הבלוקים (blockly).