mirror of
https://github.com/dart-lang/sdk
synced 2024-09-05 00:13:50 +00:00
[ddc] update documentation
Change-Id: I5d3caaffca378584cd2a4488889c84386777a218 Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/229302 Reviewed-by: Nicholas Shahan <nshahan@google.com>
This commit is contained in:
Sigmund Cherem
Commit Bot
parent
43af470c08
commit
6f917703d3
|
|
@ -1,48 +1,81 @@
|
|||
The Dart Dev Compiler (DDC) is a fast, modular compiler that generates modern JavaScript (EcmaScript 6). Its primary use today is to support fast, iterative development of Dart web applications for Chrome and other modern browsers.
|
||||
The Dart Dev Compiler (DDC) is a fast, modular compiler that generates modern
|
||||
JavaScript (EcmaScript 6). Its primary use today is to support fast, iterative
|
||||
development of Dart web applications for Chrome and other modern browsers.
|
||||
|
||||
# Soundness and Restrictions
|
||||
# Support
|
||||
|
||||
DDC is built upon Dart's [sound](https://dart.dev/guides/language/type-system) type system. It only compiles programs that statically type check (i.e., no strong mode errors). It leverages static type checking to generate simpler, readable, and more idiomatic code with fewer runtime checks. In general, DDC is able to provide stronger type guarantees - i.e., *soundness* - than traditional Dart checked mode with significantly fewer runtime checks.
|
||||
DDC is meant to be used by build systems like bazel, `build_web_compilers` and
|
||||
`flutter_tools` under the hood. This compiler is not meant to be used by
|
||||
application developers directly.
|
||||
|
||||
With strong mode, DDC is stricter than traditional Dart production mode or checked mode. Running existing Dart code on DDC will generally require fixing both static and runtime type errors.
|
||||
While at times the code generated by this compiler may be readable, the
|
||||
representation is not meant to be stable and can break with time. For that
|
||||
reason we do not recommend using this compiler to export Dart as a
|
||||
JavaScript module.
|
||||
|
||||
For example, although the following snippet will run in production or checked mode, it will fail to compile with DDC:
|
||||
The recommended approach to compile Dart to JavaScript is to use `dart compile
|
||||
js` instead. If you intend to make a public JavaScript API based on a Dart
|
||||
implementation, such API should be declared explicitly using the standard
|
||||
Dart-JSInterop mechanisms.
|
||||
|
||||
```dart
|
||||
var list = ["hello", "world"]; // Inferred as List<String> in strong mode
|
||||
List<int> list2 = list; // Static type error: incompatible types
|
||||
```
|
||||
# Implementation details
|
||||
|
||||
On the other hand, the following snippet - which tries to mask the type error via casts - will compile with DDC, but fail with a runtime type error.
|
||||
## Modularity
|
||||
|
||||
```dart
|
||||
var list = ["hello", "world"];
|
||||
List<Object> list2 = list; // Generics are covariant. No runtime check required.
|
||||
List<int> list3 = list2; // Implicit runtime downcast triggers error.
|
||||
```
|
||||
Unlike Dart2JS, DDC does not require an entire Dart application. Instead, it
|
||||
operates modularly: it compiles a set of Dart files into a JavaScript module. A
|
||||
DDC compilation step requires a set of input Dart files and a set of *summaries*
|
||||
of dependencies. It performs modular type checking as part of this compilation
|
||||
step, and, if the input type checks, it generates a JavaScript module. The
|
||||
browser (i.e., the JavaScript runtime) loads and links the generated modules
|
||||
when running the application. During development, a compilation step only needs
|
||||
to be rerun if the Dart files or summaries it relies upon change. For most
|
||||
changes, only a very small part of your code will require recompilation.
|
||||
Moreover, modules that are unchanged can be cached in the browser.
|
||||
|
||||
# Modularity
|
||||
## Representation
|
||||
|
||||
DDC provides fast, incremental compilation based on standard JavaScript modules. Unlike Dart2JS, DDC does not require an entire Dart application. Instead, it operates modularly: it compiles a set of Dart files into a JavaScript module. A DDC compilation step requires a set of input Dart files and a set of *summaries* of dependencies. It performs modular type checking as part of this compilation step, and, if the input type checks, it generates a JavaScript module (e.g., [*ES6*](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import), [*AMD*](https://github.com/amdjs/amdjs-api/blob/master/AMD.md), or [*CommonJS*](https://nodejs.org/docs/latest/api/modules.html)). The browser (i.e., the JavaScript runtime) loads and links the generated modules when running the application.
|
||||
During development, a compilation step only needs to be rerun if the Dart files or summaries it relies upon change. For most changes, only a very small part of your code will require recompilation. Moreover, modules that are unchanged can be cached in the browser.
|
||||
Currently Dart classes are mapped to ES6 classes, Dart fields to ES6 properties,
|
||||
Dart getters/setters to ES6 getters/setters, Dart methods to ES6 methods, and so
|
||||
on. Often names are preserved and calling conventions are natural JavaScript
|
||||
ones.
|
||||
|
||||
# EcmaScript 6
|
||||
Some Dart concepts don't map directly:
|
||||
|
||||
DDC attempts to map Dart to idiomatic EcmaScript 6 (ES6) as cleanly as possible, and it relies heavily on static typing to do this. In general, where Dart concepts map directly to ES6, DDC generates code accordingly. For example, Dart classes are mapped to ES6 classes, Dart fields to ES6 properties, Dart getters/setters to ES6 getters/setters, Dart methods to ES6 methods, and so on. In most cases, names are preserved and calling conventions are natural JavaScript ones.
|
||||
- *Libraries*. Multiple Dart libraries are mapped to a single JS module. Each
|
||||
library appears as a first class object in the generated JS module, with its
|
||||
top-level symbols as members. We currently use a heuristic (based upon file
|
||||
paths) to ensure unique naming of generated library objects.
|
||||
|
||||
There are some import caveats where Dart concepts do not map directly:
|
||||
- *Generics*. Dart generics are *reified*, i.e., they are preserved at runtime.
|
||||
Generic classes are mapped to factories that, given one or more type
|
||||
parameters, return an actual ES6 class (e.g., `HashMap$(core.String,
|
||||
core.int)` produces a class that represents a HashMap from strings to ints).
|
||||
Similarly, generic methods are mapped to factories that, given one or more
|
||||
type parameters, return a method.
|
||||
|
||||
- *Libraries*. Multiple Dart libraries are mapped to a single JS module. Each library appears as a first class object in the generated JS module, with its top-level symbols as members. We currently use a heuristic (based upon file paths) to ensure unique naming of generated library objects.
|
||||
- *Generics*. Dart generics are *reified*, i.e., they are preserved at runtime. Generic classes are mapped to factories that, given one or more type parameters, return an actual ES6 class (e.g., `HashMap$(core.String, core.int)` produces a class that represents a HashMap from strings to ints). Similarly, generic methods are mapped to factories that, given one or more type parameters, return a method.
|
||||
- *Dynamic*. DDC supports dynamically typed code (i.e., Dart's `dynamic` type), but it will typically generate less readable and less efficient ES6 output as many type checks must be deferred to runtime. All dynamic operations are invoked via runtime helper code.
|
||||
- *Constructors*. Dart supports multiple, named and factory constructors for a given class with a different initialization order for fields. Today, these are mapped to instance or static methods on the generated ES6 class.
|
||||
- *Private members*. Dart maps private members (e.g., private fields or methods) to ES6 symbols. For example, `a._x` may map to `a[_x]` where `_x` is a symbol only defined in the scope of the generated library.
|
||||
- *Scoping*. Dart scoping rules and reserved words are slightly different than JavaScript. While we try to preserve names wherever possible, in certain cases, we are required to rename.
|
||||
- *Dynamic*. DDC supports dynamically typed code (i.e., Dart's `dynamic` type),
|
||||
but it will typically generate less readable and less efficient ES6 output as
|
||||
many type checks must be deferred to runtime. All dynamic operations are
|
||||
invoked via runtime helper code.
|
||||
|
||||
In general, the current conventions (i.e., the Application Binary Interface or ABI in compiler terminology) should not be considered stable. We reserve the right to change these in the future.
|
||||
- *Constructors*. Dart supports multiple, named and factory constructors for a
|
||||
given class with a different initialization order for fields. Today, these
|
||||
are mapped to instance or static methods on the generated ES6 class.
|
||||
|
||||
- *Private members*. Dart maps private members (e.g., private fields or
|
||||
methods) to ES6 symbols. For example, `a._x` may map to `a[_x]` where `_x` is
|
||||
a symbol only defined in the scope of the generated library.
|
||||
|
||||
- *Scoping*. Dart scoping rules and reserved words are slightly different than
|
||||
JavaScript. While we try to preserve names wherever possible, in certain
|
||||
cases, we are required to rename.
|
||||
|
||||
In general, the current conventions (i.e., the Application Binary Interface or
|
||||
ABI in compiler terminology) should not be considered stable. We reserve the
|
||||
right to change these in the future.
|
||||
|
||||
# Browser support
|
||||
|
||||
DDC currently supports Chrome stable (though users have had success running on FireFox and Safari). In the near future, we expect to target all common modern browsers that support ES6. ES6 itself is in active development across all modern browsers, but at advanced stages of support:
|
||||
|
||||
[kangax.github.io/compat-table/es6](https://kangax.github.io/compat-table/es6/).
|
||||
DDC currently supports Chrome stable (though users have had success running on
|
||||
FireFox and Safari).
|
||||
|
|
|
|||
|
|
@ -1,81 +0,0 @@
|
|||
# Usage
|
||||
|
||||
The [Dart Dev Compiler](README.md) (DDC) is an **experimental** development
|
||||
compiler from Dart to EcmaScript 6. It is still incomplete, under heavy
|
||||
development, and not yet ready for production use.
|
||||
|
||||
With those caveats, we welcome feedback for those experimenting.
|
||||
|
||||
The easiest way to compile and run DDC generated code for now is via NodeJS.
|
||||
The following instructions are in a state of flux -- please expect them to
|
||||
change. If you find issues, please let us know.
|
||||
|
||||
1. Follow the [Getting the Source](https://github.com/dart-lang/sdk/wiki/Building#getting-the-source) steps, and
|
||||
set the environment variable `DDC_PATH` to the `pkg/dev_compiler`
|
||||
subdirectory within wherever you check that out.
|
||||
|
||||
2. Install nodejs v6.0 or later and add it to your path. It can be installed
|
||||
from:
|
||||
|
||||
https://nodejs.org/
|
||||
|
||||
Note, v6 or later is required for harmony / ES6 support.
|
||||
|
||||
3. Define a node path (you can add other directories if you want to separate
|
||||
things out):
|
||||
|
||||
```sh
|
||||
export NODE_PATH=$DDC_PATH/lib/js/common:.
|
||||
```
|
||||
|
||||
4. Compile a test file with a `main` entry point:
|
||||
|
||||
```sh
|
||||
dart $DDC_PATH/bin/dartdevc.dart --modules node -o hello.js hello.dart
|
||||
```
|
||||
|
||||
Note, the `hello.js` built here is not fully linked. It loads the SDK via a `require` call.
|
||||
|
||||
5. Run it via your node built in step 1:
|
||||
|
||||
```sh
|
||||
node -e 'require("hello").hello.main()'
|
||||
```
|
||||
|
||||
6. Compile multiple libraries using summaries. E.g., write a `world.dart` that
|
||||
imports `hello.dart` with it's own `main`. Step 5 above generated a summary
|
||||
(`hello.sum`) for `hello.dart`. Build world:
|
||||
|
||||
```sh
|
||||
dart $DDC_PATH/bin/dartdevc.dart --modules node -s hello.sum -o world.js world.dart
|
||||
```
|
||||
|
||||
Run world just like hello above:
|
||||
|
||||
```sh
|
||||
node -e 'require("world").world.main()'
|
||||
```
|
||||
|
||||
7. Node modules do not run directly on the browser or v8. You can use a tool
|
||||
like `browserify` to build a linked javascript file that can:
|
||||
|
||||
Install:
|
||||
|
||||
```sh
|
||||
sudo npm install -g browserify
|
||||
```
|
||||
|
||||
and run, e.g.,:
|
||||
|
||||
```sh
|
||||
echo 'require("world").world.main()' | browserify -d - > world.dart.js
|
||||
```
|
||||
|
||||
The produced `world.dart.js` fully links all dependencies (`dart_sdk`,
|
||||
`hello`, and `world`) and executes `world.main`. It can be loaded via
|
||||
script tag and run in Chrome (stable or later).
|
||||
|
||||
## Feedback
|
||||
|
||||
Please file issues in our [GitHub issue
|
||||
tracker](https://github.com/dart-lang/sdk/issues).
|
||||
Loading…
Reference in a new issue