Script di build di Blockly

Blockly è composto da oltre un centinaio di file TypeScript. Questi dati devono essere compilati dal compilatore TypeScript, tsc, in JavaScript prima di poter essere utilizzati. Questo crea un numero altrettanto elevato di file .js, che sono adatti per i test locali, ma caricare un numero così elevato di file su internet è un'esperienza lenta per gli utenti finali. Per velocizzare il caricamento di Blockly, il Compilatore di chiusura viene utilizzato per comprimere (minimizzare) e combinarli in una mezza dozzina di file ("bundle" o "blocchi") con dimensioni totali inferiori alla metà di quelle dei file non compressi.

Nel processo, il codice che utilizza le funzionalità ECMAScript più recenti, quelle che potrebbero non essere compatibili con tutti i browser, viene trasferito a ES6, che è generalmente compatibile con i browser più utilizzati. Pertanto, è importante pubblicare solo il codice minimizzato agli utenti finali.

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

Il processo di creazione, test e pubblicazione di Blockly è automatizzato utilizzando script npm per eseguire le attività Gulp. Questa pagina documenta gli script principali e la funzione di ognuno.

Modalità compressa e non compressa

Il caricamento di Blockly direttamente dai singoli file .js generati dal compilatore TypeScript viene definito "modalità non compressa". Poiché evita diversi passaggi di compilazione lenti, questo facilita un rapido ciclo di modifica-compile-esecuzione e facilita anche il debug poiché il codice JavaScript in esecuzione è leggibile quasi quanto le origini TypeScript originali, eliminando la necessità di dipendere dalle mappe sorgente.

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

N.B.: Nel repository a blocchi, 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, in quanto Closure Compiler veniva utilizzato per comprimere (minimizzare) il codice, ma ora è sempre necessario il compilatore TypeScript, anche in modalità non compressa, pertanto questa terminologia alternativa è potenzialmente confusa e scoraggiata.

Avvio rapido

  • Se hai apportato modifiche locali e vuoi assicurarti che non abbiano interrotto la build o eventuali test, esegui

    npm test

    per creare Blockly ed eseguire la sua suite di test.

  • Se vuoi testare le modifiche locali nel browser, esegui

    npm start

    Questa operazione compila Blockly e apre un browser web che punta al gioco Blockly che esegue Blockly in modalità non compressa.

    Tutti i file modificati in core/, blocks/ e generators/ vengono ricompilati automaticamente; ricarica la scheda del browser per visualizzare le modifiche.

  • Per creare una versione di Blockly modificata localmente e testarla, in modalità compressa, come dipendenza di un altro pacchetto npm, esegui

    npm run package

    per creare il pacchetto Blockly, quindi

    cd dist && npm link

    per indicare a npm dove trovare i file compilati, quindi cd nella directory del progetto prima dell'esecuzione

    npm link blockly

    per fare in modo che il tuo pacchetto utilizzi la versione appena compilata di Blockly al posto del pacchetto blockly pubblicato.

Riferimento dettagliato agli script

Questa sezione elenca il principio 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 build.
  • I file nella sottodirectory dist/ costituiscono i contenuti del pacchetto npm pubblicato.

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

clean

npm run clean ripulisce qualsiasi build precedente eliminando le directory build/ e dist/. Utile per correggere gli errori arcani di build, in particolare quelli causati dalla ridenominazione di un file di origine.

messages

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

langfiles

npm run langfiles genera i file del linguaggio compilato in build/msg/ dai file dei messaggi in msg/json.

tsc

npm run tsc esegue il compilatore TypeScript sui contenuti delle directory core/, blocks/ e generators/ e restituisce i 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 blocchi (gruppi minimi), dopodiché esegue closure-compiler per creare i blocchi nel seguente modo:

  • 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.
  • Lo stesso vale per dart, lua, php e python.

I blocchi generati utilizzano un wrapper per garantire la compatibilità con la definizione del modulo universale, quindi non è necessaria ulteriore elaborazione prima di essere inclusi nel pacchetto.

build

npm run build esegue le attività minify e langfiles. Questa operazione dovrebbe eseguire tutte le operazioni necessarie per caricare il parco giochi 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/, inserendo le versioni con wrapping in dist/msg/.
  • Aggiunge vari file di supporto aggiuntivi a dist/, con wrapper UMD ove applicabile.

publish

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

lint

npm run lint esegue ESLint, eseguendo analisi statiche del codice sorgente di Blockly per individuare eventuali problemi.

test

npm test (o npm run test) esegue l'attività package e poi diversi test automatici (tra cui l'esecuzione di ESLint). Dovrebbe essere eseguito e trasmesso su qualsiasi codice inviato come richiesta di pull sul repository a blocchi.