Scripts de build do Blockly

O Blockly é composto por mais de cem arquivos TypeScript. Eles precisam ser compilados pelo compilador do TypeScript, tsc, em JavaScript antes de serem usados. Isso cria um número igualmente grande de arquivos .js, adequados para testes locais, mas carregar um número tão grande de arquivos pela Internet é uma experiência lenta para os usuários finais. Para tornar o carregamento do Blockly mais rápido, o Closure Compiler é usado para compactar (minimizar) e combiná-los em meia dúzia de arquivos ("pacotes" ou "fragmentos") com um tamanho total menor que a metade dos arquivos descompactados.

Durante o processo, o código que usa os recursos mais recentes do ECMAScript, que podem não ser compatíveis com todos os navegadores, é transpilado para ES6, que geralmente é compatível com a maioria dos navegadores mais usados. Portanto, é importante que você forneça apenas o código minimizado aos usuários finais.

O repositório google/blockly contém apenas o código-fonte. Anteriormente, ele também continha os produtos de build, mas, desde 2019, os pacotes minificados foram publicados como o pacote blockly NPM e, desde 2022, também eram anexados como um arquivo .tgz a cada versão do GitHub. Por isso, não é necessário criar o Blockly, a menos que você esteja invadindo o próprio Blockly, principalmente em arquivos nos diretórios core, blocks, generators ou msg.

O processo de criação, teste e publicação do Blockly é automatizado usando scripts npm para executar tarefas do Gulp (links em inglês). Esta página documenta os scripts principais e o que cada um deles faz.

Modos compactado e descompactado

O carregamento do Blockly diretamente dos arquivos .js individuais gerados pelo compilador TypeScript é chamado de "modo descompactado". Como ele evita várias etapas de build lentas, isso facilita um ciclo rápido de edição-compilação-execução. Ele também facilita a depuração, já que o código JavaScript executado é quase tão legível quanto as origens originais do TypeScript, dispensando a necessidade de depender de sourcemaps.

O carregamento do Blockly nos pacotes minificados é chamado de "modo compactado". Essa é a melhor maneira de testar mudanças no Blockly ao usá-lo como uma dependência de outro pacote, porque ele testa (uma versão não publicada) o pacote npm blockly.

N.B.: Há alguns lugares no repositório do Blockly em que os termos "modo não compilado" e "modo compilado" são usados como sinônimos de "modo não comprimido" e "modo comprimido", respectivamente. Esse uso fazia sentido no passado, porque o Closure Compiler era usado para compactar (minificar) o código, mas agora o compilador TypeScript é sempre necessário, mesmo no modo descompactado. Portanto, essa terminologia alternativa pode ser confusa e não recomendada.

Início rápido

Se você fez alterações locais e quer verificar se elas não quebraram o build ou algum teste, execute
```
npm test
```
para criar o Blockly e executar o pacote de testes.
Se você quiser testar as mudanças locais no navegador, execute
```
npm start
```
Isso compila o Blockly e abre um navegador da Web apontando para o playground do Blockly que está executando o Blockly no modo descompactado.

Todos os arquivos em core/, blocks/ e generators/ que forem modificados serão recompilados automaticamente. Atualize a guia do navegador para conferir as mudanças.
Para criar e testar a versão modificada localmente do Blockly, no modo comprimido, como uma dependência de outro pacote npm, execute
```
npm run package
```
para criar o pacote do Blockly, depois
```
cd dist && npm link
```
para informar ao npm onde encontrar os arquivos compilados e, em seguida, cd para o diretório do seu projeto antes da execução
```
npm link blockly
```
para que o pacote use a versão recém-compilada do Blockly no lugar do pacote blockly publicado.

Referência detalhada do script

Esta seção lista os princípios scripts no arquivo package.json do Blockly com uma explicação do que eles fazem.

Esses scripts geram arquivos em dois locais:

Os arquivos no subdiretório build/ são arquivos intermediários usados para testes locais ou ingeridos por partes posteriores do pipeline de build.
Os arquivos no subdiretório dist/ formam o conteúdo do pacote npm publicado.

Nenhum diretório é rastreado no repositório do Git do Blockly.

`clean`

O npm run clean limpa todos os builds anteriores excluindo os diretórios build/ e dist/. Útil para corrigir falhas de build obscuras, principalmente aquelas causadas pela renomeação de um arquivo de origem.

`messages`

npm run messages atualiza os arquivos de mensagens em msg/json/ com as alterações feitas em msg/messages.js e precisa ser executado sempre que esse arquivo for modificado.

`langfiles`

npm run langfiles gera os arquivos de linguagem compilados em build/msg/ a partir dos arquivos de mensagens em msg/json.

`tsc`

O npm run tsc executa o compilador TypeScript no conteúdo dos diretórios core/, blocks/ e generators/ e gera arquivos .js individuais para build/src/.

`minify`

npm run minify executa closure-make-deps e closure-calculate-chunks para determinar como dividir os arquivos .js compilados em pedaços (pacotes minimizados), depois executa closure-compiler para criar os pedaços da seguinte maneira:

O conteúdo de build/src/core/ se torna dist/blockly_compressed.js.
O conteúdo de build/src/blocks/ se torna dist/blocs_compressed.js.
O conteúdo de build/src/generators/javascript/ (mais build/src/generators/javascript.js) se torna dist/javascript_compressed.js.
O mesmo vale para dart, lua, php e python.

Os chuks gerados usam um wrapper para garantir a compatibilidade com a definição de módulo universal. Assim, não é necessário nenhum processamento extra antes de serem incluídos no pacote.

`build`

npm run build executa as tarefas minify e langfiles. Isso deve fazer tudo o que é necessário para carregar o playground do Blockly no modo compactado ou descompactado.

`package`

npm run package executa as tarefas clean e build e, em seguida:

Aplica um wrapper de UMD aos arquivos em build/msg/, colocando as versões unidas em dist/msg/.
Vários arquivos de suporte adicionais foram adicionados a dist/, com wrappers UMD, quando aplicável.

`publish`

A npm run publish é usada pela equipe do Blockly para publicar o pacote npm blockly. Ele depende da infraestrutura interna do Google e, portanto, não é útil para desenvolvedores externos.

`lint`

npm run lint executa o ESLint, realizando a análise estática do código-fonte do Blockly para encontrar problemas.

`test`

npm test (ou npm run test) executa a tarefa package e, em seguida, vários testes automatizados, incluindo a execução do ESLint. Isso deve ser executado e transmitido em qualquer código enviado como uma solicitação de envio para o repositório com bloqueio.