Update JS compiler content for v2.18 #4193

atsansone · 2022-08-25T19:45:52Z

Removed mentions of `dart2js` and `dartdevc`

Added production debugging section from `dart2js`

debugging

Removed all content

src/_guides/language/language-tour.md

mit-mit · 2022-08-26T09:19:30Z

src/tools/dart-compile.md

 Generated: /tmp/myapp
+```
+
+To run your compiled app, change to the `/tmp` directory and run.


I think this would be simpler if it was just /tmp/myapp without having to change directory.

Not a problem here.

Agree with mit.

mit-mit · 2022-08-26T09:27:15Z

src/tools/dartdevc.md

+  Dart 2.18 removes the `dartdevc` command-line tool from the Dart
+  package, but retains the dartdevc compiler.
+
+  Use [`dart compile js`](/tools/dart-compile#js) to compile Dart code


I don't think this is true. compile js will produce non-debuggable JS. I think maybe we need to point to webdev instead, @sigmundch ?

It actually looks like the removed content below might all still work, and just need to be retained?

This all falls under the dartdevc command. I can excise some parts and put them elsewhere, like webdev. I thought you were looking for removing anything other than dart compile js, so I tried to stay in that lane. Can you indicate which lines I should move? All of them, changing dartdevc to webdev serve?

My recommendation here is that we are not downplaying one command over others. Both commands are serving different purposes and each is valid for the journey the developer is at the moment (I provided additional details in the planning doc if that helps).

That means that we'd keep both references to web development and web production compilers, but change the sample commands. If a command used dart2js, we turn it into dart compile js, if a command used dartdevc, we turn it into webdev serve.

In the past, calling dartdevc directly was not recommended anyways, and not something I expect we had said to do in the documentation (we used the term to refer to the development compiler, but I'd be surprised if we had examples to show people how to call it directly). So I expect for the most part we used webdev serve to describe those use cases, and we can simply preserve good chunks of the old documentation.

Correct - in this case we'd point them at webdev serve

There is still a page for webdev below, so rather than retaining the content of the dartdevc.md file, I'd recommend selecting the relevant pieces to preserve that make sense to show in the context of webdev. From looking at the contents on this file, thought, I don't think there is much I'd keep (all content about module format, etc, are not really that relevant to our developers).

Is it a requirement that we keep old pages around? or is it OK to delete them altogether?

After looking at this more closely, I'm no longer sure I see the value in keeping around both the dartdevc.md and the dart2js.md pages. So I'd be inclined in deleting them both. If we have to keep them, then I would suggest to trim them down further. For example, by deleting anything that is describing the compilers beyond production/development (e.g. I'd suggest deletion the whole explanation of modules and AMD).

One suggestion:

"Version note: Since Dart 2.18 the dart2js web production compiler is only available from dart compile js(link)", and

"Version note: Since Dart 2.18 the dartdevc web development compiler is only available from webdev serve(link)."

Another suggestion (I slightly prefer this one):

"dart2js is Dart's web production compiler. Version note: Since Dart 2.18 the dart2js compiler can only be invoked from dart compile js. It is also used internally by deployment tools like webdev build", and

"dartdevc is Dart's web development compiler. Version note: Since Dart 2.18 the dartdevc compiler cannot be invoked directly, but it is used internally by development tools like webdev serve."

sigmundch · 2022-08-26T16:08:44Z

src/_guides/language/language-tour.md

-  **Only dart2js supports deferred loading.**
-  Flutter, the Dart VM, and dartdevc don't support deferred loading.
-  For more information, see
+  **Only `dart compile js` supports deferred loading.**


FYI - I believe some support for deferred loading has been added to the VM and we are working towards adding it to the dartdevc workflow (webdev). That's tangential to this change, so I wouldn't change anything here, just wanted to give you a heads up :)

sigmundch · 2022-08-26T16:09:49Z

src/_guides/whats-new.md

+
+In addition to bug fixes and incremental improvements,
+we made the following changes to this site:
+


is your intent to also add here some bullet points about these recent changes?

I guess this was accidentally included as that is being handled in #4195

sigmundch · 2022-08-26T16:11:55Z

src/faq.md

-The _development_ compiler ([dartdevc][]) supports only Chrome.
-You _might_ be able to use other modern browsers
+The _development_ web compiler supports Chrome only.
+You _might_ be able to use other modern browsers based on Chromium


I'd recommend reverting this line change - only Edge is based on chromium, FF and Safari are not.

sigmundch · 2022-08-26T16:12:38Z

src/faq.md

-The _development_ compiler ([dartdevc][]) supports only Chrome.
-You _might_ be able to use other modern browsers
+The _development_ web compiler supports Chrome only.
+You _might_ be able to use other modern browsers based on Chromium
 (Chromium Edge, Firefox, and Safari).


Consider removing there "Chromium", since now the default is that Edge is a chromium based browser?

sigmundch · 2022-08-26T16:40:40Z

src/tools/dartdevc.md

+  Dart 2.18 removes the `dartdevc` command-line tool from the Dart
+  package, but retains the dartdevc compiler.
+
+  Use [`dart compile js`](/tools/dart-compile#js) to compile Dart code


My recommendation here is that we are not downplaying one command over others. Both commands are serving different purposes and each is valid for the journey the developer is at the moment (I provided additional details in the planning doc if that helps).

That means that we'd keep both references to web development and web production compilers, but change the sample commands. If a command used dart2js, we turn it into dart compile js, if a command used dartdevc, we turn it into webdev serve.

In the past, calling dartdevc directly was not recommended anyways, and not something I expect we had said to do in the documentation (we used the term to refer to the development compiler, but I'd be surprised if we had examples to show people how to call it directly). So I expect for the most part we used webdev serve to describe those use cases, and we can simply preserve good chunks of the old documentation.

sigmundch · 2022-08-26T16:45:01Z

src/faq.md

@@ -373,34 +370,18 @@ For example, the `dart:io` library
 provides access to operating system files and directories with APIs not
 available to the browser.

-### Q. Why does Dart have two JavaScript compilers, dartdevc and dart2js?


I'd still preserve this Q. Maybe instead of "why two compilers", ask "why does Dart have two ways to compile to JavaScript"

In the paragraph below we can however remove the references to the actual compiler names. For example:

Each developer journey has different requirements, so Dart generates JavaScript differently
depending on what you need to do. You don't usually have to worry
about which compiler you're using, because the [webdev][] tool
chooses the right compiler for your use case. When you're developing your app,
webdev chooses a development web compiler, which is modular and supports
incremental compilation so you can quickly see the results of your edits.
When you're building your app for deployment, webdev chooses the web
production compiler (same as dart compile js) which uses techniques such
as tree shaking to produce optimized code.

sigmundch · 2022-08-26T16:46:20Z

src/faq.md


 We don't claim that all Dart code will run faster
 than handwritten JavaScript, when compiled to JavaScript,
 but we're working to make the common cases fast.

-### Q. How can I write Dart code that compiles to performant JavaScript?


This is an important reference, so I would prefer not to remove it.

sigmundch · 2022-08-26T16:48:36Z

src/null-safety/faq.md

@@ -173,7 +173,7 @@ The assert will be unnecessary when everything is fully migrated, but for now it
 ## How should I migrate a runtime null check that now shows as unnecessary?

 An explicit runtime null check, for example `if (arg == null) throw
-ArgumentError(...)`, will be flagged as an unnecessary comparison if you make
+ArgumentError(...)`, will be optionged as an unnecessary comparison if you make


nit: undo edit?

sigmundch · 2022-08-26T16:50:54Z

src/null-safety/faq.md

@@ -319,72 +319,75 @@ and situations where a null value is really expected. So the tool tells you what
 it knows ("it looks like this condition will always be false!") and lets you
 decide what to do.

-## What should I know about dart2js and null safety?
+## What should I know about compiling and null safety?


compiling here is too general (since that includes compilation we do for AOT, and other non-web work).

I'd either use dart compile js or "web production compiles" here.

sigmundch · 2022-08-26T17:02:26Z

src/null-safety/faq.md

-For a long time, the dart2js compiler has had optimizations specifically
-targeting null values and null checks. Because of that, null safety is not
-expected to affect much the output of the compiler.
+The compiler optimizes null values and null checks. So null safety


I think there is some missing pieces in this paragraph that it's worth adding. I realize now that when I first wrote this I didn't word this properly to really convey what I was trying to say, so while your edits make sense looking at this with fresh eyes, I feel that some of the nuance that I was trying to convey here gets lost in the process.

To provide additional context. Developers know that null safety bring many benefits. One such benefit is that it will reduce code-size and improve performance of apps compiled natively (e.g. flutter and AOT targets). Many developers believe that the same benefits will come to JavaScript apps, but in reality the benefits will be much smaller. This Q/A was added because we wanted to set expectations appropriately.

My goal with the first sentence "For a long time ..." was to provide the reason behind this. That is, while our compiler learns from null-safety and it makes the compiler job easier, it's just that in the past there were many optimizations added to the production web compiler to specifically recover the cost of null checks, and as a result the benefits of null safety are not as easily observable when looking at the output of the compiler.

There is probably a better way to convey all of this :). I know this is tangential to your edits, so I'd be fine keeping the original wording for now.

sigmundch · 2022-08-26T17:21:32Z

src/overview.md

-  a production time compiler (dart2js).
-  Both compilers translate Dart into JavaScript.
+  Dart can compile for debugging or production.
+  Its web compiler translates Dart into JavaScript.


Technically there are 2 ocmpilers though... another thought here is to keep the original wording, but remove the words in parenthesis from the original sentence?

I made a different update. Let me know what you think.

How about "Its web compilers translate Dart into JavaScript" (plural compilers vs singluar compiler?)

Alternatively, combining both sentences:
Web platform: For apps targeting the web, Dart can compile to JavaScript, both for development and production purposes.

sigmundch · 2022-08-26T17:28:45Z

src/tools/dart-compile.md

+  The [`webdev build`][] command, by default,
+  also produces minified, deployable JavaScript.
+  The [`webdev serve`][] command, by default,
+  produces JavaScript modules to compile web apps


nit: delete "to compile web apps" ?

sigmundch · 2022-08-26T17:33:23Z

src/_includes/tools/dart-compile-js-options.md

+    are safe for all programs.
+    {{site.alert.note}}
+      With `-O2`, string representations of types are no longer the same as
+      those in the Dart VM and when compiled with [dartdevc][].


note: one more reference to dartdevc to remove here.

sigmundch · 2022-08-26T17:46:20Z

src/tools/dartdevc.md

+  Dart 2.18 removes the `dartdevc` command-line tool from the Dart
+  package, but retains the dartdevc compiler.
+
+  Use [`dart compile js`](/tools/dart-compile#js) to compile Dart code


Correct - in this case we'd point them at webdev serve

There is still a page for webdev below, so rather than retaining the content of the dartdevc.md file, I'd recommend selecting the relevant pieces to preserve that make sense to show in the context of webdev. From looking at the contents on this file, thought, I don't think there is much I'd keep (all content about module format, etc, are not really that relevant to our developers).

sigmundch · 2022-08-26T17:48:40Z

src/web/deployment.md

-as described in the [build_web_compilers page.][build_web_compilers]
+[Use the `webdev build` command][build] to create a deployable version
+of your app. This command converts your code to JavaScript and saves
+the result as `build/web/main.dart.js`.


I agree with most of the deletions here, but it may be worth including also a link to the dart2js options (I wouldn't document them individually here, but refer to the fact that under the hood webdev build invokes dart compile js, so all options available there can also be used to configure a webdev build.

johnpryan · 2022-08-26T20:18:49Z

src/_guides/whats-new.md

+## August 30, 2022: 2.18 release
+
+This section lists notable changes made from May 12, 2022,
+through August 30, 2022.
+For details about the 2.18 release,
+see [Dart 2.18: ][], and the [change log][https://github.com/dart-lang/sdk/blob/main/CHANGELOG.md#2180].
+
+In addition to bug fixes and incremental improvements,
+we made the following changes to this site:
+
+


Suggested change

## August 30, 2022: 2.18 release

This section lists notable changes made from May 12, 2022,

through August 30, 2022.

For details about the 2.18 release,

see [Dart 2.18: ][], and the [change log][https://github.com/dart-lang/sdk/blob/main/CHANGELOG.md#2180].

In addition to bug fixes and incremental improvements,

we made the following changes to this site:

johnpryan · 2022-08-26T20:21:46Z

src/_includes/known-issues/compile-ki.md

@@ -0,0 +1,20 @@
+No cross-compilation support ([issue 28617][])


Did you commit this by accident? It seems unrelated to this change

I yanked out this block from the dart compile file to cover exe and aot-snapshot more cleanly. It is unrelated. Apologies for the extra change.

src/_includes/tools/dart-compile-js-options.md

src/_includes/tools/debug-prod-js-code.md

johnpryan · 2022-08-26T21:21:37Z

src/faq.md

+The mapping is trivial: `Float32List` becomes a `Float32Array`.
+One exception exists: the production web compiler does not support
+64-bit integers: `Int64List` or `Uint64List`. Compiling Dart code with
+either of those lists results in a runtime exception.


Just FYI, semantic line breaks like these are a convention the Dart and Flutter sites often use

Just learned what this is. Great point. I'll fix some here and others later.

johnpryan · 2022-08-26T21:22:50Z

src/null-safety/faq.md

+
+You must include this check if the program is a mixed-version one.
+Until everything is fully migrated and the code switches to running
+with sound null safety, `arg` might be set to `null`.


This is unrelated to js compilation, not sure if this was committed by accident

This was to clean up the language and format around this check. It's the same content as what was there originally.

src/tools/index.md

src/tools/webdev.md

sigmundch

Overall the changes look great, thanks @atsansone!

I defer to the proper editors here to give the final stamp of approval 😊

sigmundch · 2022-08-26T23:31:24Z

src/tools/index.md

-: The Dart dev compiler, a modular Dart-to-JavaScript compiler.
-  IDEs and the `webdev` CLI use dartdevc when running a development server.
-
+: A CLI to build and serve Dart web apps.


Should we consider adding back a bullet point equivalent to dart2js (maybe it would be dart compile js instead?).

It seems these were the primary links we had to steer readers towards the more detailed articles about how to develop and deploy apps to JavaScript, so without those, this index page feels incomplete.

Also worth nothing something for a follow up (clearly out of scope for this change): it's strange that have a couple workflow articles like web/deployment and web/debugging, but no article on web/development. It would be be consistent and have an article per user journey. My guess the reason is that it overlaps entirely with the content of the webdev.md article, so it would require a bit of editing to figure out the right organization of that content.

mit-mit · 2022-08-29T07:50:26Z

@atsansone is this ready for a last review? If so, could you please stage it somewhere? I'm having a bit of trouble visualizing how the pages end up linking together from just the source.

atsansone · 2022-08-29T16:28:11Z

@mit-mit : The links to the staged pages are in the description at the top of this PR.

kevmoo · 2022-08-29T19:26:05Z

src/_includes/tools/dart-compile-js-options.md

+  [Dart Package Configuration File.][]
+
+`-D<flag>=<value>`
+: Defines an environment variable.


We have to have a doc on this that can be linked to.

I'm annoyed this page https://api.dart.dev/stable/2.18.0/dart-core/int/int.fromEnvironment.html – and others don't link to something like that!

atsansone

Made corrections per @johnpryan .

atsansone · 2022-08-29T19:19:15Z

src/_includes/known-issues/compile-ki.md

@@ -0,0 +1,20 @@
+No cross-compilation support ([issue 28617][])


I yanked out this block from the dart compile file to cover exe and aot-snapshot more cleanly. It is unrelated. Apologies for the extra change.

atsansone · 2022-08-29T19:27:14Z

src/faq.md

+The mapping is trivial: `Float32List` becomes a `Float32Array`.
+One exception exists: the production web compiler does not support
+64-bit integers: `Int64List` or `Uint64List`. Compiling Dart code with
+either of those lists results in a runtime exception.


Just learned what this is. Great point. I'll fix some here and others later.

atsansone · 2022-08-29T19:29:58Z

src/null-safety/faq.md

+
+You must include this check if the program is a mixed-version one.
+Until everything is fully migrated and the code switches to running
+with sound null safety, `arg` might be set to `null`.


This was to clean up the language and format around this check. It's the same content as what was there originally.

atsansone · 2022-08-29T19:35:24Z

src/tools/index.md

-: The Dart dev compiler, a modular Dart-to-JavaScript compiler.
-  IDEs and the `webdev` CLI use dartdevc when running a development server.
-
+: A CLI to build and serve Dart web apps.


Suggested change

: A CLI to build and serve Dart web apps.

: A CLI to [build](/tools/webdev#build) and [serve](/tools/webdev#serve) Dart JavaScript apps.

mit-mit · 2022-08-30T08:56:08Z

src/_guides/language/language-tour.md

@@ -2470,9 +2470,9 @@ When exactly do assertions work?
 That depends on the tools and framework you're using:

 * Flutter enables assertions in [debug mode.][Flutter debug mode]
-* Development-only tools such as [dartdevc][]
+* Development-only tools such as [`webdev serve`][]


This link and the compile js one below don't render correctly. I think you are missing definitions of them.

mit-mit

Just one more comment (left above)

johnpryan · 2022-08-30T16:44:42Z

src/_includes/tools/dart-compile-js-options.md

@@ -0,0 +1,113 @@
+#### Options {#prod-compile-options}


includes are typically not used for sections like this. This can make things harder to maintain (the heading type might change depending on the context where it's included.) IMO it's better to just inline things and use includes for banners and other smaller things.

@mit-mit

Updated two other files Fixed dartdevc conflict Updated per @mit-mit and @sigmundch reviews replaced 'web compiler' with 'JavaScript' compiler Apply suggestions from @johnpryan code review Co-authored-by: John Ryan <ryjohn@google.com> Updated per @kevmoo review Updated missing links per @mit-mit Updated Dockerfile

* 2.18 section in evolution.md, added more to what's new (incomplete) * What's new: added 2.18 section with link to change log. Language evolution: added 2.18 section moving commits to new branch * What's new: added 2.18 section with link to change log. Language evolution: added 2.18 section * whats-new.md added 2.18 changes in docs (and to-be-changed pages), finalized evolution.md summary for 2.18 language changes * changed inference link in evolution.md to point to the Type argument inference section specifically on the Type inference page * adjusted .packages workaround pointer * adjusted to reflect #4193 * remove mention of async in what's new, no changes * incorporate style reviews * Apply suggestions from code review Co-authored-by: Parker Lougheed <parlough@gmail.com> * added more new content * semantic line breaks * review * review * change wording Co-authored-by: Parker Lougheed <parlough@gmail.com>

atsansone force-pushed the remove-obsolete branch 7 times, most recently from dc48ceb to 3f88f00 Compare August 26, 2022 04:08

atsansone requested review from parlough, mit-mit and johnpryan August 26, 2022 04:23

mit-mit requested a review from sigmundch August 26, 2022 09:14

mit-mit requested changes Aug 26, 2022

View reviewed changes

sigmundch reviewed Aug 26, 2022

View reviewed changes

johnpryan reviewed Aug 26, 2022

View reviewed changes

sigmundch reviewed Aug 26, 2022

View reviewed changes

MaryaBelanger mentioned this pull request Aug 29, 2022

2.18 What's new and Language evolution pages #4195

Merged

14 tasks

atsansone force-pushed the remove-obsolete branch from aa27b1a to 30b6d15 Compare August 29, 2022 18:26

MaryaBelanger added a commit to MaryaBelanger/site-www that referenced this pull request Aug 29, 2022

adjusted to reflect dart-lang#4193

6250feb

kevmoo reviewed Aug 29, 2022

View reviewed changes

atsansone commented Aug 29, 2022

View reviewed changes

mit-mit reviewed Aug 30, 2022

View reviewed changes

mit-mit approved these changes Aug 30, 2022

View reviewed changes

atsansone force-pushed the remove-obsolete branch 3 times, most recently from 628d5c2 to 4c509ef Compare August 30, 2022 16:42

kevmoo approved these changes Aug 30, 2022

View reviewed changes

atsansone force-pushed the remove-obsolete branch from 4c509ef to 9fdb07d Compare August 30, 2022 16:49

atsansone changed the base branch from main to v2.18 August 30, 2022 16:50

johnpryan reviewed Aug 30, 2022

View reviewed changes

johnpryan approved these changes Aug 30, 2022

View reviewed changes

atsansone force-pushed the remove-obsolete branch from 9fdb07d to a829540 Compare August 30, 2022 16:52

atsansone force-pushed the remove-obsolete branch from a829540 to a52123b Compare August 30, 2022 16:53

atsansone merged commit 5a3e50e into dart-lang:v2.18 Aug 30, 2022

atsansone mentioned this pull request Aug 31, 2022

Consolidate and organizing web tooling and processes documentation #4013

Closed


		In addition to bug fixes and incremental improvements,
		we made the following changes to this site:

		@@ -0,0 +1,20 @@
		No cross-compilation support ([issue 28617][])

	: A CLI to build and serve Dart web apps.
	: A CLI to [build](/tools/webdev#build) and [serve](/tools/webdev#serve) Dart JavaScript apps.

Update JS compiler content for v2.18 #4193

Update JS compiler content for v2.18 #4193

Conversation

atsansone commented Aug 25, 2022 • edited Loading

Removed mentions of dart2js and dartdevc

Added production debugging section from dart2js

Removed all content

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sigmundch left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mit-mit commented Aug 29, 2022

atsansone commented Aug 29, 2022

Choose a reason for hiding this comment

atsansone left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mit-mit Aug 30, 2022 • edited Loading

Choose a reason for hiding this comment

mit-mit left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

atsansone commented Aug 25, 2022 •

edited

Loading

Removed mentions of `dart2js` and `dartdevc`

Added production debugging section from `dart2js`

mit-mit Aug 30, 2022 •

edited

Loading