Secuencias de comandos de compilación

Blockly se compone de más de cien archivos de TypeScript. El compilador de TypeScript, tsc, debe compilar estos archivos en JavaScript antes de que se puedan usar. Esto crea una cantidad igual de archivos .js que son adecuados para las pruebas locales, pero cargar una cantidad tan grande de archivos a través de Internet es una experiencia lenta para los usuarios finales. Para que Blockly se cargue más rápido, se usa el compilador de Closure para comprimir (reducir) y combinar los archivos en media docena de archivos ("paquetes" o "fragmentos") con un tamaño total inferior a la mitad del tamaño 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 generalmente es compatible con la mayoría de los navegadores más usados. Por lo tanto, es importante que solo publiques el código comprimido para tus usuarios finales.

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

El proceso de compilación, prueba y publicación de Blockly se automatiza con secuencias de comandos de npm para ejecutar tareas de Gulp. En esta página, se documentan los scripts principales y lo que hace cada uno.

Modo comprimido y sin comprimir

Cargar Blockly directamente desde los archivos .js individuales que genera el compilador de TypeScript se conoce como "modo sin comprimir". Como evita varios pasos de compilación lentos, facilita un ciclo rápido de edición, compilación y ejecución. También facilita la depuración, ya que el código JavaScript que se ejecuta es casi tan legible como las fuentes originales de TypeScript, lo que elimina la necesidad de depender de los mapas de origen.

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

N.B.: En algunas partes del repositorio de Blockly, 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 Closure Compiler se usaba para comprimir (minificar) el código, pero ahora siempre se necesita el compilador de TypeScript, incluso en el modo sin comprimir, por lo que esta terminología alternativa puede ser confusa y no se recomienda.

Inicio rápido

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

    npm test

    para compilar Blockly y ejecutar su paquete de pruebas.

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

    npm start

    Esto compila Blockly y abre un navegador web que apunta al Playground de Blockly que ejecuta Blockly en modo sin comprimir.

    Los archivos de core/, blocks/ y generators/ que se modifican se vuelven a compilar automáticamente. Vuelve a cargar la pestaña del navegador para ver los cambios.

  • Para compilar tu versión de Blockly modificada localmente y probarla, en modo comprimido, como dependencia de otro paquete npm, ejecuta

    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, cd al directorio de tu proyecto antes de ejecutar

    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 enumeran los principales scripts en el archivo package.json de Blockly con una explicación de lo que hacen.

Estas secuencias de comandos generan archivos en dos ubicaciones:

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

Ninguno de los directorios se rastrea en el repositorio de Git de Blockly.

clean

npm run clean limpia las compilaciones anteriores borrando los directorios build/ y dist/. Es útil para corregir errores de compilación arcanos, en especial los que se producen por cambiar el nombre de un archivo fuente.

messages

npm run messages actualiza los archivos de mensajes en msg/json/ con los cambios que se hayan realizado en msg/messages.js, y se debe ejecutar cada vez que se modifique ese archivo.

langfiles

npm run langfiles genera los archivos de lenguaje 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 reducidos). Luego, ejecuta 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.
  • Lo mismo sucede con dart, lua, php y python.

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

build

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

package

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

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

publish

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

lint

npm run lint ejecuta ESLint, que 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). Este comando debe ejecutarse (y aprobarse) en cualquier código enviado como solicitud de extracción al repositorio de Blockly.