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/
ygenerators/
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 ejecutarlonpm 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 endist/blockly_compressed.js
. - El contenido de
build/src/blocks/
se convierte endist/blocs_compressed.js
. - El contenido de
build/src/generators/javascript/
(másbuild/src/generators/javascript.js
) se convierte endist/javascript_compressed.js
. - Del mismo modo, para
dart
,lua
,php
ypython
.
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 endist/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.