Configurar aplicaciones con declaraciones de entorno de compilación

Puedes especificar declaraciones de entorno de compilación al compilar o ejecutar una aplicación Dart. Las declaraciones de entorno de compilación especifican opciones de configuración como pares clave-valor que se acceden y evalúan en tiempo de compilación.

Tu aplicación puede usar los valores de las declaraciones de entorno para cambiar su funcionalidad o comportamiento. Los compiladores de Dart pueden eliminar el código que quede inaccesible debido al flujo de control utilizando los valores de las declaraciones de entorno.

Podrías definir y usar declaraciones de entorno para:

• Agregar funcionalidad durante la depuración, como habilitar el registro (logging).
• Crear diferentes versiones (flavors) de tu aplicación.
• Configurar el comportamiento de la aplicación, como el puerto de un servidor HTTP.
• Habilitar un modo experimental de tu aplicación para pruebas.
• Cambiar entre backends de prueba y producción.

Para especificar una declaración de entorno al ejecutar o compilar una aplicación Dart, usa la opción --define o su abreviatura, -D. Especifica el par clave-valor de la declaración usando el formato <NAME>=<VALUE>:

$ dart run --define=DEBUG=true -DFLAVOR=free

Para aprender cómo configurar estas declaraciones con otras herramientas, consulta la sección de especificar declaraciones de entorno en esta guía. Esa sección explica la sintaxis de las declaraciones y cómo especificarlas en la línea de comandos y en IDEs y editores.

Para acceder a los valores especificados de las declaraciones de entorno, usa uno de los constructores fromEnvironment con const o dentro de un contexto constante. Usa bool.fromEnvironment para valores true o false, int.fromEnvironment para valores enteros, y String.fromEnvironment para cualquier otra cosa.

Cada uno de los constructores fromEnvironment requiere el nombre o la clave de la declaración de entorno. También aceptan un argumento con nombre opcional defaultValue para sobrescribir el valor predeterminado de respaldo. El valor predeterminado de respaldo se usa cuando no se define una declaración o el valor especificado no se puede analizar como el tipo esperado.

Por ejemplo, si deseas imprimir mensajes de registro solo cuando la declaración de entorno DEBUG esté configurada en true:

void log(String message) {
  // Log the debug message if the environment declaration 'DEBUG' is `true`.
  // If there was no value specified, do not log.
  if (const bool.fromEnvironment('DEBUG', defaultValue: false)) {
    print('Debug: $message');
  }
}

En este fragmento de código, si DEBUG está configurado en false durante la compilación, o no se especifica en absoluto, los compiladores de producción pueden eliminar por completo la condición y su cuerpo.

Los constructores fromEnvironment recurren a un valor predeterminado cuando la declaración no está especificada o el valor especificado no se puede analizar. Por lo tanto, para verificar específicamente si se ha especificado una declaración de entorno, usa el constructor bool.hasEnvironment:

if (const bool.hasEnvironment('DEBUG')) {
  print('Debug behavior was configured!');
}

Tanto dart run como los subcomandos de dart compile aceptan cualquier cantidad de opciones -D o --define para especificar valores de declaraciones de entorno.

$ dart run --define=DEBUG=true -DFLAVOR=free main.dart
$ dart compile exe --define=DEBUG=true -DFLAVOR=free main.dart
$ dart compile js --define=DEBUG=true -DFLAVOR=free main.dart
$ dart compile aot-snapshot --define=DEBUG=true -DFLAVOR=free main.dart
$ dart compile jit-snapshot --define=DEBUG=true -DFLAVOR=free main.dart
$ dart compile kernel --define=DEBUG=true -DFLAVOR=free main.dart

Para aprender sobre cómo configurar webdev para pasar declaraciones de entorno a los compiladores web de desarrollo y producción, consulta la documentación de configuración de webdev.

En tu configuración de lanzamiento (launch.json) bajo configurations, agrega una nueva clave toolArgs que contenga las declaraciones de entorno deseadas:

"configurations": [
    {
        "name": "Dart",
        "request": "launch",
        "type": "dart",
        "toolArgs": [
          "--define=DEBUG=true"
        ]
    }
]

Para aprender más, consulta la documentación para configuraciones de lanzamiento de VS Code.

En las Run/Debug Configurations para tu proyecto, agrega las declaraciones de entorno deseadas a VM options:

Para aprender más, consulta la documentación de JetBrains para Dart Run/Debug Configurations.

Para especificar declaraciones de entorno a la herramienta Flutter, usa la opción --dart-define en su lugar:

$ flutter run --dart-define=DEBUG=true