Scripts de build

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

No 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 os navegadores mais usados. Portanto, é importante veicular apenas o código minimizado para os usuários finais.

O repositório RaspberryPiFoundation/blockly contém apenas o código-fonte. Antes, ele também continha os produtos de build, mas, desde 2019, os pacotes minificados são publicados como o pacote blockly NPM e, desde 2022, também são anexados como um arquivo .tgz a cada lançamento do GitHub. Portanto, não é necessário criar o Blockly, a menos que você esteja hackeando 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. Esta página documenta os principais scripts e o que cada um faz.

Modo compactado e descompactado

Carregar o 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-execução. Também facilita a depuração, já que o código JavaScript em execução é quase tão legível quanto as fontes TypeScript originais, eliminando a necessidade de depender de mapas de origem.

Carregar o Blockly dos 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 blockly npm.

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

Início rápido

  • Se você fez mudanças locais e quer garantir que elas não prejudicaram o build ou os testes, execute

    npm test

    para criar o Blockly e executar o pacote de testes dele.

  • Se você quiser testar 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 executa o Blockly no modo não compactado.

    Todos os arquivos em core/, blocks/ e generators/ que forem modificados serão recompilados automaticamente. Recarregue a guia do navegador para ver as mudanças.

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

    npm run package

    para criar o pacote do Blockly e, em seguida,

    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 de executar

    npm link blockly

    para que seu pacote use a versão recém-compilada do Blockly em vez do pacote blockly publicado.

Referência detalhada de 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 lugares:

  • Os arquivos no subdiretório build/ são 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 dos diretórios é rastreado no repositório git do Blockly.

clean

O npm run clean limpa 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 mudanças feitas em msg/messages.js e precisa ser executado sempre que o arquivo é modificado.

langfiles

O npm run langfiles gera os arquivos de linguagem compilados em build/msg/ 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 em build/src/.

minify

O npm run minify executa closure-make-deps e closure-calculate-chunks para determinar como dividir os arquivos .js compilados em partes (pacotes minificados). Depois disso, ele executa closure-compiler para criar as partes 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 Universal Module Definition (em inglês). Assim, não é necessário 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 não compactado.

package

npm run package executa as tarefas clean e build e depois:

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

publish

O npm run publish é usado 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

O npm run lint executa o ESLint, realizando uma 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 vários testes automatizados (incluindo a execução do ESLint). Ele precisa ser executado e aprovado em qualquer código enviado como uma solicitação de pull no repositório do Blockly.