dart compile

Este guia descreve como usar o comando dart compile para compilar um programa Dart para uma plataforma de destino.

Use o comando dart compile para compilar um programa Dart para uma plataforma de destino. A saída, que você especifica usando um subcomando, pode incluir um Dart runtime ou ser um módulo (também conhecido como snapshot).

ia-translate: true

Aqui está um exemplo de uso do subcomando exe para produzir um arquivo executável autocontido (myapp.exe):

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

O próximo exemplo usa o subcomando aot-snapshot para produzir um módulo compilado ahead-of-time (AOT) (myapp.aot). Em seguida, ele usa o comando dartaotruntime (que fornece um Dart runtime) para executar o módulo AOT:

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

Para especificar o caminho do arquivo de saída, use a opção -o ou --output:

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

Para mais opções e informações de uso, execute dart compile [<subcommand>] --help:

$ dart compile exe --help

Consulte o exemplo native_app para ver um exemplo simples de uso do dart compile para compilar uma aplicação nativa, seguido de exemplos de execução da aplicação.

A tabela a seguir mostra os subcomandos do dart compile.

As seções a seguir detalham cada tipo de saída que o dart compile pode produzir.

O subcomando exe produz um executável independente para Windows, macOS ou Linux. Um executável independente é código de máquina nativo compilado a partir do arquivo Dart especificado e suas dependências, mais um pequeno Dart runtime que cuida da verificação de tipos e da coleta de lixo.

Você pode distribuir e executar o arquivo de saída como faria com qualquer outro arquivo executável.

Compile sua aplicação e defina o arquivo de saída:

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

Quando bem-sucedido, este comando gera a seguinte saída:

Generated: /tmp/myapp

Execute sua aplicação compilada a partir do diretório /tmp:

$ ./tmp/myapp

A tabela a seguir mostra quais sistemas operacionais host de 64 bits suportam cross-compilation para quais alvos:

Para usar a cross-compilation, inclua as seguintes flags:

--target-os=linux

O sistema operacional de destino para o executável compilado. Atualmente, apenas o sistema operacional Linux é suportado.

--target-arch=value

A arquitetura de destino para o executável compilado. O valor dessa flag pode ser:

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

O comando a seguir demonstra como fazer a cross-compilation de um executável independente para um sistema Linux de 64 bits:

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

Internamente, este comando baixa binários adicionais do Dart SDK e os armazena em cache no diretório ~/.dart.

Aqui está um exemplo de saída com a flag --verbose especificada no 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

Executáveis criados com dart compile exe oferecem suporte a assinatura no macOS e no Windows.

Para saber mais sobre assinatura de código específica de cada plataforma, consulte a documentação dos sistemas operacionais:

• Documentação do SignTool.exe (Windows)
• Guia de Code Signing da Apple

O subcomando exe tem as seguintes limitações conhecidas:

• Não há suporte para dart:mirrors e dart:developer. Para uma lista completa das bibliotecas principais que você pode usar, consulte as tabelas de bibliotecas Multi-platform e Native platform.

• A cross-compilation é suportada, mas o SO de destino é limitado ao Linux. Para saber mais, confira Cross-compilation.

Use módulos AOT para reduzir os requisitos de espaço em disco ao distribuir várias aplicações de linha de comando. O subcomando aot-snapshot produz um arquivo de saída específico para a arquitetura atual na qual você compila sua aplicação.

Por exemplo, se você usar macOS para criar um arquivo .aot, então esse arquivo só poderá ser executado no macOS. O Dart oferece suporte a módulos AOT no Windows, macOS e Linux.

Compile sua aplicação e defina o arquivo de saída:

$ dart compile aot-snapshot bin/myapp.dart

Quando bem-sucedido, este comando gera a seguinte saída:

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

Execute sua aplicação compilada a partir do diretório /bin:

$ dartaotruntime bin/myapp.aot

Para saber mais, consulte a documentação do dartaotruntime.

O suporte à cross-compilation do subcomando aot-snapshot é o mesmo disponível para o subcomando exe. Para mais informações, consulte Executáveis autocontidos (exe).

O subcomando aot-snapshot tem as mesmas limitações do subcomando exe. Para mais informações, consulte Executáveis autocontidos (exe)

Módulos JIT incluem todas as classes analisadas e o código compilado gerado durante uma execução de treinamento de um 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!

Ao executar a partir de um módulo de aplicação, a Dart VM não precisa analisar ou compilar classes e funções que já foram usadas durante a execução de treinamento, então a VM começa a executar o código do usuário mais cedo.

Esses módulos são específicos da arquitetura, ao contrário dos módulos produzidos com o subcomando kernel.

Use o subcomando kernel para empacotar uma aplicação em um único arquivo portável que pode ser executado em todos os sistemas operacionais e arquiteturas de CPU. Um módulo kernel contém uma forma binária da árvore de sintaxe abstrata (Kernel AST) de um programa Dart.

Aqui está um exemplo de criação e execução de um módulo kernel:

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

Embora os módulos kernel tenham um tempo de inicialização menor que o do código Dart, eles podem ter uma inicialização bem mais lenta do que os formatos de saída AOT específicos da arquitetura.

O subcomando js compila código Dart para JavaScript implantável. Por padrão, o compilador gera tanto o arquivo JavaScript (.js) quanto um arquivo de source map (.js.map).

ia-translate: true

O comando dart compile js possui múltiplas opções para personalizar a compilação de código JavaScript.

• Opções básicas
• Opções de caminho e ambiente
• Opções de exibição
• Opções de análise

Opções básicas

Opções comuns incluem:

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

Gera a saída em <file>. Se não for especificado, a saída vai para um arquivo chamado out.js.

--enable-asserts

Habilita a verificação de assertions.

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

Controla otimizações para reduzir o tamanho do arquivo e melhorar o desempenho do código. Para saber mais sobre essas otimizações, execute dart compile js -hv.

• -O0: Desabilita muitas otimizações.

• -O1: Habilita otimizações padrão.

• -O2: Habilita as otimizações de -O1, além de outras (como minificação) que respeitam a semântica da linguagem e são seguras para todos os programas.

• -O3: Habilita as otimizações de -O2, além de omitir verificações implícitas de tipo.

• -O4: Habilita otimizações mais agressivas que -O3, mas com as mesmas premissas.

--no-source-maps

Não gera um arquivo source map. Por padrão, o dart compile js gera automaticamente um arquivo de source map .js.map ao lado do código JavaScript gerado. Use esta flag para desabilitar a geração de source maps. Para considerações de segurança e privacidade ao publicar source maps, veja Deploy para web.

-h ou --help

Exibe ajuda. Para obter informações sobre todas as opções, use -hv.

Opções de caminho e ambiente

Algumas outras opções úteis incluem:

--packages=<path>

Especifica o caminho para o arquivo de configuração de resolução de pacotes. Para mais informações, confira a especificação do arquivo de configuração de pacotes do Dart.

-D<flag>=<value>

Define um par de declaração de ambiente e valor que pode ser acessado com String.fromEnvironment, int.fromEnvironment, bool.fromEnvironment ou bool.hasEnvironment. Para saber mais sobre declarações de ambiente, veja Configurando apps com declarações de ambiente de compilação.

--version

Exibe informações de versão do dart.

Opções de exibição

As seguintes opções ajudam você a controlar a saída do compilador.

--suppress-warnings

Não exibe avisos.

--suppress-hints

Não exibe dicas.

--terse

Emite diagnósticos, sem sugerir como resolver os problemas diagnosticados.

-v ou --verbose

Exibe muitas informações.

Opções de análise

As seguintes opções controlam a análise feita sobre o código Dart.

--fatal-warnings

Trata avisos como erros de compilação.

--enable-diagnostic-colors

Adiciona cores às mensagens de diagnóstico.

--show-package-warnings

Mostra avisos e dicas gerados por pacotes.

--csp

Desabilita a geração dinâmica de código na saída gerada. Isso é necessário para atender às restrições de CSP (veja W3C Content Security Policy.)

--dump-info

Gera um arquivo (com o sufixo .info.json) que contém informações sobre o código gerado. Você pode inspecionar o arquivo gerado com as ferramentas do dart2js_info.

--[no-]deprecated-js-interop

Habilita ou desabilita o suporte à interop JS legada com dart:* e às bibliotecas web (dart:html, dart:indexed_db, dart:js, dart:js_util, dart:svg, dart:web_audio e dart:web_gl), além dos pacotes que as importam (como package:js). Habilitado por padrão (--deprecated-js-interop). Quando você passa a flag --no-deprecated-js-interop, importar qualquer uma dessas bibliotecas resulta em erro de compilação, que mostra os caminhos de import mais curtos até as bibliotecas depreciadas. Além disso, as condições de ambiente dart.library.* delas (como dart.library.html e dart.library.js_util) são avaliadas como false em imports condicionais e em bool.fromEnvironment. Para detalhes, consulte Desabilitar bibliotecas de interop JS legadas.

Por exemplo, para compilar uma aplicação Dart para JavaScript otimizado, execute o seguinte comando:

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

Siga estas práticas para melhorar a inferência de tipos, reduzir o tamanho dos arquivos e melhorar o desempenho do JavaScript:

• Não use Function.apply().
• Não sobrescreva noSuchMethod().
• Evite definir variáveis como null.
• Seja consistente com os tipos dos argumentos que você passa para cada função ou método.

Para saber mais sobre como construir e implantar aplicações JavaScript, confira Web deployment.

O subcomando wasm compila código Dart para um módulo WebAssembly/WasmGC. Por padrão, o compilador gera o módulo .wasm, um arquivo de runtime JavaScript complementar .mjs e um arquivo de source map .wasm.map.

Por exemplo, para compilar uma aplicação web Dart para WebAssembly otimizado:

$ dart compile wasm -O2 -o site/main.wasm web/main.dart

Para detalhes sobre compilar, servir e implantar aplicações Wasm, consulte Compilando para WebAssembly. Para saber sobre considerações de segurança ao implantar source maps, consulte Web deployment.