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

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

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

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

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

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

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

Загрузка 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/ являются промежуточными файлами, используемыми для локального тестирования или принимаемыми более поздними частями конвейера сборки.
  • Файлы в подкаталоге 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 .

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

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). Эта команда должна запускаться (и проходить) для любого кода, отправленного в виде запроса на извлечение (pull request) в блочном репозитории.