Script di build di Blockly

Blockly è composto da oltre cento file TypeScript. Prima di poter essere utilizzati, devono essere compilati in JavaScript dal compilatore TypeScript, tsc. In questo modo si crea un numero altrettanto elevato di file .js adatti ai test locali, ma il caricamento di un numero così elevato di file su internet risulta lento per gli utenti finali. Per velocizzare il caricamento di Blockly, viene utilizzato il compilatore Closure per comprimere (minimizzare) e combinare i file in una mezza dozzina di file ("bundle" o "chunk") con dimensioni totali inferiori alla metà di quelle dei file non compressi.

Durante la procedura, il codice che utilizza le funzionalità ECMAScript più recenti, che potrebbero non essere compatibili con tutti i browser, viene transpiled in ES6, che è generalmente compatibile con la maggior parte dei browser più utilizzati. Pertanto, è importante pubblicare per gli utenti finali solo il codice minimizzato.

Il repository google/blockly contiene solo il codice sorgente. In precedenza conteneva anche i prodotti di compilazione, ma dal 2019 i bundle minimizzati sono stati pubblicati come pacchetto NPM blockly e dal 2022 sono stati allegati anche come file .tgz a ogni release di GitHub, quindi non è necessario compilare Blockly, a meno che tu non stia eseguendo hacking su Blockly stesso, in particolare sui file nelle directory core, blocks, generators o msg.

Il processo di creazione, test e pubblicazione di Blockly è automatizzato utilizzando script npm per eseguire task Gulp. Questa pagina descrive gli script principali e la relativa funzionalità.

Modalità compressa e non compressa

Il caricamento di Blockly direttamente dai singoli file .js generati dal compilatore TypeScript è denominato "modalità non compressa". Poiché evita diversi passaggi di compilazione lenti, semplifica un rapido ciclo di modifica, compilazione ed esecuzione. Inoltre, semplifica il debug perché il codice JavaScript in esecuzione è quasi altrettanto leggibile delle origini TypeScript originali, eliminando la necessità di dipendere dai file sourcemap.

Il caricamento di Blockly dai bundle minimizzati è denominato "modalità compressa". Questo è il modo migliore per testare le modifiche a Blockly quando lo utilizzi come dipendenza di un altro pacchetto, perché testa (una versione non pubblicata) del pacchetto blockly npm.

N.B.: In alcuni punti del repository di Blockly, i termini "modalità non compilata" e "modalità compilata" vengono utilizzati come sinonimi rispettivamente di "modalità non compressa" e "modalità compressa". Questo utilizzo aveva senso in passato poiché Closure Compiler veniva utilizzato per comprimere (minimizzare) il codice, ma ora il compilatore TypeScript è sempre necessario, anche in modalità non compressa, quindi questa terminologia alternativa è potenzialmente fuorviante e scoraggiata.

Avvio rapido

Se hai apportato modifiche locali e vuoi assicurarti che non abbiano interrotto la compilazione o i test, esegui
```
npm test
```
per compilare Blockly ed eseguire la suite di test.
Se vuoi testare le modifiche locali nel browser, esegui
```
npm start
```
Verrà compilato Blockly e verrà aperto un browser web che punta al visualizzatore Blockly in cui viene eseguito Blockly in modalità non compressa.

Tutti i file in core/, blocks/ e generators/ che vengono modificati vengono ricompilati automaticamente. Ricarica la scheda del browser per visualizzare le modifiche.
Per compilare la versione di Blockly modificata localmente e testarla, in modalità compressa, come dipendenza di un altro pacchetto npm, esegui
```
npm run package
```
per compilare il pacchetto Blockly, quindi
```
cd dist && npm link
```
per indicare a npm dove trovare i file compilati e poi cd alla directory del progetto prima dell'esecuzione
```
npm link blockly
```
per fare in modo che il pacchetto utilizzi la versione appena compilata di Blockly al posto del pacchetto blockly pubblicato.

Riferimento dettagliato allo script

Questa sezione elenca i principi scripts nel file package.json di Blockly con una spiegazione della loro funzione.

Questi script generano file in due posizioni:

I file nella sottodirectory build/ sono file intermedi utilizzati per i test locali o importati da parti successive della pipeline di compilazione.
I file nella sottodirectory dist/ formano i contenuti del pacchetto npm pubblicato.

Nessuna delle due directory viene tracciata nel repository Git a blocchi.

`clean`

npm run clean ripulisce eventuali build precedenti eliminando le directory build/ e dist/. Utile per correggere errori di build entusiasmanti, in particolare quelli causati dalla ridenominazione di un file di origine.

`messages`

npm run messages aggiorna i file di messaggi in msg/json/ con eventuali modifiche apportate a msg/messages.js e deve essere eseguito ogni volta che il file viene modificato.

`langfiles`

npm run langfiles genera i file di lingua compilati in build/msg/ dai file di messaggi in msg/json.

`tsc`

npm run tsc esegue il compilatore TypeScript sui contenuti delle directory core/, blocks/ e generators/ e genera singoli file .js in build/src/.

`minify`

npm run minify esegue closure-make-deps e closure-calculate-chunks per determinare come suddividere i file .js compilati in chunk (bundle minimizzati), dopodiché esegue closure-compiler per creare i chunk come segue:

I contenuti di build/src/core/ diventano dist/blockly_compressed.js.
I contenuti di build/src/blocks/ diventano dist/blocs_compressed.js.
I contenuti di build/src/generators/javascript/ (più build/src/generators/javascript.js) diventano dist/javascript_compressed.js.
e lo stesso vale per dart, lua, php e python.

I chuk generati utilizzano un wrapper per garantire la compatibilità con la definizione del modulo universale, pertanto non è necessaria alcuna elaborazione aggiuntiva prima che vengano inclusi nel pacchetto.

`build`

npm run build esegue le attività minify e langfiles. Dovresti avere eseguito tutte le operazioni necessarie per caricare il Playground di Blockly in modalità compressa o non compressa.

`package`

npm run package esegue le attività clean e build, quindi:

Applica un wrapper UMD ai file in build/msg/, posizionando le versioni con wrapping in dist/msg/.
Aggiunge vari altri file di supporto a dist/, con wrapper UMD ove applicabile.

`publish`

npm run publish viene utilizzato dal team di Blockly per pubblicare il pacchetto npm blockly. Dipende dall'infrastruttura interna di Google, quindi non è utile per gli sviluppatori esterni.

`lint`

npm run lint esegue ESLint, che esegue un'analisi statica del codice sorgente di Blockly per trovare i problemi.

`test`

npm test (o npm run test) esegue l'attività package, quindi esegue vari test automatici (inclusa l'esecuzione di ESLint). Questo deve essere eseguito e superato su qualsiasi codice inviato come pull request nel repository Blockly.