Skip to main content

dart compile

Command-line tool for compiling Dart source code.

This guide describes how to use the dart compile command to compile a Dart program to a target platform.

Overview

#

Use the dart compile command to compile a Dart program to a target platform. The output—which you specify with a subcommand—can either include a Dart runtime or be a module (also known as a snapshot).

The following example uses the exe subcommand to produce a self-contained executable file (myapp.exe):

dart compile exe bin/myapp.dart

The output is similar to the following:

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

The next example uses the aot-snapshot subcommand to produce an ahead-of-time (AOT) compiled module (myapp.aot):

dart compile aot-snapshot bin/myapp.dart

The output is similar to the following:

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

Use the dartaotruntime command (which provides a Dart runtime) to run the AOT module:

dartaotruntime bin/myapp.aot

To specify the path to the output file, use the -o or --output option:

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

For more options and usage information, run dart compile SUBCOMMAND --help, replacing SUBCOMMAND with a subcommand such as exe or wasm:

dart compile exe --help

Refer to the native_app sample for a simple example of using dart compile to compile a native app, followed by examples of running the app.

Subcommands

#

The following table shows the subcommands of dart compile.

Subcommand Output Description
exe Self-contained executable A standalone, architecture-specific executable file containing the source code compiled to machine code and a small Dart runtime.
aot-snapshot AOT module An architecture-specific file containing the source code compiled to machine code, without a Dart runtime.
jit-snapshot JIT module An architecture-specific file with an intermediate representation of all source code, plus an optimized representation of the source code that executed during a training run of the program. JIT-compiled code can have faster peak performance than AOT code if the training data is good.
kernel Kernel module A portable, intermediate representation of the source code.
js JavaScript A deployable JavaScript file (.js) and source map (.js.map), compiled from the source code.
wasm WebAssembly A WebAssembly module (.wasm), companion JavaScript runtime (.mjs), and source map (.wasm.map).

Types of output

#

The following sections have details about each type of output that dart compile can produce.

Self-contained executables (exe)

#

The exe subcommand produces a standalone executable for Windows, macOS, or Linux. A standalone executable is native machine code that's compiled from the specified Dart file and its dependencies, plus a small Dart runtime that handles type checking and garbage collection.

You can distribute and run the output file like you would any other executable file.

Compile your app and set the output file:

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

When successful, this command outputs the following:

Generated: /tmp/myapp

Run your compiled executable:

/tmp/myapp

Cross-compilation

#

The following table shows which 64-bit host operating systems support cross-compilation to which targets:

64-bit host OS Linux ARM Linux ARM64 Linux RISCV64 Linux x64
Linux done done done done
macOS done done done done
Windows done done done done

To use cross-compilation, include the following flags:

--target-os=linux

The target operating system for the compiled executable. Cross-compilation supports only Linux as a target operating system.

--target-arch=value

The target architecture for the compiled executable. The value for this flag can be one of the following architectures:

  • arm: 32-bit ARM processor
  • arm64: 64-bit ARM processor
  • riscv64: 64-bit RISC-V (RV64GC) processor
  • x64: x86-64 processor

The following command demonstrates how to cross-compile a standalone executable for a 64-bit Linux system:

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

Internally, this command downloads additional Dart SDK binaries and caches them in the ~/.dart directory.

Here's a sample output with the --verbose flag specified with the command:

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

Signing

#

Executables created with dart compile exe support signing on macOS and Windows.

To learn more about platform-specific code signing, refer to the platform documentation for those operating systems:

Known limitations

#

The exe subcommand has the following known limitations:

  • No support for dart:mirrors and dart:developer. For a complete list of the core libraries you can use, refer to the Multi-platform and Native platform library tables.

  • Cross-compilation is supported, but the target OS is limited to Linux. To learn more, refer to Cross-compilation.

AOT modules (aot-snapshot)

#

Use AOT modules to reduce disk space requirements when distributing multiple command-line apps. The aot-snapshot subcommand produces an output file specific to the current architecture on which you compile your app.

For example, if you use macOS to create a .aot file, then that file can run on macOS only. Dart supports AOT modules on Windows, macOS, and Linux.

Compile your app and set the output file:

dart compile aot-snapshot bin/myapp.dart

When successful, this command outputs the following:

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

Run your compiled app from your project root directory:

dartaotruntime bin/myapp.aot

To learn more, refer to the dartaotruntime documentation.

Cross-compilation

#

Cross-compilation support for the aot-snapshot subcommand is the same as what's available for the exe subcommand. For more information, refer to Self-contained executables (exe).

Known limitations

#

The aot-snapshot subcommand has the same limitations as the exe subcommand. For more information, refer to Self-contained executables (exe).

JIT modules (jit-snapshot)

#

JIT modules include all the parsed classes and compiled code that's generated during a training run of a program.

Compile a JIT module from a training run:

dart compile jit-snapshot bin/myapp.dart

The output is similar to the following:

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

Run the compiled JIT module:

dart run bin/myapp.jit

The output is similar to the following:

Hello world!

When running from an application module, the Dart VM doesn't need to parse or compile classes and functions that were already used during the training run, so the VM starts running your code sooner.

These modules are architecture-specific, unlike modules produced by using the kernel subcommand.

Portable modules (kernel)

#

Use the kernel subcommand to package an app into a single, portable file that runs on all operating systems and CPU architectures. A kernel module contains a binary form of the abstract syntax tree (Kernel AST) for a Dart program.

Create a kernel module:

dart compile kernel bin/myapp.dart

The output is similar to the following:

Compiling bin/myapp.dart to kernel file bin/myapp.dill.

Run the compiled kernel module:

dart run bin/myapp.dill

Although kernel modules have reduced startup time compared to Dart code, they can have much slower startup than architecture-specific AOT output formats.

JavaScript (js)

#

The js subcommand compiles Dart code to deployable JavaScript. By default, the compiler outputs both the JavaScript file (.js) and a source map file (.js.map).

Options

#

The dart compile js command has multiple options to customize javascript code compilation.

Basic options

Common options include:

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

Generates the output into <file>. If not specified, the output goes in a file named out.js.

--enable-asserts

Enables assertion checking.

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

Controls optimizations to reduce file size and improve code performance. To learn more about these optimizations, run dart compile js -hv.

  • -O0: Disables many optimizations.

  • -O1: Enables default optimizations.

  • -O2: Enables -O1 optimizations, plus additional ones (such as minification) that respect the language semantics and are safe for all programs.

  • -O3: Enables -O2 optimizations, plus omits implicit type checks.

  • -O4: Enables more aggressive optimizations than -O3, but with the same assumptions.

--no-source-maps

Don't generate a source map file. By default, dart compile js automatically outputs a .js.map source map file alongside the generated JavaScript code. Use this flag to disable source map generation. For security and privacy considerations when deploying source maps, see Web deployment.

-h or --help

Displays help. To get information about all options, use -hv.

Path and environment options

Some other handy options include:

--packages=<path>

Specifies the path to the package resolution configuration file. For more information, check out the Dart package configuration file specification.

-D<flag>=<value>

Defines an environment declaration and value pair which can be accessed with String.fromEnvironment, int.fromEnvironment, bool.fromEnvironment, or bool.hasEnvironment. To learn more about environment declarations, see Configuring apps with compilation environment declarations.

--version

Displays version information for dart.

Display options

The following options help you control the compiler output.

--suppress-warnings

Doesn't display warnings.

--suppress-hints

Doesn't display hints.

--terse

Emits diagnostics, without suggesting how to get rid of the diagnosed problems.

-v or --verbose

Displays lots of information.

Analysis options

The following options control the analysis performed on Dart code.

--fatal-warnings

Treat warnings as compilation errors.

--enable-diagnostic-colors

Adds colors to diagnostic messages.

--show-package-warnings

Shows warnings and hints generated from packages.

--csp

Disables dynamic generation of code in the generated output. This is necessary to satisfy CSP restrictions (see W3C Content Security Policy.)

--dump-info

Generates a file (with the suffix .info.json) that contains information about the generated code. You can inspect the generated file with tools in dart2js_info.

--[no-]deprecated-js-interop

Enables or disables support for the deprecated dart:* JS interop and web libraries (dart:html, dart:indexed_db, dart:js, dart:js_util, dart:svg, dart:web_audio, and dart:web_gl), as well as packages that import them (such as package:js). Enabled by default (--deprecated-js-interop). When you pass the --no-deprecated-js-interop flag, importing any of these libraries results in a compile-time error that reports the shortest import paths to the deprecated libraries. In addition, their dart.library.* environment conditions (such as dart.library.html and dart.library.js_util) evaluate to false in conditional imports and bool.fromEnvironment. For details, refer to Disallow deprecated JS interop libraries.

Compile a web app

#

For example, to compile a Dart application to optimized JavaScript, run the following command:

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

Improve production web compilation

#

Follow these practices to improve type inference, reduce file size, and improve JavaScript performance:

  • Don't use Function.apply().
  • Don't override noSuchMethod().
  • Avoid setting variables to null.
  • Be consistent with the types of arguments you pass into each function or method.

To learn more about building and deploying JavaScript applications, refer to Web deployment.

WebAssembly (wasm)

#

The wasm subcommand compiles Dart code ahead-of-time (AOT) to a WebAssembly (WasmGC) module (dart2wasm). By default, the compiler generates the .wasm module, a companion .mjs JavaScript runtime file, and a .wasm.map source map file.

For example, run the following command to compile a Dart web application to optimized WebAssembly:

dart compile wasm -O2 -o site/main.wasm web/main.dart
OptionDescription
-O0 to -O4 Controls compiler optimizations for code size and execution speed ( -O1 is the default, -O2 adds minification and omits error details, -O3 omits implicit type checks, and -O4 omits index bounds checks).
--minify Minifies runtime names (such as <obj>.runtimeType.toString() ). Enabled by default at -O2 and higher.
--[no-]strip-wasm Strips the static symbol name section from the output .wasm binary (enabled by default). Pass --no-strip-wasm for readable function names when profiling.
--[no-]source-maps Generates a .wasm.map source map file alongside the .wasm output (enabled by default).
--[no-]enable-deferred-loading Splits deferred as imports into separate .wasm modules loaded on demand.
--standalone Emits a standalone .wasm binary without JS runtime dependencies (disallows dart:js_interop and --enable-deferred-loading ).
-D<key>=<value> or --define=<key>=<value> Defines compile-time environment declarations for String.fromEnvironment , bool.fromEnvironment , and int.fromEnvironment .

For details on compiling, optimizing, and loading Wasm applications, refer to WebAssembly compilation. To learn about serving .wasm assets and managing source maps in production, refer to Web deployment.