Script di compilazione

Blockly è composto da oltre cento file TypeScript. Questi devono essere compilati dal compilatore TypeScript, tsc, in JavaScript prima di poter essere utilizzati. In questo modo, viene creato un numero altrettanto elevato di file .js adatti ai test locali, ma il caricamento di un numero così elevato di file su internet è un'esperienza lenta per gli utenti finali. Per velocizzare il caricamento di Blockly, viene utilizzato Closure Compiler per comprimerli (ridurli) e combinarli in una mezza dozzina di file ("bundle" o "chunk") con una dimensione totale inferiore alla metà di quella dei file non compressi.

Durante il processo, il codice che utilizza le funzionalità ECMAScript più recenti, che potrebbero non essere compatibili con tutti i browser, viene transpilato in ES6, che è generalmente compatibile con i browser più utilizzati. Pertanto, è importante che tu fornisca solo il codice minimizzato ai tuoi 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 pacchetto NPM blockly e dal 2022 sono stati allegati anche come file .tgz a ogni release di GitHub, quindi non è necessario creare Blockly, a meno che tu non stia lavorando su Blockly stesso, in particolare sui file nelle directory core, blocks, generators o msg.

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

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, facilita un rapido ciclo di modifica-compilazione-esecuzione; facilita anche il debug, poiché il codice JavaScript in esecuzione è quasi leggibile come le origini TypeScript originali, eliminando la necessità di dipendere dalle sourcemap.

Il caricamento di Blockly dai bundle compressi è chiamato "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 npm blockly.

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

Avvio rapido

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

    npm test

    per creare Blockly ed eseguire la relativa suite di test.

  • Se vuoi testare le modifiche locali nel browser, esegui

    npm start

    Viene compilato Blockly e si apre un browser web che punta al playground di Blockly che esegue Blockly in modalità non compressa.

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

  • Per creare la 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 di eseguire

    npm link blockly

    per fare in modo che il pacchetto utilizzi la versione di Blockly appena compilata anziché il pacchetto blockly pubblicato.

Riferimento dettagliato dello 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 inseriti nelle parti successive della pipeline di build.
  • I file nella sottodirectory dist/ formano i contenuti del pacchetto npm pubblicato.

Nessuna directory viene monitorata nel repository Git di Blockly.

clean

npm run clean pulisce le build precedenti eliminando le directory build/ e dist/. Utile per risolvere errori di compilazione arcani, in particolare quelli causati dalla ridenominazione di un file sorgente.

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 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 dividere i file .js compilati in blocchi (bundle ridotti), dopodiché esegue closure-compiler per creare i blocchi 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.
  • 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, quindi non è necessario alcun ulteriore trattamento prima che vengano inclusi nel pacchetto.

build

npm run build esegue le attività minify e langfiles. In questo modo dovrebbe essere possibile caricare l'area giochi di Blockly in modalità compressa o non compressa.

package

npm run package esegue le attività clean e build e poi:

  • Applica un wrapper UMD ai file in build/msg/, inserendo le versioni sottoposte a wrapping in dist/msg/.
  • Aggiunge vari file di supporto aggiuntivi a dist/, con wrapper UMD, se applicabile.

publish

npm run publish viene utilizzato dal team 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, eseguendo l'analisi statica del codice sorgente di Blockly per trovare problemi.

test

npm test (o npm run test) esegue l'attività package e poi vari test automatizzati (inclusa l'esecuzione di ESLint). Questo test deve essere eseguito e superato per qualsiasi codice inviato come richiesta pull rispetto al repository Blockly.