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, que são adequados para testes locais. No entanto, 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 (reduzir) e combiná-los em meia dúzia de arquivos ("pacotes" ou "blocos") com tamanho total inferior à metade dos arquivos descompactados.

No processo, o código que usa os recursos do ECMAScript mais recentes (que podem não ser compatíveis com todos os navegadores) é transcompilado para o ES6, que geralmente é compatível com os navegadores mais usados. Portanto, é importante exibir apenas o código minimizado para os 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 minimizados foram publicados como o pacote blockly do NPM e, desde 2022, também anexado como um arquivo .tgz a cada versão do GitHub. Portanto, não é necessário criar o Blockly, a menos que você esteja invadindo o Blockly, principalmente nos arquivos dos diretórios core, blocks, generators ou msg.

O processo de criação, teste e publicação do Blockly é automatizado com scripts npm para executar tarefas Gulp (links em inglês). Nesta página, documentamos os scripts de princípios e o que cada um faz.

Modo compactado e descompactado

O carregamento do Blockly diretamente dos arquivos .js individuais gerados pelo compilador TypeScript é chamado de "modo não compactado". Como ele evita várias etapas lentas de build, isso facilita um ciclo rápido de edição/compilação e execução. Além disso, facilita a depuração, já que o código JavaScript que está sendo executado é quase tão legível quanto as fontes do TypeScript originais, eliminando a necessidade de depender de mapas de origem.

O carregamento do Blockly a partir dos pacotes minimizados é 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 do) pacote npm blockly.

N.B.: Há alguns locais no repositório em blocos em que os termos "modo não compilado" e "modo compilado" são usados como sinônimos para "modo não compactado" e "modo compactado", respectivamente. Esse uso fazia sentido no passado, já que o closure Compiler era usado para compactar (minificar) o código, mas agora o compilador TypeScript é sempre necessário, mesmo no modo descompactado. Por isso, essa terminologia alternativa é potencialmente confusa e não recomendada.

Início rápido

  • Se você tiver feito mudanças locais e quiser garantir que elas não corrompem o build ou algum teste, execute

    npm test

    para criar o Blockly e executar o pacote de testes.

  • Se você quiser testar alterações locais no navegador, execute

    npm start

    Isso compila o Blockly e abre um navegador da Web apontando para o playground do Blockly que executa 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 ver as mudanças.

  • Para criar sua versão modificada localmente do Blockly e testá-la, no modo compactado, como uma dependência de outro pacote npm, execute

    npm run package

    para criar um pacote Blockly,

    cd dist && npm link

    para informar ao npm onde encontrar os arquivos compilados e, em seguida, usar cd no diretório do projeto antes da execução.

    npm link blockly

    para que seu 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 o princípio 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 intermediários usados para testes locais ou ingeridos por partes posteriores do pipeline de compilação.
  • Os arquivos no subdiretório dist/ formam o conteúdo do pacote npm publicado.

Nenhum dos diretórios é rastreado no repositório git em blocos.

clean

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

messages

npm run messages atualiza os arquivos de mensagens em msg/json/ com todas as mudanças feitas em msg/messages.js e precisa ser executado sempre que o arquivo for modificado.

langfiles

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

tsc

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

O npm run minify executa closure-make-deps e closure-calculate-chunks para determinar como dividir os arquivos .js compilados em blocos (pacotes minificados). Depois disso, ele executa closure-compiler para criar os blocos 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 acontece com dart, lua, php e python.

Os blocos gerados usam um wrapper para garantir a compatibilidade com a Universal Module Definition. Assim, nenhum processamento extra é necessário antes de serem incluídos no pacote.

build

npm run build executa as tarefas minify e langfiles. Ela faz tudo o que é necessário para carregar o Playground Blockly no modo compactado ou não.

package

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

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

publish

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

lint

O npm run lint executa o ESLint (link em inglês), 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, executa vários testes automatizados, incluindo a execução do ESLint. Ela precisa ser executada e transmitida em qualquer código enviado como uma solicitação de envio para o repositório em blocos.