[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.

[bkonyi]

The analysis server snapshot won't be going anywhere any time soon since we don't have a replacement for it in the CLI.

[jonahwilliams]

ack, I actually forgot about dartanalyzer, but that one makes more sense 😅

[munificent]

As of this CL, dartfmt is now printing a deprecation notice.

[simolus3]

In the 2.16 release notice, it was mentioned that the standalone dartdoc command is going away in 2.17.

I'm currently using the options --rel-canonical-prefix and --link-to-source-revision when invoking dartdoc. dart doc doesn't appear to accept those options, what's the replacement for them?

[leafpetersen]

As discussed in various meetings, support for analyzing the Dart SDK core libraries doesn't seem to be available with the new command form. From the command line, currently:

xcodebuild/ReleaseX64/dart-sdk/bin/dartanalyzer  --dart-sdk=/Users/leafp/src/dart-repo/sdk/sdk --sdk-warnings  /Users/leafp/src/dart-repo/sdk/sdk/lib/

works but the corresponding dart analyze command does not.

[simolus3]

I'm currently using the options --rel-canonical-prefix and --link-to-source-revision when invoking dartdoc. dart doc doesn't appear to accept those options, what's the replacement for them?

To anyone else also stumbling across this, my solution was to add a dev_dependency on dartdoc and then use dart run dartdoc instead of the more limited dart doc command.

[devoncarew]

@simolus3 - can you open an issue against https://github.com/dart-lang/dartdoc for the dartdoc CLI flags you're missing? And, have you tried configuring dartdoc via the dartdoc_options.yaml file (https://github.com/dart-lang/dartdoc#dartdoc_optionsyaml)? That allows you to tweak more parameters than are available through dart doc.

[jakemac53]

We recently had dart-lang/build#3337 filed on package:build, I was wondering if I can get some clarification here, as currently package:build_web_compilers uses both dart2js and dartdevc, although it runs them by using their snapshot directly.

Will it be safe to continue using these snapshots in perpetuity, or is there a plan to delete them? If we do delete them, how should we invoke DDC?

It does look like for dart2js I can run dart compile js directly, so I will try to make that change and see if anything fails (biggest risk is probably command line options being the same, we allow users to pass arbitrary dart2js options).

[sigmundch]

@jakemac53 - yes, the goal is still to support their use from build_web_compilers. For now we intend to keep the snapshots, but there have been discussions about combining the snapshots into the CLI snapshot sometime in the future (but that's not a short term goal).

To avoid the warning, using dart compile js will work (that will also be safe in the future if dart2js gets merged into the Dart CLI). Alternatively, we can also pass a special flag to the dart2js snapshot to indicate that you are one of the use cases we support (that was our intended design at first).

As for DDC, the snapshot will remain available for foreseeable future. Note that DDC should not give you a warning if you are using the snapshot (only the shell script does today).

[jakemac53]

Thanks, I will go ahead and land the change to use dart compile js and leave the rest as is for now. So you should be unblocked soon to merge the snapshot with the CLI snapshot when you are able, that should probably help sdk size a fair bit :).

[mit-mit]

These discontinuations are now complete, and the current dev channel build (2.18.0-271.0.dev) and upcoming stable build (2.18.0) have just the following in bin:

-rwxr-xr-x@  1 mit  primarygroup  38802064 Jul 12 13:28 dart
-rwxr-xr-x@  1 mit  primarygroup   4050496 Jul 12 13:28 dartaotruntime
drwxr-xr-x@  4 mit  primarygroup       128 Jul 12 13:28 resources
drwxr-xr-x@ 12 mit  primarygroup       384 Jul 12 13:28 snapshots
drwxr-xr-x@  3 mit  primarygroup        96 Jul 12 13:28 utils