[breaking change]: Deprecation and discontinuation of standalone Dart tools

[mit-mit]

Background

Historically the Dart team has offered a number of smaller developer tools for things like formatting code (dartfmt), analyzing code (dartanalyzer), etc. In Dart 2.10 (October 2020) we introduced a new unified Dart developer tool, the dart tool.

Intended change

As we discussed at launch in the blog post, we plan to first deprecate and then discontinue the smaller tools in favor of the new combined tool. The this meta-bug presents an overview of the status of this migration. As this is considered breaking, it will happen in a staged fashion over time, when each individual tool first becoming deprecated in one stable release (here it will still exist but print a warning), and then fully discontinued (here it will no longer be in the SDK).

Historical tool	dart replacement	Deprecation	Discontinuation
stagehand	dart create	2.14	✅ 2.14*
dartfmt	dart format	2.14	✅ 2.15
dart2native	dart compile exe	2.14	✅ 2.15
dart2js	dart compile js	2.17	✅ 2.18
dartdevc	none	2.17	✅ 2.18
dartanalyzer & package:analyzer_cli	dart analyze	2.16	✅ 2.18
dartdoc	dart doc	2.16	✅ 2.17
pub	dart pub	2.15	✅ 2.17

Notes:

• We currently have no plans to deprecate dartaotruntime.
• stagehand will go directly to discontinuation as it's a pub global tool on pub.dev, and not a SDK distributed tool like the rest. This means it can still be invoked (with dart pub global run stagehand) even after it's been discontinued.
• dartdevc will be discontinued as a publicly visible tool. The tool was never intended or supported as a stable command line tool for end users. The underlying binary for this compiler will still be shipped with the SDK to be used by build systems tools (such as bazel, webdev, and flutter_tools). However, it will no longer be exposed to be used by developers directly on the command line.

Rationale

With the new unified tool the existing tools are no longer needed. To reduce maintenance, remove confusion for new users, and to ensure we offer a single high-quality toolset the old commands are being removed.

Should you have any issues with missing functionality in the new dart-based tools, please file an issue.

Migration

To migrate, switch to using the dart tool, and the subcommands listed in the above table.

[jonahwilliams]

I can begin switching the flutter usages of the tools with specified deprecation dates. For some of these, it seems like there is still a significant gap in functionality (analysis server usage with dart analyze, or the various compile options for dart2js). Is there a plan to resolve this before announcing deprecation dates?

[sigmundch]

... significant gap in functionality (... various compile options for dart2js)

I can at least speak for the dart2js side, yes. We will ensure there isn't any gap in our case. It's very likely that we'll even preserve all existing flags, but we'll confirm once the plan is finalized.

[mit-mit]

The items marked as deprecated in 2.14 in the table are considered "feature complete" and we're not aware of any things missing from them.

For dart analyze it's fairly complete, and we'd like to hear more input on what might be missing. We've migrated a bunch of uses of dartanalyzer in various Dart repos already.

[kleinpetr]

what is the replacement for the web-angular which is in now in stagehand?

[aadarshadhakalg]

As angular-dart is also being discontinued, most probably dart create will not include web-angular template. But Is the google team planning to release a separate CLI tool for angular-dart or there are other existing alternatives?

Update: I found one https://pub.dev/packages/ngdart

[mit-mit]

stagehand will continue to work as today; it just won't see any future work -- so that can still be used to create web-angular projects.

[jonahwilliams]

@mit-mit I'm thinking of functionality like the lsp mode that the analysis server supports, unless that snapshot won't be removed.