اسکریپت های ساخت Blockly

Blockly از بیش از صد فایل TypeScript تشکیل شده است. اینها قبل از استفاده باید توسط کامپایلر TypeScript، tsc ، در جاوا اسکریپت کامپایل شوند. این تعداد به همان اندازه فایل‌های .js را ایجاد می‌کند که برای آزمایش محلی مناسب هستند، اما بارگیری چنین تعداد زیادی فایل از طریق اینترنت یک تجربه کند برای کاربران نهایی است. برای سریع‌تر کردن بارگذاری Blockly، کامپایلر بستن برای فشرده‌سازی (کوچک کردن) و ترکیب آن‌ها در نیم دوجین فایل ("بسته" یا "تکه") با حجم کلی کمتر از نصف فایل‌های غیرفشرده استفاده می‌شود.

در این فرآیند، کدهایی با استفاده از آخرین ویژگی‌های ECMAScript - مواردی که ممکن است با همه مرورگرها سازگار نباشند - به ES6 منتقل می‌شوند، که معمولاً با اکثر مرورگرهای پرکاربرد سازگار است. بنابراین، مهم است که فقط کد کوچک شده را به کاربران نهایی خود ارائه دهید.

مخزن google/blockly فقط حاوی کد منبع است. قبلاً حاوی محصولات ساخت بود، اما از سال 2019 بسته‌های کوچک‌سازی شده به‌عنوان بسته NPM blockly منتشر شد و از سال 2022 نیز به‌عنوان یک فایل .tgz به هر نسخه GitHub پیوست شده است، بنابراین نیازی به ساخت Blockly نیست مگر اینکه در حال هک کردن باشید. خود را مسدود کنید - به ویژه در پرونده‌های موجود در core ، blocks ، generators یا فهرست‌های msg .

فرآیند ساخت، آزمایش و انتشار Blockly با استفاده از اسکریپت‌های npm برای اجرای وظایف Gulp خودکار می‌شود. این صفحه اسکریپت های اصلی و کارهایی که هر کدام انجام می دهند را مستند می کند.

حالت فشرده و غیر فشرده

بارگیری Blockly مستقیماً از فایل های .js منفرد تولید شده توسط کامپایلر TypeScript به عنوان "حالت غیر فشرده" نامیده می شود. از آنجایی که از چندین مرحله ساخت آهسته جلوگیری می کند، چرخه ویرایش-کامپایل-اجرای سریع را تسهیل می کند. همچنین اشکال زدایی را تسهیل می کند زیرا کد جاوا اسکریپت در حال اجرا تقریباً به اندازه منابع اصلی TypeScript قابل خواندن است و نیاز به وابستگی به نقشه های منبع را برطرف می کند.

Loading Blockly از بسته های کوچک شده به عنوان "حالت فشرده" نامیده می شود. این بهترین راه برای آزمایش تغییرات Blockly هنگام استفاده از آن به عنوان وابستگی بسته دیگری است، زیرا بسته npm blockly (نسخه منتشر نشده) را آزمایش می کند.

نکته: برخی مکان‌ها در مخزن بلوکی وجود دارد که در آن‌ها از اصطلاحات «حالت کامپایل‌نشده» و «حالت کامپایل‌شده» به‌ترتیب به‌عنوان مترادف «حالت غیر فشرده» و «حالت فشرده» استفاده می‌شود. این استفاده در گذشته منطقی بود زیرا از Closure Compiler برای فشرده‌سازی (کوچک کردن) کد استفاده می‌شد، اما اکنون کامپایلر TypeScript همیشه مورد نیاز است، حتی در حالت غیر فشرده، بنابراین این اصطلاح جایگزین به طور بالقوه گیج‌کننده و دلسرد کننده است.

شروع سریع

  • اگر تغییرات محلی ایجاد کرده‌اید و می‌خواهید مطمئن شوید که بیلد یا هیچ آزمایشی شکسته نشده‌اند، اجرا کنید

    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/ subdirectory فایل‌های واسطه‌ای هستند که برای آزمایش محلی استفاده می‌شوند یا توسط بخش‌های بعدی خط لوله ساخت، جذب می‌شوند.
  • فایل‌های موجود در دایرکتوری فرعی dist/ محتویات بسته npm منتشر شده را تشکیل می‌دهند.

هیچ یک از دایرکتوری ها در مخزن blockly git ردیابی نمی شوند.

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 استفاده می شود. این به زیرساخت داخلی گوگل بستگی دارد، بنابراین برای توسعه دهندگان خارجی مفید نیست.

lint

npm run lint ESLint را اجرا می‌کند و تجزیه و تحلیل استاتیک کد منبع Blockly را برای یافتن مشکلات انجام می‌دهد.

test

npm test (یا npm run test ) وظیفه package را اجرا می کند و سپس تست های خودکار مختلف (از جمله اجرای ESLint) را اجرا می کند. این باید بر روی هر کدی که به عنوان یک درخواست کشش در برابر مخزن بلوکی ارسال شده است اجرا شود و ارسال شود.