Document conditional imports #2079
Conversation
3 things that I'd like to clear up before publishing are marked as PENDING
googlebot
added
the
cla: yes
|
cc @lrhn can you give this a review, please? |
| then export `hw_io.dart`. | ||
| * If this code is running in a browser, | ||
| then export `hw_html.dart`. | ||
| * Otherwise, export `hw.dart`. **[PENDING: when would this happen?]** |
There was a problem hiding this comment.
I think the analyzer will import this during development, so that might be where code completion comes from (check if this is true).
Also if one day a platform that supports neither dart:html or dart:io then I guess it would be imported there. Though no such platform currently exist.
| To conditionally import or export, | ||
| you must check for the presence of `dart:*` libraries. | ||
| Here's an example of conditional export code that | ||
| checks for the presence of `dart:io` and `dart:html`: |
There was a problem hiding this comment.
nit: I would perhaps consider testing on dart:js instead of dart:html because I would imagine dart:js is more comon in Flutter for web packages (just a guess).
There was a problem hiding this comment.
I've seen dart:html in the wild, but that's probably pre-flutter web, and I'd love to get a definitive answer on this. @johnpryan?
There was a problem hiding this comment.
It depends on what platform library you actually depend on.
This is library testing, not platform testing—which is why the example is actually not very good. It's not detecting "VM" or "JavaScript", it's detecting the presence of the dart:io library or the dart:html library.
I know of at least one experiment with embedding the VM and a browser engine in the same program, and that platform hae both dart:io and dart:html (not sure if it had dart:js though, since you used Dart instead).
So, if you depend on dart:js then test for dart.library.js, and if you depend on dart:html then test for dart.library.html. That makes your code maximally supported.
In most cases, the feature you need is a DOM feature, not a plain JS feature, so I'd test for dart.library.html.
There was a problem hiding this comment.
What happens if both dart:io & dart:html are supported? Would only the first if take effect, or might you import multiple libraries? (I'd hope it's the former, not the latter.)
| To conditionally import or export, | ||
| you must check for the presence of `dart:*` libraries. | ||
| Here's an example of conditional export code that | ||
| checks for the presence of `dart:io` and `dart:html`: |
There was a problem hiding this comment.
It depends on what platform library you actually depend on.
This is library testing, not platform testing—which is why the example is actually not very good. It's not detecting "VM" or "JavaScript", it's detecting the presence of the dart:io library or the dart:html library.
I know of at least one experiment with embedding the VM and a browser engine in the same program, and that platform hae both dart:io and dart:html (not sure if it had dart:js though, since you used Dart instead).
So, if you depend on dart:js then test for dart.library.js, and if you depend on dart:html then test for dart.library.html. That makes your code maximally supported.
In most cases, the feature you need is a DOM feature, not a plain JS feature, so I'd test for dart.library.html.
|
ptal |
kwalrath
changed the title
|
@lrhn still lgty? |
|
I'm taking that as a yes. :) |
| @@ -0,0 +1,5 @@ | |||
| import 'package:create_libraries/hw_mp.dart'; | |||
|
|
|||
| main() { | |||
There was a problem hiding this comment.
@kwalrath: main() -> void main() (to avoid an analyzer issue)?
There was a problem hiding this comment.
FYI, I added void in a recent PR, matching how we declared the alarm() function. If we've decided that to promote the declaration of main() w/o it's type, I'll revert the change.
I put most of the content in the "Creating library packages" page, not directly in the language tour.
Staged:
https://kw-staging-dartlang-2.firebaseapp.com/guides/language/language-tour#implementing-libraries
https://kw-staging-dartlang-2.firebaseapp.com/guides/libraries/create-library-packages#conditionally-importing-and-exporting-library-files
I'd love some feedback on the most common use cases (e.g. which platforms you'd support, and if there's something else I should show/cover).
Fixes #1569