Scripts de compilation

Blockly est composé de plus d'une centaine de fichiers TypeScript. Ils doivent être compilés par le compilateur TypeScript, tsc, en JavaScript avant de pouvoir être utilisés. Cela crée un nombre tout aussi important de fichiers .js qui conviennent aux tests locaux, mais le chargement d'un si grand nombre de fichiers sur Internet est une expérience lente pour les utilisateurs finaux. Pour que Blockly se charge plus rapidement, le Closure Compiler est utilisé pour les compresser (les réduire) et les combiner en une demi-douzaine de fichiers ("bundles" ou "chunks") dont la taille totale est 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é en ES6, qui est généralement compatible avec la plupart des navigateurs les plus utilisés. Il est donc important de ne diffuser que le code réduit à vos utilisateurs finaux.

Le dépôt google/blockly ne contient que le code source. Auparavant, il contenait également les produits de compilation, mais depuis 2019, les bundles minimisés sont publiés en tant que package NPM blockly et, depuis 2022, ils sont également joints en tant que fichier .tgz à chaque version GitHub. Il n'est donc pas nécessaire de compiler Blockly, sauf si vous modifiez Blockly lui-même, en particulier 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 décrit les scripts principaux et leur fonction.

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, il facilite un cycle d'édition-compilation-exécution rapide. Il facilite également le débogage, car le code JavaScript exécuté est presque aussi lisible que les sources TypeScript d'origine, ce qui évite d'avoir à dépendre des sourcemaps.

Le chargement de Blockly à partir des bundles minimisés est appelé "mode compressé". C'est la meilleure façon de tester les modifications apportées à Blockly lorsque vous l'utilisez comme dépendance d'un autre package, car elle teste (une version non publiée de) le package npm blockly.

N.B.: Dans le dépôt Blockly, les termes "mode non compilé" et "mode compilé" sont parfois utilisés comme synonymes de "mode non compressé" et "mode compressé", respectivement. Cette utilisation avait du sens dans le passé, 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 terminologie alternative est donc potentiellement déroutante et déconseillée.

Démarrage rapide

  • Si vous avez apporté des modifications locales et que vous souhaitez vous assurer qu'elles n'ont pas interrompu la compilation ni les tests, exécutez

    npm test

    pour compiler Blockly et exécuter sa suite de tests.

  • Si vous souhaitez tester les modifications locales dans le navigateur, exécutez

    npm start

    Cette commande compile Blockly et ouvre un navigateur Web pointant vers le bac à sable Blockly qui exécute Blockly en mode non compressé.

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

  • Pour créer 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 dans le répertoire de votre projet avant d'exécuter

    npm link blockly

    pour que votre package utilise la version de Blockly qui vient d'être compilée au lieu du package blockly publié.

Documentation de référence détaillée des scripts

Cette section liste les principaux scripts du fichier package.json de Blockly et explique leur fonctionnement.

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 locaux 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 des deux répertoires n'est suivi dans le dépôt Git Blockly.

clean

npm run clean nettoie les versions précédentes 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. Il doit être exécuté chaque fois que ce fichier est modifié.

langfiles

npm run langfiles génère les fichiers de langue 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 blocs (bundles minimisés), puis exécute closure-compiler pour créer les blocs 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 chunks générés utilisent un wrapper pour assurer la compatibilité avec la définition de module universel. Aucun traitement supplémentaire n'est donc nécessaire avant de les inclure dans le package.

build

npm run build exécute les tâches minify et langfiles. Cela devrait suffire pour charger l'atelier Blockly en mode compressé ou non compressé.

package

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

  • Applique un wrapper UMD aux fichiers de build/msg/ et place les versions encapsulées dans dist/msg/.
  • Ajoute divers fichiers d'assistance 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. Elle dépend de l'infrastructure interne de Google et n'est donc pas utile aux développeurs externes.

lint

npm run lint exécute ESLint, en effectuant une analyse statique du code source Blockly pour trouver les problèmes.

test

npm test (ou npm run test) exécute la tâche package, puis différents tests automatisés (y compris ESLint). Il doit être exécuté (et réussi) sur tout code envoyé en tant que demande d'extraction au dépôt Blockly.