Site-www: Changes for Dart 2.1

[kwalrath]

2.1 will have the following user-visible features requiring updates to the language tour and elsewhere:

• [x] int-to-double conversion of literals (dart-lang/language#4, #1165; DONE: #1228)
• [x] the mixin keyword (#1086, dart-lang/sdk#34992; DONE: #1228)
• [x] no need to import dart:async just to get Future and Stream)
  
  
  
  • [x] Update library tour (DONE: #1228)
  
  
  • [x] Update normal code samples (DONE: #1228)
  
  
  • [x] Update example on homepage
  
  
  • [x] Update miscellaneous other mentions of dart:async
  
  
• [x] Document dartfix tool (#1229)
• [x] Check/update flags for existing tools (e.g. remove -c/--checked from pub run docs)

We might also want to update /dart-2 to mention these differences. @mit-mit, @JekCharlsonYu, or @chalin, can you think of anything else I'll need to do for 2.1?

We might also want to add a banner announcing 2.1.

[mit-mit]

I believe we are also removing a few flags from the VM (like --strong, but I'm not sure if they are documented today)

[chalin]

Looking at the SDK CHANGELOG I see other possibly relevant user-visible changes:

---

dart:core

• Exported Future and Stream from dart:core.

This means that imports of dart:async that were used solely for accessing Future or Stream will become unnecessary (and I can confirm that this is the case using the latest Dart dev release).

Interestingly the (dev channel) dartanalyzer doesn't (yet) report dart:async as an unused import in such cases, so in that sense it isn't a "breaking" change, but since we can omit such dart:async imports it _is_ user visible.

@munificent: Maybe dart --fix could be enhanced to remove unnecessary dart:async imports?

---

• Added operators &, | and ^ to bool.

Are these non-short-circuiting versions of the boolean connectives? (If so, I'm curious why it was felt that non-short-circuiting versions of the operators were needed. @eernstg?)

---

Pub

• Rename the --checked flag to pub run to --enable-asserts.

In addition to pub run, the flag change was also applied to the dart command, as @mit-mit pointed out. (Maybe the CHANGELOG should also mention this?)

Note: both dart and pub run still accept -c and --checked w/o a deprecation notice. Nit: so technically, the changelog entry isn't correct: the flag wasn't renamed, instead an extra flag was added. Should the changelog be updated? (Eventually, I suppose, a deprecation notice will be issued.)

---

dart2js

• Added -O flag to tune optimization levels. ...

  We recommend to enable optimizations using the -O flag instead of individual flags for each optimization. This is because the -O flag is intended to be stable and continue to work in future versions of dart2js, ... At this time we recommend to test and debug with -O1 and to deploy with -O3.

(Emphasis mine) We mention use of the individual optimization flags on webdev, so any such prose would need to be updated. I'll create a separate issue to track that. (Done https://github.com/dart-lang/site-webdev/issues/1824).

[mit-mit]

Note: both dart and pub run still accept -c and --checked w/o a deprecation notice. Nit: so technically, the changelog entry isn't correct: the flag wasn't renamed, instead an extra flag was added. Should the changelog be updated? (Eventually, I suppose, a deprecation notice will be issued.)

I believe that is about to be removed, see https://github.com/dart-lang/sdk/issues/34468

[natebosch]

technically, the changelog entry isn't correct: the flag wasn't renamed, instead an extra flag was added.

The old flag in pub should be hidden from --help. I intentionally did not remove it entirely so as to not break backwards compatibility.

[kwalrath]

Also document the dartfix tool: https://github.com/dart-lang/sdk/labels/analyzer-dartfix

[kwalrath]

/cc @munificent

[kwalrath]

PR #1255 updates pub run options, removing two obsolete ones and adding their replacement.

Some other pub command pages (deps, downgrade, get, upgrade) are missing some options, but those are less worrisome because they're covered by the command's help. I've put my notes about them (which aren't 2.1-specific) in #1256.

[eernstg]

[why add] non-short-circuiting versions of the boolean connectives

It was an odd omission that we could operate on a bit array of some size (that is, an int) with these operators, but we couldn't operate on a single bit (that is, bool). In particular, not having an xor operator for booleans at all was a bit odd.

Some programming idioms will require non-short-circuit semantics for correctness. E.g., there can be situations where you want the side-effects from both operands even when the first one returns false:

if (cleanupHouse() & cleanupGarden()) {
  sitAndEnjoy();
} else {
  cryForHelp();
}

Also, if we generalize tear-offs to handle additional cases (such as tearing off operators and constructors) then these operators may be convenient to have, because they are regular instance methods (except for the syntactic property of being operators), whereas the short-circuit operators like && and || are special forms whose semantics is defined directly in the language (in particular, you can't tear off such a special form).

[chalin]

Also document the dartfix tool: https://github.com/dart-lang/sdk/labels/analyzer-dartfix

Done via #1254.

[chalin]

Thanks for the explanation Erik!

[kwalrath]

I'm going to close this. ~The one remaining task was to update the homepage example to not import dart:async. That seems like more trouble than it's worth, though, since it isn't exactly wrong and the code is difficult to update. Also, we're likely to reimplement the homepage (and homepage example) fairly soon.~ Patrice has fixed the homepage example in #1303.