Secuencias de comandos de compilación de Blockly

Blockly tiene más de cien archivos de TypeScript. El compilador de TypeScript, tsc, debe compilarlos en JavaScript para poder usarlos. Esto crea una cantidad igual de grande de archivos .js que son adecuados para las pruebas locales. Sin embargo, cargar una cantidad tan grande de archivos por Internet es una experiencia lenta para los usuarios finales. Para que Blockly se cargue más rápido, se usa el compilador de cierre para comprimirlos (minificarlos) y combinarlos en media docena de archivos (“paquetes” o “fragmentos”) con un tamaño total inferior a la mitad del de los archivos sin comprimir.

En el proceso, el código que usa las funciones más recientes de ECMAScript (que pueden no ser compatibles con todos los navegadores) se transpila a ES6, que suele ser compatible con los navegadores más utilizados. Por lo tanto, es importante que entregues solo el código reducido a los usuarios finales.

El repositorio google/blockly contiene solo el código fuente. Anteriormente, también contenía los productos de compilación, pero desde 2019 los paquetes reducidos se publicaron como el paquete blockly de NPM y, desde 2022, también se adjuntaron como un archivo .tgz a cada versión de GitHub, por lo que no es necesario compilar Blockly, a menos que estés hackeando en Blockly, en particular en archivos de los directorios core, blocks, generators o msg.

El proceso de compilación, prueba y publicación de Blockly se automatiza mediante secuencias de comandos de npm para ejecutar tareas de Gup. Esta página documenta las principales secuencias de comandos y lo que cada una hace.

Modo comprimido y sin comprimir

La carga de Blockly directamente desde los archivos .js individuales generados por el compilador de TypeScript se denomina "modo sin comprimir". Debido a que se evitan varios pasos de compilación lentos, se facilita un ciclo rápido de edición, compilación y ejecución, y la depuración, ya que el código JavaScript que se ejecuta es casi tan legible como las fuentes originales de TypeScript, lo que evita la necesidad de depender de mapas de origen.

La carga de Blockly desde los paquetes reducidos se denomina "modo comprimido". Esta es la mejor manera de probar los cambios en Blockly cuando lo usas como dependencia de otro paquete, ya que prueba (una versión no publicada) el paquete de npm blockly.

N.B.: Hay algunos lugares en el repositorio en bloque en los que los términos "modo sin compilar" y "modo compilado" se usan como sinónimos de "modo sin comprimir" y "modo comprimido", respectivamente. Este uso tenía sentido en el pasado, ya que se utilizaba Closure Compiler para comprimir (minificar) el código, pero ahora el compilador de TypeScript siempre es necesario, incluso en el modo sin comprimir, por lo que esta terminología alternativa puede resultar confusa y desaconsejada.

Inicio rápido

  • Si realizaste cambios locales y quieres asegurarte de que no hayan dañado la compilación ni las pruebas, ejecuta

    npm test
    

    para compilar Blockly y ejecutar su paquete de pruebas.

  • Si quieres probar los cambios locales en el navegador, ejecuta lo siguiente:

    npm start
    

    Esto compila Blockly y abre un navegador web que apunta a la zona de pruebas de Blockly que ejecuta Blockly en modo sin comprimir.

    Todos los archivos en core/, blocks/ y generators/ que se modifiquen se volverán a compilar automáticamente. Vuelve a cargar la pestaña del navegador para ver los cambios.

  • Para compilar la versión de Blockly modificada de forma local y probarla, en modo comprimido, como una dependencia de otro paquete npm, ejecuta lo siguiente:

    npm run package
    

    para compilar el paquete de Blockly, luego

    cd dist && npm link
    

    para indicarle a npm dónde encontrar los archivos compilados y, luego, usar cd en el directorio de tu proyecto antes de ejecutarlo

    npm link blockly
    

    para que tu paquete use la versión recién compilada de Blockly, en lugar del paquete blockly publicado.

Referencia detallada de la secuencia de comandos

En esta sección, se enumera el principio scripts en el archivo package.json de Blockly con una explicación de lo que hacen.

Estas secuencias de comandos generan archivos en dos lugares:

  • Los archivos del subdirectorio build/ son archivos intermedios que se usan para pruebas locales o que transfieren partes posteriores de la canalización de compilación.
  • Los archivos del subdirectorio dist/ forman el contenido del paquete npm publicado.

No se realiza un seguimiento de ninguno de los directorios en el repositorio de Git bloqueado.

clean

npm run clean borra las compilaciones anteriores borrando los directorios build/ y dist/. Es útil para solucionar fallas de compilación extrañas, en especial las causadas por el cambio de nombre de un archivo fuente.

messages

npm run messages actualiza los archivos de mensajes en msg/json/ con cualquier cambio que se haya realizado en msg/messages.js y debe ejecutarse después de cada vez que se modifica ese archivo.

langfiles

npm run langfiles genera los archivos de idioma compilados en build/msg/ a partir de los archivos de mensajes en msg/json.

tsc

npm run tsc ejecuta el compilador de TypeScript en el contenido de los directorios core/, blocks/ y generators/, y genera archivos .js individuales en build/src/.

minify

npm run minify ejecuta closure-make-deps y closure-calculate-chunks para determinar cómo dividir los archivos .js compilados en fragmentos (paquetes minificados) y, luego, ejecutar closure-compiler para crear los fragmentos de la siguiente manera:

  • El contenido de build/src/core/ se convierte en dist/blockly_compressed.js.
  • El contenido de build/src/blocks/ se convierte en dist/blocs_compressed.js.
  • El contenido de build/src/generators/javascript/ (más build/src/generators/javascript.js) se convierte en dist/javascript_compressed.js.
  • Del mismo modo, para dart, lua, php y python.

Los fragmentos generados usan un wrapper para garantizar la compatibilidad con la definición universal del módulo, por lo que no se necesita procesamiento adicional antes de incluirlos en el paquete.

build

npm run build ejecuta las tareas minify y langfiles. Esto debería hacer todo lo necesario para cargar la zona de pruebas de Blockly en modo comprimido o sin comprimir.

package

npm run package ejecuta las tareas clean y build, y luego:

  • Aplica un wrapper de UMD a los archivos en build/msg/ y coloca las versiones unidas en dist/msg/.
  • Agrega varios archivos de compatibilidad adicionales a dist/, con wrappers de UMD cuando corresponda.

publish

El equipo de Blockly usa npm run publish para publicar el paquete de npm de blockly. Depende de la infraestructura interna de Google, por lo que no es útil para los desarrolladores externos.

lint

npm run lint ejecuta ESLint y realiza un análisis estático del código fuente de Blockly para encontrar problemas.

test

npm test (o npm run test) ejecuta la tarea package y, luego, ejecuta varias pruebas automatizadas (incluida la ejecución de ESLint). Esto debe ejecutarse y pasar en cualquier código enviado como una solicitud de extracción en el repositorio de Blockly.