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

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

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

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

התחלה מהירה

אם ביצעתם שינויים מקומיים ואתם רוצים לוודא שהם לא פגעו ב-build או בבדיקות, תוכלו להריץ את הפקודה
```
npm test
```
כדי ליצור את Blockly ולהריץ את חבילת הבדיקות שלו.
כדי לבדוק שינויים מקומיים בדפדפן, מפעילים
```
npm start
```
הפעולה הזו יוצרת את Blockly ופותח דפדפן אינטרנט שמצביע אל Blockly מגרש משחקים שבו פועל 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 שפורסם חבילה.

לא מתבצע מעקב אחרי אף אחת מהספריות במאגר ה-Git.

`clean`

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

`messages`

קובצי ההודעות בתיקייה msg/json/ מתעדכנים על ידי npm run messages עם כל שינוי שהועברו ל-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 כדי להבטיח תאימות ל הגדרת המודול כך שלא נדרש עיבוד נוסף נדרש לפני שהם כלולים בחבילה.

`build`

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

`package`

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

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

`publish`

npm run publish משמש את צוות Blockly לפרסום החבילה blockly ב-npm. תלוי בתשתית הפנימית של Google אז לא שימושי למפתחים חיצוניים.

`lint`

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

`test`

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