Scripts de compilation de Blockly

Blockly est constitué de plus d'une centaine de fichiers TypeScript. Ils doivent être compilés en JavaScript par le compilateur TypeScript, tsc, avant de pouvoir être utilisés. Cela crée un nombre tout aussi important de fichiers .js, qui sont adaptés aux tests locaux, mais le chargement d'un tel nombre de fichiers sur Internet est une expérience lente pour les utilisateurs finaux. Pour accélérer le chargement de Blockly, le compilateur Closure est utilisé pour compresser (minimiser) et les combiner dans 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 transcompilé 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 minifié auprès de 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 réduits ont été publiés en tant que package NPM blockly et, depuis 2022, également joints sous forme de fichier .tgz à chaque version GitHub. Il n'est donc pas nécessaire de compiler Blockly, sauf si vous piratez Blockly lui-même, 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 décrit les principaux scripts et leur fonction.

Modes 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é". Étant donné qu'il évite plusieurs étapes de compilation lentes, cela 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 minifiés 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 blockly, les termes "mode non compilé" et "mode compilé" sont utilisés respectivement comme synonymes pour "mode non compressé" et "mode compressé". Cette utilisation avait du sens par le passé, car le compilateur Closure était utilisé pour compresser (minimiser) le code. Toutefois, le compilateur TypeScript est désormais toujours nécessaire, même en mode non compressé. Par conséquent, cette terminologie alternative est potentiellement source de confusion 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 endommagé le build ni les tests, exécutez
```
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
```
npm start
```
Cette commande compile Blockly et ouvre un navigateur Web pointant vers l'espace de jeu Blockly exécutant Blockly en mode non compressé.

Les fichiers core/, blocks/ et generators/ modifiés sont automatiquement recompilés. Actualisez l'onglet du navigateur pour voir les modifications.
Pour créer et tester votre version modifiée localement de Blockly, en mode compressé, en tant que dépendance d'un autre package npm, exécutez
```
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 au répertoire de votre projet avant l'exécution
```
npm link blockly
```
pour que votre package utilise la version fraîchement compilée de Blockly à la place du package blockly publié.

Référence détaillée du script

Cette section liste les scripts principaux dans le fichier package.json de Blockly, avec une explication de leur fonction.

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 de ces répertoires n'est suivi dans le dépôt git blockly.

`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 renommage 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 segments (bundles minifiés), puis exécute closure-compiler pour créer les segments 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.
dart, lua, php et python sont renommés sur le même principe.

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

`build`

npm run build exécute les tâches minify et langfiles. Cela devrait faire tout ce qui est nécessaire pour charger l'espace de jeu 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 dans build/msg/, en plaçant 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 pour les développeurs externes.

`lint`

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

`test`

npm test (ou npm run test) exécute la tâche package, puis exécute divers tests automatisés (y compris l'exécution d'ESLint). Cette opération doit être exécutée et transmise à tout code envoyé en tant que requête pull sur le dépôt Blockly.