Document usage

[nex3]

Currently there's very little documentation describing how to use the dev compiler. The usage doc that exists is very sparse and has been marked as out-of-date for three months.

Some information that would be useful:

• How to compile a simple application. In particular, it's not obvious that every source file needs to be provided explicitly.
• How to use package imports.
• What comprises a module—the relationship between the generated JS and the summary.
• How to use a summary when compiling, and the benefit of doing so.
• What the --build-root and --module-root flags do and when they're needed.
• How to embed compiled JS into a web page, especially if the same page needs multiple modules.
• How to choose which library's main method is invoked.
• How to pass a file containing entrypoints (see Allow sources to be provided as a file #614 (comment)).

[nex3]

This is blocking dart-lang/test#414; in particular, we need a documented and stable way of determining the module name and library name to use when running an entrypoint.

[jmesserly]

Possible idea: would it work if we provide a way to specify these on the command line?

[nex3]

That would be enough to unblock test. What UI are you thinking?

[jmesserly]

CC @vsmenon

I can think of a couple of options. For library name, but perhaps after each library file URI, you can specify the desired library name? Needs some kind of separator character :), but something like foo.dart::foo in the input sources list.

Another idea, perhaps we should provide something equivalent to Dart's import -- so you could import a library by a Dart URI. In theory we need something like that anyway for debugging/mirrors. So it would be like

let foo = dart.import("package:foo/foo.dart");

For modules, the idea is this is already specified via the module-root+path to summary. When DDC writes out summary files it puts them next to the JS files, so DDC's structure of the code matches how an ES6 loader would look for things. But, we could do the same trick: -s foo.api.ds::foo_module

[nex3]

I can think of a couple of options. For library name, but perhaps after each library file URI, you can specify the desired library name? Needs some kind of separator character :), but something like foo.dart::foo in the input sources list.

This would work.

Another idea, perhaps we should provide something equivalent to Dart's import -- so you could import a library by a Dart URI. In theory we need something like that anyway for debugging/mirrors. So it would be like

let foo = dart.import("package:foo/foo.dart");

This seems a lot more complex when you're dealing with file: paths. Either you have to encode the absolute paths or you have to have some complex logic for determining what they're relative to.

For modules, the idea is this is already specified via the module-root+path to summary. When DDC writes out summary files it puts them next to the JS files, so DDC's structure of the code matches how an ES6 loader would look for things. But, we could do the same trick: -s foo.api.ds::foo_module

Wouldn't you only need to indicate the name of the module you're actively compiling? Downstream modules could just load it from the summary or whatever. If you only need to name the current module, then all you need is a --module-name parameter.

[vsmenon]

Today, the module name is the relative path of the output js file (minus extension) wrt to the module_root.

Similarly, the library name is the relative path of the input library dart wrt to the library_root with the separator replaced by '__'.

This was setup to work with bazel rules.

[nex3]

Today, the module name is the relative path of the output js file (minus extension) wrt to the module_root.

Relative path or relative URI? If the former, does this mean module names are expected to differ between OSes? If the latter, how does it handle URI-incompatible characters in file paths?

Does it remove a single extension or all extensions? What happens if the input file doesn't have an extension? What if it has an extension but that extension isn't .dart? What if removing the extension creates conflicts?

These sorts of questions are important to get ironed out, especially if multiple disparate tools are going to be re-implementing this logic in order to generate accurate module names.