dart compile

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

Here’s an example of using the exe subcommand to produce a self-contained executable file (myapp.exe):

$ dart compile exe bin/myapp.dart
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). It then uses the dartaotruntime command (which provides a Dart runtime) to run the AOT module:

$ dart compile aot-snapshot bin/myapp.dart
Generated: /Users/me/myapp/bin/myapp.aot
$ 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:

$ dart compile exe --help

The dart compile command replaces the dart2native, dart2aot, and dart2js commands.

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.

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 returns the following.

Generated: /tmp/myapp

Run your compiled app from the /tmp directory.

$ ./tmp/myapp

Signing

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

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

• Windows SignTool.exe documentation
• Apple Code Signing guide

Known limitations

The exe subcommand has some known limitations:

No cross-compilation support (issue 28617)

The compiler can create machine code only for the operating system on which you’re compiling. To create executables for macOS, Windows, and Linux, you need to run the compiler three times. You can also use a continuous integration (CI) provider that supports all three operating systems.

No support for dart:mirrors and dart:developer

For a complete list of the core libraries you can use, see the All and AOT entries in the table of core Dart libraries.

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.

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

The aot-snapshot subcommand has some known limitations.

No cross-compilation support (issue 28617)

The compiler can create machine code only for the operating system on which you’re compiling. To create executables for macOS, Windows, and Linux, you need to run the compiler three times. You can also use a continuous integration (CI) provider that supports all three operating systems.

No support for dart:mirrors and dart:developer

For a complete list of the core libraries you can use, see the All and AOT entries in the table of core Dart libraries.

To learn more, see the dartaotruntime documentation.

JIT modules (jit-snapshot)

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

$ 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!

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 user code sooner.

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

Portable modules (kernel)

Use the kernel subcommand to package up an app into a single, portable file that can be run 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.

Here’s an example of creating and running a kernel module:

$ dart compile kernel bin/myapp.dart
Compiling bin/myapp.dart to kernel file bin/myapp.dill.
$ 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.

Options

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

• Basic options
• Path and environment options
• Display options
• Analysis options

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

Do not generate a source map file.

-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.

Compiling web app example

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

Improving 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, check out Web deployment.