Skip to content

Document usage #27263

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
vsmenon opened this issue Sep 6, 2016 · 8 comments
Closed

Document usage #27263

vsmenon opened this issue Sep 6, 2016 · 8 comments
Labels
dev-compiler-ux type-enhancement A request for a change that isn't a bug web-dev-compiler

Comments

@vsmenon
Copy link
Member

vsmenon commented Sep 6, 2016

From @nex3 on July 28, 2016 1:7

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 dart-archive/dev_compiler#614 (comment)).

Copied from original issue: dart-archive/dev_compiler#613

@vsmenon
Copy link
Member Author

vsmenon commented Sep 6, 2016

From @nex3 on August 2, 2016 17:59

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.

@vsmenon vsmenon added web-dev-compiler dev-compiler-ux P1 A high priority bug; for example, a single project is unusable or has many test failures type-enhancement A request for a change that isn't a bug labels Sep 6, 2016
@vsmenon
Copy link
Member Author

vsmenon commented Sep 6, 2016

From @jmesserly on August 2, 2016 20:17

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

@vsmenon
Copy link
Member Author

vsmenon commented Sep 6, 2016

From @nex3 on August 2, 2016 21:52

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

@vsmenon
Copy link
Member Author

vsmenon commented Sep 6, 2016

From @jmesserly on August 2, 2016 21:59

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

@vsmenon
Copy link
Member Author

vsmenon commented Sep 6, 2016

From @nex3 on August 2, 2016 23:46

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
Copy link
Member Author

vsmenon commented Sep 6, 2016

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.

@vsmenon
Copy link
Member Author

vsmenon commented Sep 6, 2016

From @nex3 on August 2, 2016 23:58

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.

@vsmenon vsmenon removed the P1 A high priority bug; for example, a single project is unusable or has many test failures label Jan 6, 2017
@jmesserly
Copy link

Build root and module root are tracked elsewhere (e.g. #32272) so I think we can close this one out

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
dev-compiler-ux type-enhancement A request for a change that isn't a bug web-dev-compiler
Projects
None yet
Development

No branches or pull requests

2 participants