Blockly's 建構指令碼

Blockly 由超過一百種 TypeScript 檔案組成。這些程式碼必須先由 TypeScript 編譯器 tsc 編譯為 JavaScript,才能使用。這會建立大量適合本機測試的 .js 檔案,但透過網際網路載入這類大量檔案,對使用者而言是順暢無礙的體驗。為了加快 Blockly 的載入速度,系統會使用 Closure Compiler 來壓縮 (縮小) 並將檔案合併為半個檔案 (「套裝組合」或「區塊」),總大小少於未壓縮檔案的一半。

在過程中,如果程式碼使用最新的 ECMAScript 功能 (可能與所有瀏覽器不相容),則會轉換為 ES6,這大致上與大多數最常用的瀏覽器相容。因此,請務必只為使用者提供壓縮的程式碼。

google/blockly 存放區只包含原始碼。先前也包含建構產品,但自 2019 年起,壓縮的套件已以 blockly NPM 套件的形式發布,自 2022 年起,也以 .tgz 檔案的形式附加至每個 GitHub 版本,因此除非您已遭到入侵 (尤其是 coreblocksgeneratorsmsg 目錄中的檔案),否則不必建構 Blockly。

使用 npm 指令碼執行 Gulp 工作,自動執行建構、測試和發布 Blockly 的程序。本頁面記錄了原理指令碼和分別的作用。

壓縮與未壓縮模式

直接從 TypeScript 編譯器產生的個別 .js 檔案載入 Blockly,此模式稱為「未壓縮模式」。這可避免數個緩慢的建構步驟,因此有助於快速編輯編譯執行週期;也有助於偵錯,因為執行的 JavaScript 程式碼幾乎與原始 TypeScript 來源一樣可讀取,因此您不必依賴來源對應。

從壓縮的套件載入區塊稱為「壓縮模式」。 當您將其做為另一個套件的依附元件使用時,這是測試 Blockly 變更的最佳方式,因為這個套件會測試 blockly npm 套件 (未發布的版本)。

N.B.: 區塊存放區中有些地方會分別使用「未編譯模式」和「編譯模式」這兩個字詞,做為「未壓縮模式」和「壓縮模式」的同義詞。這種使用方法過去十分合理,因為 Closure Compiler 之前曾用來壓縮 (縮小) 程式碼,但現在即使在未壓縮模式下,也需要 TypeScript 編譯器,因此這個替代術語可能會令人混淆並不建議使用。

快速啟動

  • 如果您已進行本機變更,且想確保這些變更並未損毀版本或任何測試,請執行

    npm test
    

    建構 Blockly 並執行測試套件

  • 如要在瀏覽器中測試本機變更,請執行

    npm start
    

    這會編譯 Blockly,並開啟網路瀏覽器,指向在未壓縮模式下執行的 Blockly Playground。

    系統會自動重新編譯 core/blocks/generators/ 中的任何檔案;重新載入瀏覽器分頁即可查看變更。

  • 如要建構在本機修改的 Blockly 版本並進行測試,請以壓縮模式的形式,當做另一個 npm 套件的依附元件,執行

    npm run package
    

    建構 Blockly 套件

    cd dist && npm link
    

    告知 npm 在哪裡可以找到已編譯的檔案,然後在執行前,將 cd 移至專案的目錄

    npm link blockly
    

    讓套件使用剛編譯的 Blockly 版本,取代已發布的 blockly 套件。

詳細的指令碼參考資料

本節列出 Blockly package.json 檔案中的 scripts 原則,以及相關用途的說明。

這些指令碼會在兩個位置產生檔案:

  • build/ 子目錄中的檔案是中介檔案,用於本機測試,或由建構管道的後續部分擷取。
  • dist/ 子目錄中的檔案會形成已發布 npm 套件的內容,

在區塊化 Git 存放區中,系統不會追蹤其中一個目錄。

clean

npm run clean 會刪除 build/dist/ 目錄,藉此清除先前的任何建構作業。有助於修正神經建構失敗問題,特別是重新命名來源檔案所造成的問題。

messages

npm run messages 會根據對 msg/messages.js 所做的任何變更,更新 msg/json/ 中的訊息檔案,且應在每次修改檔案後執行。

langfiles

npm run langfiles 會從 msg/json 中的訊息檔案,在 build/msg/ 中產生編譯語言檔案。

tsc

npm run tsc 會在 core/blocks/generators/ 目錄的內容上執行 TypeScript 編譯器,並將個別 .js 檔案輸出至 build/src/

minify

npm run minify 會執行 closure-make-depsclosure-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
  • 同樣地,dartluaphppython 也同樣適用。

產生的事件會使用包裝函式確保與通用模組定義相容,因此不需額外處理才能納入套件。

build

npm run build 會執行 minifylangfiles 工作。無論在壓縮或未壓縮模式下,系統都會執行載入 Blockly Play 所需的所有操作。

package

npm run package 會執行 cleanbuild 工作,然後:

  • 會在 build/msg/ 中套用 UMD 包裝函式,將包裝過的版本放在 dist/msg/ 中。
  • 將各種額外的支援檔案新增至 dist/,包含適用的 UMD 包裝函式。

publish

Blockly 團隊會使用 npm run publish 發布 blockly npm 套件。它依附於 Google 內部基礎架構,因此不適合外部開發人員。

lint

npm run lint 會執行 ESLint,對 Blockly 原始碼執行靜態分析來找出問題。

test

npm test (或 npm run test) 會執行 package 工作,然後執行各種自動化測試,包括執行 ESLint。這項作業應該在提交至區塊存放區的提取要求時執行 (並傳遞)。