dart compile

Esta guía describe cómo usar el comando dart compile para compilar un programa de Dart para una plataforma de destino.

Usa el comando dart compile para compilar un programa de Dart para una plataforma de destino. La salida —que especificas usando un subcomando— puede incluir un Dart runtime o ser un módulo (también conocido como snapshot).

Aquí tienes un ejemplo del uso del subcomando exe para producir un archivo ejecutable autónomo (myapp.exe):

$ dart compile exe bin/myapp.dart
Generated: /Users/me/myapp/bin/myapp.exe

El siguiente ejemplo usa el subcomando aot-snapshot para producir un módulo compilado ahead-of-time (AOT) (myapp.aot). Luego usa el comando dartaotruntime (el cual proporciona un Dart runtime) para ejecutar el módulo AOT:

$ dart compile aot-snapshot bin/myapp.dart
Generated: /Users/me/myapp/bin/myapp.aot
$ dartaotruntime bin/myapp.aot

Para especificar la ruta al archivo de salida, usa la opción -o o --output:

$ dart compile exe bin/myapp.dart -o bin/runme

Para obtener más opciones e información de uso, ejecuta dart compile [<subcomando>] --help:

$ dart compile exe --help

Consulta el ejemplo native_app para ver un ejemplo sencillo de cómo usar dart compile para compilar una aplicación nativa, seguido de ejemplos de cómo ejecutarla.

La siguiente tabla muestra los subcomandos de dart compile.

Las siguientes secciones contienen detalles sobre cada tipo de salida que dart compile puede producir.

El subcomando exe produce un ejecutable autónomo para Windows, macOS o Linux. Un ejecutable autónomo es código de máquina nativo que se compila a partir del archivo Dart especificado y sus dependencias, además de un pequeño Dart runtime que maneja la comprobación de tipos y la recolección de basura.

Puedes distribuir y ejecutar el archivo de salida como lo harías con cualquier otro archivo ejecutable.

Compila tu aplicación y establece el archivo de salida:

$ dart compile exe bin/myapp.dart -o /tmp/myapp

Cuando tiene éxito, este comando genera lo siguiente:

Generated: /tmp/myapp

Ejecuta tu aplicación compilada desde el directorio /tmp:

$ ./tmp/myapp

La siguiente tabla muestra qué sistemas operativos host de 64 bits admiten la compilación cruzada para qué objetivos:

Para usar la compilación cruzada, incluye las siguientes banderas:

--target-os=linux

El sistema operativo de destino para el ejecutable compilado. Solo el sistema operativo Linux es compatible en este momento.

--target-arch=value

La arquitectura de destino para el ejecutable compilado. El valor para esta bandera puede ser:

• arm: Procesador ARM de 32 bits
• arm64: Procesador ARM de 64 bits
• riscv64: Procesador RISC-V de 64 bits (RV64GC)
• x64: Procesador x86-64

El siguiente comando demuestra cómo compilar de forma cruzada (cross-compile) un ejecutable autónomo para un sistema Linux de 64 bits:

dart compile exe \
  --target-os=linux \
  --target-arch=x64 \
  hello.dart

Internamente, este comando descarga binarios adicionales de Dart SDK y los almacena en caché en el directorio ~/.dart.

Aquí tienes un ejemplo de salida con la bandera --verbose especificada en el comando:

Downloading https://storage.googleapis.com/dart-archive/channels/dev/signed/hash/...4864.../sdk/gen_snapshot_macos_arm64_linux_x64...
Downloading https://storage.googleapis.com/dart-archive/channels/dev/raw/hash/...64e44.../sdk/dartaotruntime_linux_x64...
Specializing Platform getters for target OS linux.
Generating AOT kernel dill.
Compiling /tmp/hello.dart to /tmp/hello.exe using format Kind.exe:
Generating AOT snapshot. path/to/dir/.dart/3.8.0-265.0.dev/gen_snapshot_macos_arm64_linux_x64 []
Generating executable.
Marking binary executable.
Generated: /tmp/hello.exe

Los ejecutables creados con dart compile exe admiten firma en macOS y Windows.

Para obtener más información sobre la firma de código específica de la plataforma, consulta la documentación de la plataforma para esos sistemas operativos:

• Documentación de SignTool.exe de Windows
• Guía de firma de código de Apple

El subcomando exe tiene las siguientes limitaciones conocidas:

• Sin soporte para dart:mirrors y dart:developer. Para obtener una lista completa de las bibliotecas principales que puedes usar, consulta las tablas de bibliotecas Multiplataforma y Plataforma nativa.

• La compilación cruzada está soportada, pero el SO de destino está limitado a Linux. Para obtener más información, consulta Compilación cruzada.

Usa módulos AOT para reducir los requisitos de espacio en disco al distribuir múltiples aplicaciones de línea de comandos. El subcomando aot-snapshot produce un archivo de salida específico de la arquitectura actual en la que compilas tu aplicación.

Por ejemplo, si usas macOS para crear un archivo .aot, ese archivo solo se podrá ejecutar en macOS. Dart admite módulos AOT en Windows, macOS y Linux.

Compila tu aplicación y establece el archivo de salida:

$ dart compile aot-snapshot bin/myapp.dart

Cuando tiene éxito, este comando genera lo siguiente:

Generated: /Users/me/myapp/bin/myapp.aot

Ejecuta tu aplicación compilada desde el directorio /bin:

$ dartaotruntime bin/myapp.aot

Para obtener más información, consulta la documentación de dartaotruntime.

El soporte de compilación cruzada para el subcomando aot-snapshot es el mismo que está disponible para el subcomando exe. Para obtener más información, consulta Ejecutables autónomos (exe).

El subcomando aot-snapshot tiene las mismas limitaciones que el subcomando exe. Para obtener más información, consulta Ejecutables autónomos (exe)

Los módulos JIT incluyen todas las clases analizadas (parsed) y el código compilado que se genera durante una ejecución de entrenamiento (training run) de un programa.

$ dart compile jit-snapshot bin/myapp.dart
Compiling bin/myapp.dart to jit-snapshot file bin/myapp.jit.
Hello world!
$ dart run bin/myapp.jit
Hello world!

Al ejecutar desde un módulo de aplicación, la Dart VM no necesita analizar ni compilar las clases y funciones que ya se usaron durante la ejecución de entrenamiento, por lo que la VM comienza a ejecutar el código de usuario más rápido.

Estos módulos son específicos de la arquitectura, a diferencia de los módulos producidos utilizando el subcomando kernel.

Usa el subcomando kernel para empaquetar una aplicación en un solo archivo portátil que se pueda ejecutar en todos los sistemas operativos y arquitecturas de CPU. Un módulo kernel contiene una forma binaria del árbol de sintaxis abstracta (Kernel AST) para un programa Dart.

Aquí tienes un ejemplo de creación y ejecución de un módulo kernel:

$ dart compile kernel bin/myapp.dart
Compiling bin/myapp.dart to kernel file bin/myapp.dill.
$ dart run bin/myapp.dill

Aunque los módulos kernel tienen un tiempo de inicio reducido en comparación con el código Dart, pueden tener un inicio mucho más lento que los formatos de salida AOT específicos de la arquitectura.

El subcomando js compila código Dart a JavaScript desplegable.

El comando dart compile js tiene múltiples opciones para personalizar la compilación de código JavaScript.

• Opciones básicas
• Opciones de ruta y entorno
• Opciones de visualización
• Opciones de análisis

Opciones básicas

Las opciones comunes incluyen:

-o <file> o --output=<file>

Genera la salida en <file>. Si no se especifica, la salida va a un archivo llamado out.js.

--enable-asserts

Habilita la verificación de aserciones.

-O{0|1|2|3|4}

Controla las optimizaciones para reducir el tamaño del archivo y mejorar el rendimiento del código. Para obtener más información sobre estas optimizaciones, ejecuta dart compile js -hv.

• -O0: Deshabilita muchas optimizaciones.

• -O1: Habilita las optimizaciones por defecto.

• -O2: Habilita las optimizaciones de -O1, más otras adicionales (como la minimización) que respetan la semántica del lenguaje y son seguras para todos los programas.

• -O3: Habilita las optimizaciones de -O2, además omite las comprobaciones de tipo implícitas.

• -O4: Habilita optimizaciones más agresivas que -O3, pero con las mismas suposiciones.

--no-source-maps

No generar un archivo de mapa de fuentes (source map).

-h o --help

Muestra la ayuda. Para obtener información sobre todas las opciones, usa -hv.

Opciones de ruta y entorno

Algunas otras opciones útiles incluyen:

--packages=<path>

Especifica la ruta al archivo de configuración de resolución de paquetes. Para obtener más información, consulta la especificación del archivo de configuración de paquetes de Dart.

-D<flag>=<value>

Define un par de declaración de entorno y valor al cual se puede acceder con String.fromEnvironment, int.fromEnvironment, bool.fromEnvironment, o bool.hasEnvironment. Para obtener más información sobre las declaraciones de entorno, consulta Configurar aplicaciones con declaraciones de entorno de compilación.

--version

Muestra información de la versión de dart.

Opciones de visualización

Las siguientes opciones te ayudan a controlar la salida del compilador.

--suppress-warnings

No muestra advertencias.

--suppress-hints

No muestra sugerencias.

--terse

Emite diagnósticos, sin sugerir cómo deshacerse de los problemas diagnosticados.

-v o --verbose

Muestra mucha información.

Opciones de análisis

Las siguientes opciones controlan el análisis realizado en el código Dart.

--fatal-warnings

Tratar las advertencias como errores de compilación.

--enable-diagnostic-colors

Agrega colores a los mensajes de diagnóstico.

--show-package-warnings

Muestra advertencias y sugerencias generadas a partir de paquetes.

--csp

Deshabilita la generación dinámica de código en la salida generada. Esto es necesario para satisfacer las restricciones de CSP (consulta W3C Content Security Policy.)

--dump-info

Genera un archivo (con el sufijo .info.json) que contiene información sobre el código generado. Puedes inspeccionar el archivo generado con herramientas en dart2js_info.

Por ejemplo, para compilar una aplicación de Dart a JavaScript optimizado, ejecuta el siguiente comando:

$ dart compile js -O2 -o out/main.js web/main.dart

Sigue estas prácticas para mejorar la inferencia de tipos, reducir el tamaño del archivo y mejorar el rendimiento de JavaScript:

• No uses Function.apply().
• No sobrescribas noSuchMethod().
• Evita establecer variables a null.
• Sé consistente con los tipos de argumentos que pasas a cada función o método.

Para obtener más información sobre la creación y el despliegue de aplicaciones de JavaScript, consulta Despliegue web.