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/
etgenerators/
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écuternpm 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/
devientdist/blockly_compressed.js
. - Le contenu de
build/src/blocks/
devientdist/blocs_compressed.js
. - Le contenu de
build/src/generators/javascript/
(plusbuild/src/generators/javascript.js
) devientdist/javascript_compressed.js
. - Il en va de même pour
dart
,lua
,php
etpython
.
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 dansdist/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.