Configurando aplicações com declarações de ambiente de compilação

Você pode especificar declarações de ambiente de compilação ao construir ou executar uma aplicação Dart. Declarações de ambiente de compilação especificam opções de configuração como pares chave-valor que são acessados e avaliados em tempo de compilação.

Sua aplicação pode usar os valores das declarações de ambiente para mudar sua funcionalidade ou comportamento. Compiladores Dart podem eliminar o código tornado inalcançável devido ao fluxo de controle usando os valores de declaração de ambiente.

Você pode definir e usar declarações de ambiente para:

• Adicionar funcionalidade durante a depuração, como habilitar logging.
• Criar sabores separados de sua aplicação.
• Configurar o comportamento da aplicação, como a porta de um servidor HTTP.
• Habilitar um modo experimental de sua aplicação para testes.
• Alternar entre backends de teste e produção.

Para especificar uma declaração de ambiente ao executar ou compilar uma aplicação Dart, use a opção --define ou sua abreviação, -D. Especifique o par chave-valor da declaração usando um formato <NAME>=<VALUE>:

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

Para aprender como definir essas declarações com outras ferramentas, confira a seção especificando declarações de ambiente neste guia. Essa seção explica a sintaxe de declaração e como especificá-las na linha de comando e em IDEs e editores.

Para acessar valores de declaração de ambiente especificados, use um dos construtores fromEnvironment com const ou dentro de um contexto constante. Use bool.fromEnvironment para valores true ou false, int.fromEnvironment para valores inteiros, e String.fromEnvironment para qualquer outra coisa.

Cada um dos construtores fromEnvironment requer o nome ou chave da declaração de ambiente. Eles também aceitam um argumento nomeado opcional defaultValue para sobrescrever o valor de fallback padrão. O valor de fallback padrão é usado quando uma declaração não está definida ou o valor especificado não pode ser analisado como o tipo esperado.

Por exemplo, se você quiser imprimir mensagens de log apenas quando a declaração de ambiente DEBUG estiver definida como 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');
  }
}

Neste trecho, se DEBUG for definido como false durante a compilação, ou não for especificado de forma alguma, compiladores de produção podem remover completamente a condição e seu corpo.

Os construtores fromEnvironment recorrem a um valor padrão quando a declaração não está especificada ou o valor especificado não pode ser analisado. Portanto, para verificar especificamente se uma declaração de ambiente foi especificada, use o construtor bool.hasEnvironment:

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

Tanto dart run quanto os subcomandos dart compile aceitam qualquer número das opções -D ou --define para especificar valores de declaração de ambiente.

$ 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 configurar webdev para passar declarações de ambiente tanto para os compiladores web de desenvolvimento quanto de produção, confira a documentação de configuração do webdev.

Na sua configuração de lançamento (launch.json) sob configurations, adicione uma nova chave toolArgs contendo suas declarações de ambiente desejadas:

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

Para aprender mais, confira a documentação para configurações de lançamento do VS Code.

Nas Configurações Run/Debug para seu projeto, adicione suas declarações de ambiente desejadas às opções de VM:

Para aprender mais, confira a documentação da JetBrains para Configurações Run/Debug do Dart.

Para especificar declarações de ambiente para a ferramenta Flutter, use a opção --dart-define em vez disso:

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