Build-Skripts von Blockly

Blockly besteht aus über hundert TypeScript-Dateien. Diese müssen vom TypeScript-Compiler tsc in JavaScript kompiliert werden, bevor sie verwendet werden können. Dadurch wird eine ähnlich große Anzahl von .js-Dateien erstellt, die für lokale Tests geeignet sind. Das Laden einer so großen Anzahl von Dateien über das Internet ist jedoch für Endnutzer sehr mühsam. Damit Blockly schneller geladen wird, wird der Closure Compiler verwendet, um sie zu komprimieren (minimieren) und zu einem halben Dutzend Dateien ("Bundles" oder "Chunks") mit einer Gesamtgröße von weniger als der Hälfte der nicht komprimierten Dateien zusammenzufassen.

Dabei wird Code mit den neuesten ECMAScript-Funktionen – die möglicherweise nicht mit allen Browsern kompatibel sind – in ES6 umgewandelt, das im Allgemeinen mit den gängigsten Browsern kompatibel ist. Daher ist es wichtig, dass Sie Ihren Endnutzern nur den minimierten Code bereitstellen.

Das google/blockly-Repository enthält nur den Quellcode. Sie enthielt zuvor auch die Build-Produkte. Seit 2019 wurden die reduzierten Bundles jedoch als blockly-NPM-Paket veröffentlicht und seit 2022 auch als .tgz-Datei an jeden GitHub-Release angehängt. Es ist also nicht erforderlich, Blockly zu erstellen, es sei denn, Sie hacken auf Blockly selbst, insbesondere bei Dateien in den Verzeichnissen core, blocks, generators oder msg.

Das Erstellen, Testen und Veröffentlichen von Blockly wird mithilfe von npm-Skripts automatisiert, um Gulp-Aufgaben auszuführen. Auf dieser Seite werden die Hauptskripts und ihre Funktion dokumentiert.

Komprimierter und unkomprimierter Modus

Das Laden von Blockly direkt aus den einzelnen .js-Dateien, die vom TypeScript-Compiler generiert wurden, wird als „unkomprimierter Modus“ bezeichnet. Da mehrere langsame Build-Schritte vermieden werden, wird ein schneller Zyklus des Bearbeitens, Kompilierens und Ausführens erleichtert. Außerdem wird die Fehlerbehebung erleichtert, da der ausgeführte JavaScript-Code fast so lesbar ist wie die ursprünglichen TypeScript-Quellen, wodurch die Notwendigkeit von Sourcemaps überflüssig wird.

Das Laden von Blockly aus den reduzierten Bundles wird als „komprimierter Modus“ bezeichnet. Dies ist die beste Methode, um Änderungen an Blockly zu testen, wenn es als Abhängigkeit eines anderen Pakets verwendet wird, weil das npm-Paket blockly (eine unveröffentlichte Version) getestet wird.

N.B.: Im blockly Repository gibt es einige Stellen, an denen die Begriffe „nicht kompilierter Modus“ und „kompilierter Modus“ als Synonyme für „unkomprimierter Modus“ bzw. „komprimierter Modus“ verwendet werden. In der Vergangenheit war diese Verwendung sinnvoll, da Closure Compiler zum Komprimieren (Minify) des Codes verwendet wurde. Jetzt wird jedoch der TypeScript-Compiler immer benötigt, auch im unkomprimierten Modus, sodass diese alternative Terminologie möglicherweise verwirrend ist und nicht empfohlen wird.

Schnellstart

  • Wenn Sie lokale Änderungen vorgenommen haben und sicherstellen möchten, dass der Build oder Tests dadurch nicht beeinträchtigt werden, führen Sie folgenden Befehl aus:

    npm test

    um Blockly zu erstellen und seine Testsuite auszuführen.

  • Wenn Sie lokale Änderungen im Browser testen möchten, führen Sie den folgenden Befehl aus:

    npm start

    Dadurch wird Blockly kompiliert und ein Webbrowser geöffnet, der auf den Blockly Playground verweist, der Blockly im unkomprimierten Modus ausführt.

    Alle geänderten Dateien in core/, blocks/ und generators/ werden automatisch neu kompiliert. Laden Sie den Browsertab neu, um die Änderungen zu sehen.

  • Um Ihre lokal geänderte Version von Blockly zu erstellen und als Abhängigkeit eines anderen npm-Pakets im komprimierten Modus zu testen, führen Sie folgenden Befehl aus:

    npm run package

    um das Blockly-Paket zu erstellen,

    cd dist && npm link

    um npm anzuweisen, wo die kompilierten Dateien zu finden sind, und dann vor der Ausführung mit cd in das Verzeichnis Ihres Projekts wechseln.

    npm link blockly

    , damit Ihr Paket die neu kompilierte Version von Blockly anstelle des veröffentlichten blockly-Pakets verwendet.

Detaillierte Skriptreferenz

In diesem Abschnitt wird das Prinzip scripts in der package.json-Datei von Blockly aufgeführt und seine Funktion wird erläutert.

Diese Skripts generieren Dateien an zwei Orten:

  • Dateien im Unterverzeichnis build/ sind Zwischendateien, die für lokale Tests verwendet oder von späteren Teilen der Build-Pipeline aufgenommen werden.
  • Dateien im Unterverzeichnis dist/ bilden den Inhalt des veröffentlichten npm-Pakets.

Keines der beiden Verzeichnisse wird im blockly-Git-Repository erfasst.

clean

npm run clean bereinigt alle vorherigen Builds, indem die Verzeichnisse build/ und dist/ gelöscht werden. Nützlich zum Beheben von schwerwiegenden Build-Fehlern, insbesondere solchen, die durch das Umbenennen einer Quelldatei verursacht werden.

messages

npm run messages aktualisiert die Nachrichtendateien in msg/json/ mit allen an msg/messages.js vorgenommenen Änderungen und sollte jedes Mal ausgeführt werden, wenn diese Datei geändert wird.

langfiles

npm run langfiles generiert die kompilierten Sprachdateien in build/msg/ aus den Nachrichtendateien in msg/json.

tsc

npm run tsc führt den TypeScript-Compiler für die Inhalte der Verzeichnisse core/, blocks/ und generators/ aus und gibt einzelne .js-Dateien in build/src/ aus.

minify

npm run minify führt closure-make-deps und closure-calculate-chunks aus, um zu bestimmen, wie die kompilierten .js-Dateien in Blöcke (minimierte Bundles) aufgeteilt werden sollen. Anschließend wird closure-compiler ausgeführt, um die Blöcke wie folgt zu erstellen:

  • Der Inhalt von build/src/core/ wird zu dist/blockly_compressed.js.
  • Der Inhalt von build/src/blocks/ wird zu dist/blocs_compressed.js.
  • Der Inhalt von build/src/generators/javascript/ (plus build/src/generators/javascript.js) wird zu dist/javascript_compressed.js.
  • Dasselbe gilt für dart, lua, php und python.

Die generierten Chuks verwenden einen Wrapper, um die Kompatibilität mit der universellen Moduldefinition zu gewährleisten, sodass keine zusätzliche Verarbeitung erforderlich ist, bevor sie in das Paket aufgenommen werden.

build

npm run build führt die Aufgaben minify und langfiles aus. Damit sollte alles erledigt werden, was zum Laden des Blockly-Playgrounds im komprimierten oder unkomprimierten Modus erforderlich ist.

package

npm run package führt die Aufgaben clean und build aus und führt dann folgende Schritte aus:

  • Wendet einen UMD-Wrapper auf die Dateien in build/msg/ an und platziert die umschlossenen Versionen in dist/msg/.
  • Fügt dist/ verschiedene zusätzliche Supportdateien mit UMD-Wrappern hinzu, sofern zutreffend.

publish

npm run publish wird vom Blockly-Team verwendet, um das npm-Paket blockly zu veröffentlichen. Es hängt von der Google-internen Infrastruktur ab und ist daher für externe Entwickler nicht hilfreich.

lint

npm run lint führt ESLint aus und führt eine statische Analyse des Blockly-Quellcodes durch, um Probleme zu finden.

test

npm test (oder npm run test) führt die Aufgabe package und dann verschiedene automatisierte Tests (einschließlich ESLint) aus. Dies sollte für jeden Code ausgeführt und übergeben werden, der als Pull-Anfrage an das blockly Repository gesendet wird.