Build-Scripts

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 ebenso große Anzahl von .js-Dateien erstellt, die sich für lokale Tests eignen. Das Laden einer so großen Anzahl von Dateien über das Internet ist für Endnutzer jedoch langsam. Damit Blockly schneller geladen wird, wird der Closure Compiler verwendet, um die Dateien zu komprimieren (zu minimieren) und in etwa sechs Dateien („Bundles“ oder „Chunks“) mit einer Gesamtgröße von weniger als der Hälfte der unkomprimierten Dateien zusammenzufassen.

Dabei wird Code, der die neuesten ECMAScript-Funktionen verwendet, die möglicherweise nicht mit allen Browsern kompatibel sind, in ES6 transpiliert, das in der Regel mit den meisten gängigen Browsern kompatibel ist. Daher ist es wichtig, dass Sie Ihren Endnutzern nur den minimierten Code bereitstellen.

Das RaspberryPiFoundation/blockly-Repository enthält nur den Quellcode. Früher waren auch die Build-Produkte enthalten, aber seit 2019 werden die minimierten Bundles als das NPM-Paket blockly veröffentlicht und seit 2022 auch als .tgz-Datei an jede GitHub-Version angehängt. Daher ist es nicht erforderlich, Blockly zu erstellen, es sei denn, Sie arbeiten an Blockly selbst, insbesondere an Dateien in den Verzeichnissen core, blocks, generators oder msg.

Der Prozess zum Erstellen, Testen und Veröffentlichen von Blockly wird mithilfe von npm-Scripts automatisiert, um Gulp-Aufgaben auszuführen. Auf dieser Seite werden die wichtigsten Skripts und ihre Funktionen dokumentiert.

Komprimierter und unkomprimierter Modus

Das direkte Laden von Blockly aus den einzelnen .js-Dateien, die vom TypeScript-Compiler generiert werden, wird als „unkomprimierter Modus“ bezeichnet. Da mehrere langsame Build-Schritte vermieden werden, wird ein schneller Zyklus aus Bearbeiten, Kompilieren und Ausführen ermöglicht. Außerdem wird das Debugging erleichtert, da der ausgeführte JavaScript-Code fast so lesbar ist wie die ursprünglichen TypeScript-Quellen. Sourcemaps sind also nicht erforderlich.

Das Laden von Blockly aus den minimierten Bundles wird als „komprimierter Modus“ bezeichnet. Dies ist die beste Möglichkeit, Änderungen an Blockly zu testen, wenn es als Abhängigkeit eines anderen Pakets verwendet wird, da damit (eine unveröffentlichte Version des) blockly-npm-Pakets getestet wird.

N.B.: An einigen Stellen im Blockly-Repository werden die Begriffe „uncompiled mode“ (nicht kompilierter Modus) und „compiled mode“ (kompilierter Modus) als Synonyme für „uncompressed mode“ (nicht komprimierter Modus) bzw. „compressed mode“ (komprimierter Modus) verwendet. Diese Verwendung war in der Vergangenheit sinnvoll, da der Closure Compiler zum Komprimieren (Minimieren) des Codes verwendet wurde. Jetzt ist der TypeScript-Compiler jedoch immer erforderlich, auch im unkomprimierten Modus. Daher ist diese alternative Terminologie potenziell verwirrend und wird nicht empfohlen.

Schnellstart

  • Wenn Sie lokale Änderungen vorgenommen haben und sichergehen möchten, dass sie den Build oder Tests nicht beeinträchtigt haben, führen Sie Folgendes aus:

    npm test

    Blockly zu erstellen und die zugehörige Testsuite auszuführen.

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

    npm start

    Dadurch wird Blockly kompiliert und ein Webbrowser geöffnet, der auf die Blockly-Sandbox verweist, in der Blockly im unkomprimierten Modus ausgeführt wird.

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

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

    npm run package

    Blockly-Paket erstellen.

    cd dist && npm link

    um npm mitzuteilen, wo die kompilierten Dateien zu finden sind. Wechseln Sie dann mit cd in das Verzeichnis Ihres Projekts, bevor Sie

    npm link blockly

    damit in Ihrem Paket die neu kompilierte Version von Blockly anstelle des veröffentlichten Pakets blockly verwendet wird.

Detaillierte Skriptreferenz

In diesem Abschnitt werden die Grundsätze scripts in der Datei package.json von Blockly mit einer Erklärung ihrer Funktion aufgeführt.

Mit diesen Skripts werden Dateien an zwei Stellen generiert:

  • 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 verfolgt.

clean

Mit npm run clean werden alle vorherigen Builds bereinigt, indem die Verzeichnisse build/ und dist/ gelöscht werden. Nützlich, um schwer nachvollziehbare Build-Fehler zu beheben, insbesondere solche, die durch das Umbenennen einer Quelldatei verursacht werden.

messages

Mit npm run messages werden die Nachrichtendateien in msg/json/ mit allen Änderungen aktualisiert, die an msg/messages.js vorgenommen wurden. Der Befehl sollte nach jeder Änderung dieser Datei ausgeführt werden.

langfiles

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

tsc

npm run tsc führt den TypeScript-Compiler für den Inhalt 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 Chunks (minimierte Bundles) aufgeteilt werden sollen. Anschließend wird closure-compiler ausgeführt, um die Chunks 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.
  • Das gilt auch für dart, lua, php und python.

Für die generierten Chunks wird ein Wrapper verwendet, um die Kompatibilität mit der Universal Module Definition zu gewährleisten. Daher ist keine zusätzliche Verarbeitung erforderlich, bevor sie in das Paket aufgenommen werden.

build

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

package

Mit npm run package werden die Aufgaben clean und build ausgeführt. Anschließend passiert Folgendes:

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

publish

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

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 aus (einschließlich ESLint). Dieser Test sollte für jeden Code ausgeführt werden, der als Pull-Anfrage für das Blockly-Repository eingereicht wird, und er sollte bestanden werden.