Скрипты сборки 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 .

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

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