Scripts de compilation de Blockly

Blockly se compose de plus d'une centaine de fichiers TypeScript. Ceux-ci doivent être compilés par le compilateur TypeScript, tsc, en JavaScript avant de pouvoir être utilisés. Cela crée un nombre tout aussi élevé de fichiers .js adaptés aux tests en local, mais le chargement d'un si grand nombre de fichiers sur Internet nuit à l'expérience des utilisateurs finaux. Pour accélérer le chargement de Blockly, le compilateur Closure Compiler est utilisé pour compresser (minifier) et les combiner en une demi-douzaine de fichiers ("bundles" ou "morceaux") d'une taille totale inférieure à la moitié de celle des fichiers non compressés.

Au cours de ce processus, le code utilisant les dernières fonctionnalités ECMAScript, qui peuvent ne pas être compatibles avec tous les navigateurs, est transpilé dans ES6, qui est généralement compatible avec la plupart des navigateurs courants. Il est donc important que vous ne livrez que le code réduit à vos utilisateurs finaux.

Le dépôt google/blockly ne contient que le code source. Il contenait également les produits de compilation, mais depuis 2019, les bundles réduits sont publiés en tant que package NPM blockly et, depuis 2022, joints également en tant que fichier .tgz à chaque version GitHub. Il n'est donc pas nécessaire de compiler Blockly, sauf si vous piratez Blockly, en particulier sur les fichiers des répertoires core, blocks, generators ou msg.

Le processus de compilation, de test et de publication de Blockly est automatisé à l'aide de scripts npm pour exécuter des tâches Gulp. Cette page documente les principaux scripts et ce que chacun fait.

Mode compressé et non compressé

Le chargement de Blockly directement à partir des fichiers .js individuels générés par le compilateur TypeScript est appelé "mode non compressé". Comme il évite plusieurs étapes de compilation lentes, cela facilite un cycle modification-compilation-exécution rapide. Il facilite également le débogage, car le code JavaScript en cours d'exécution est presque aussi lisible que les sources TypeScript d'origine, ce qui évite de dépendre de sourcesmaps.

Le chargement de Blockly à partir des bundles réduits est appelé "mode compressé". Il s'agit du meilleur moyen de tester les modifications apportées à Blockly lorsque vous l'utilisez comme dépendance d'un autre package, car il teste une version non publiée du package npm blockly.

N.B.: À certains endroits du dépôt de blocs de données, les termes "mode non compilé" et "mode compilé" sont utilisés comme synonymes de "mode non compressé" et "mode compressé" respectivement. Auparavant, cette utilisation avait du sens, car Closure Compiler était utilisé pour compresser (minifier) le code. Toutefois, le compilateur TypeScript est désormais toujours nécessaire, même en mode non compressé. Cette autre terminologie peut donc être déroutante et déconseillée.

Quick Start

  • Si vous avez apporté des modifications locales et que vous souhaitez vous assurer qu'elles n'ont pas endommagé le build ni aucun test, exécutez la commande suivante :

    npm test

    pour créer Blockly et exécuter sa suite de tests.

  • Si vous souhaitez tester les modifications locales dans le navigateur, exécutez la commande suivante :

    npm start

    Cette action compile Blockly et ouvre un navigateur Web pointant vers le terrain de jeu Blockly exécutant Blockly en mode non compressé.

    Tous les fichiers de core/, blocks/ et generators/ qui ont été modifiés sont automatiquement recompilés. Actualisez l'onglet du navigateur pour voir les modifications.

  • Pour compiler votre version modifiée localement de Blockly et la tester, en mode compressé, en tant que dépendance d'un autre package npm, exécutez la commande suivante :

    npm run package

    pour créer le package Blockly, puis

    cd dist && npm link

    pour indiquer à npm où trouver les fichiers compilés, puis cd vers le répertoire de votre projet avant d'exécuter

    npm link blockly

    faire en sorte que votre package utilise la version fraîchement compilée de Blockly à la place du package blockly publié.

Documentation de référence détaillée sur le script

Cette section présente le principe scripts dans le fichier package.json de Blockly et une explication de ce qu'ils font.

Ces scripts génèrent des fichiers à deux endroits:

  • Les fichiers du sous-répertoire build/ sont des fichiers intermédiaires utilisés pour les tests en local ou ingérés par les parties ultérieures du pipeline de compilation.
  • Les fichiers du sous-répertoire dist/ constituent le contenu du package npm publié.

Aucun de ces répertoires n'est suivi dans le dépôt Git avec blocs.

clean

npm run clean nettoie tous les builds précédents en supprimant les répertoires build/ et dist/. Utile pour corriger les échecs de compilation obscurs, en particulier ceux causés par le changement de nom d'un fichier source.

messages

npm run messages met à jour les fichiers de messages dans msg/json/ avec toutes les modifications apportées à msg/messages.js et doit être exécuté après chaque modification de ce fichier.

langfiles

npm run langfiles génère les fichiers de langage compilés dans build/msg/ à partir des fichiers de messages dans msg/json.

tsc

npm run tsc exécute le compilateur TypeScript sur le contenu des répertoires core/, blocks/ et generators/, et génère des fichiers .js individuels dans build/src/.

minify

npm run minify exécute closure-make-deps et closure-calculate-chunks pour déterminer comment diviser les fichiers .js compilés en fragments (groupes minimes), puis exécuter closure-compiler pour créer les fragments comme suit:

  • Le contenu de build/src/core/ devient dist/blockly_compressed.js.
  • Le contenu de build/src/blocks/ devient dist/blocs_compressed.js.
  • Le contenu de build/src/generators/javascript/ (plus build/src/generators/javascript.js) devient dist/javascript_compressed.js.
  • Il en va de même pour dart, lua, php et python.

Les chuks générés utilisent un wrapper pour garantir la compatibilité avec la définition de module universelle. Aucun traitement supplémentaire n'est donc nécessaire avant d'être inclus dans le package.

build

npm run build exécute les tâches minify et langfiles. Cela devrait effectuer tout ce qui est nécessaire pour charger Blockly Playground, en mode compressé ou non compressé.

package

npm run package exécute les tâches clean et build, puis:

  • Applique un wrapper UMD pour les fichiers dans build/msg/, en plaçant les versions encapsulées dans dist/msg/.
  • Ajout de divers fichiers de prise en charge supplémentaires à dist/, avec des wrappers UMD le cas échéant.

publish

npm run publish est utilisé par l'équipe Blockly pour publier le package npm blockly. Il dépend de l'infrastructure interne de Google. Il n'est donc pas utile aux développeurs externes.

lint

npm run lint exécute ESLint et effectue une analyse statique du code source Blockly pour détecter les problèmes.

test

npm test (ou npm run test) exécute la tâche package, puis divers tests automatisés (y compris l'exécution d'ESLint). Celle-ci doit être exécutée et transmise au code envoyé en tant que requête d'extraction vers le dépôt de blocs.