README.md
1# Frontend Server
2
3Frontend server is simple wrapper around Dart Frontend. It is a Dart application
4that compiles Dart source into Dart Kernel binary (.dill-file).
5Documentation on Dart Kernel (semantic, binary format, etc) can be found here:
6https://github.com/dart-lang/sdk/wiki/Kernel-Documentation.
7
8Frontend server runs in two modes:
9 - immediate mode, where Dart source file name is provided as command line
10 argument;
11 - interactive mode, where communication is happening over stdin/stdout.
12
13## Interactive mode instructions
14
15### Compile/Recompile
16```
17compile <input.dart>
18```
19 Compiles <input.dart> Dart source file with Dart Frontend. Replies with `result` response.
20
21```
22recompile <boundary-key>
23<path/to/updated/file1.dart>
24<path/to/updated/file2.dart>
25...
26<boundary-key>
27```
28 Incrementally recompiles Dart program previously compiled in current session, taking into account
29 changes in the listed files. Replies with `result` response.
30
31 Relative paths should be relative to current working directory for the shell that launched
32 Frontend Server.
33
34### Accept/Reject
35```
36accept
37```
38 Accepts results of incremental compilation, so that on next recompilation request Dart Frontend
39 will not include these recompiled files.
40```
41reject
42```
43 Rejects results of incremental compilation, so that on next recompilation request Dart Frontend
44 will include compilation results from previously rejected recompilation in addition to what it
45 will recompile based on newly changed files.
46 Small technical detail is that Dart Frontend will not recompile files from previously rejected
47 recompilation attempts (unless they were changed since then), it will just include appropriate
48 kernel binaries it kept around from those previously rejected compilation requests.
49
50 One use of `accept` and `reject` instructions is in the context of Dart VM hot-reload. Dart VM can
51 reject user-provided incremental change to what is currently running. It could happen for variety
52 of Dart VM internal reasons. For example, if incremental update changes some `class` to `enum`,
53 such update can not be hot-reloaded by VM at this point, will be rejected.
54
55### Quit
56```
57quit
58```
59 Stops the server.
60
61## Response from the server
62
63```
64result <boundary-key>
65<compiler output>
66<boundary-key> [<output.dill>]
67```
68Response from the Dart Frontend compiler is bracketed by `<boundary-key>` tags. If the compiler
69was able to produce a Dart Kernel file, the name of this file `<output.dill>` is provided too.
70If the compiler encountered unrecoverable errors, there will be no output file name provided.
71
72