Скрипты сборки Blockly

Blockly состоит из более чем сотни файлов TypeScript. Прежде чем их можно будет использовать, они должны быть скомпилированы компилятором TypeScript tsc в JavaScript. При этом создается такое же большое количество файлов .js , которые подходят для локального тестирования, но загрузка такого большого количества файлов через Интернет является медленным процессом для конечных пользователей. Чтобы ускорить загрузку Blockly, компилятор Closure используется для сжатия (минимификации) и объединения их в полдюжины файлов («связки» или «куски») с общим размером менее половины несжатых файлов.

При этом код, использующий новейшие функции ECMAScript, которые могут быть совместимы не со всеми браузерами, переводится в ES6, который обычно совместим с большинством широко используемых браузеров. Таким образом, важно, чтобы вы предоставляли конечным пользователям только минимизированный код.

Репозиторий google/blockly содержит только исходный код. Раньше он также содержал продукты сборки, но с 2019 года минифицированные пакеты публикуются как blockly пакет NPM , а с 2022 года также прикрепляются в виде файла .tgz к каждому выпуску GitHub , поэтому нет необходимости собирать Blockly, если только вы не взламываете Сам Blockly — в частности, файлы в каталогах core , blocks , generators или msg .

Процесс сборки, тестирования и публикации Blockly автоматизирован с помощью скриптов npm для запуска задач Gulp . На этой странице описаны основные сценарии и то, что каждый из них делает.

Сжатый и несжатый режим

Загрузка Blockly непосредственно из отдельных файлов .js , созданных компилятором TypeScript, называется «несжатым режимом». Поскольку это позволяет избежать нескольких медленных этапов сборки, это облегчает цикл редактирования-компиляции-выполнения; это также облегчает отладку, поскольку исполняемый код JavaScript почти так же читабелен, как и исходные источники TypeScript, что устраняет необходимость зависеть от исходных карт.

Загрузка Blockly из мини-пакетов называется «сжатым режимом». Это лучший способ протестировать изменения в Blockly при использовании его в качестве зависимости от другого пакета, поскольку он тестирует (неопубликованную версию) blockly пакет npm.

Примечание. В блочном репозитории есть места, где термины «нескомпилированный режим» и «скомпилированный режим» используются как синонимы «несжатый режим» и «сжатый режим» соответственно. Такое использование имело смысл в прошлом, поскольку компилятор Closure использовался для сжатия (минимификации) кода, но теперь компилятор 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/ являются промежуточными файлами, используемыми для локального тестирования или принимаемыми более поздними частями конвейера сборки.
Файлы в подкаталоге dist/ образуют содержимое опубликованного пакета npm.

Ни один из каталогов не отслеживается в блочном репозитории 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 .

Сгенерированные chuks используют оболочку для обеспечения совместимости с определением универсального модуля , поэтому не требуется никакой дополнительной обработки перед их включением в пакет.

`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). Его следует запустить и передать любому коду, отправленному в виде запроса на включение в блочный репозиторий.