פיתוח סקריפטים

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

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

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

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

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

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

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

N.B.: יש כמה מקומות במאגר Blockly שבהם המונחים 'מצב לא מהודק' ו'מצב מהודק' משמשים כמילים נרדפות ל'מצב לא דחוס' ו'מצב דחוס' בהתאמה. השימוש הזה היה הגיוני בעבר, כי Closure Compiler שימש לדחיסת (מינימיזציה) הקוד, אבל עכשיו תמיד צריך את TypeScript compiler, גם במצב לא דחוס, ולכן השימוש במינוח החלופי הזה עלול לבלבל ולא מומלץ.

התחלה מהירה

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

    npm test

    כדי ליצור את Blockly ולהריץ את חבילת הבדיקות שלו.

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

    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 שפורסמה.

Detailed Script Reference

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

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

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

אף אחת מהספריות לא מתועדת במאגר ה-Git של Blockly.

clean

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

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.

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

build

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

package

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

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

publish

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

lint

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

test

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