Add page to explain Dart modes

[polina-c]

Page URL

https://dart.dev/guides/

Page source

https://github.com/dart-lang/site-www/tree/main/src/_guides/index.md

Describe the problem

development mode and productive mode mentioned in this post are important aspects of the dart language, but they are not explained in dart documentation:

https://www.geeksforgeeks.org/assert-statements-in-dart/

Expected fix

No response

Additional context

No response

[parlough]

Could you provide some more context on what documentation you are looking to see. As far as I can tell, the language specification doesn't really cover a "production" or "development" mode, it only specifies that program execution can occur with asserts enabled or disabled.

From a quick look, it seems like we cover that where relevant. We cover enabling asserts and other debugging options/modes in the dart run documentation as well as in discussion about dart compile js. We also talk about asserts, how to enable them, and how production code ignores them in the language tour.

[polina-c]

@a-siva , can you comment?

Is it intention not to explain compilation mode for Dart applications and only explain asserts? How about vm service availability, debuggability and other differences?

[polina-c]

I faced this issue when I wanted to explain leak_tracker availability in different modes for Dart and Flutter. I wanted to reference the modes. I found the modes explanation for Flutter, but not for Dart.

For now I just linked this bug for Dart: https://github.com/dart-lang/leak_tracker/blob/04ad7a9e0b15ea4dac281ddd5522d496429b4fb1/README.md#by-build-mode

[parlough]

Thanks for the clarification!

I guess it's a bit challenging on the Dart side compared to Flutter. Flutter has a standardized platform combined into one tool, so there are standard build modes, but in terms of Dart, each platform and compiler/tool has its own configuration. So there are no standards modes as far as I know, at least like Flutter has with the build modes, and enabling the vm service and debugging looks different depending on the tool.

For the VM, the current documentation of enabling debugging is in dart run and for web it is in Debugging Dart web apps. We also have some shorter documentation about enabling both on the Dart DevTools page.

While we have sort of consolidated a concept for a "development" vs "production" web compiler on the website recently, that is separate from debugging. At least on the site, there does not seem to be a general concept of modes for VM apps, outside of JIT vs AOT and passing in --observe and --enable-asserts or not.

For your case of documenting leak_tracker, until we have a better consolidated picture, perhaps you could document in terms of the tools? Perhaps mentioning dart run --observe for VM apps and webdev serve --debug for web apps (if web apps are supported by leak_tracker).

\cc @mit-mit Is there is a bigger idea of modes or "production" vs "development" we should be documenting for VM apps or all Dart apps in general?

[mit-mit]

I'm a but confused about the term "productive mode". Do you mean "production mode" @polina-c? If so, please update your readme.

We have an overview that introduces those terms for each of native and web here: https://dart.dev/overview#platform

We should probably detail here which are development mode and which are production mode: https://dart.dev/tools/dart-compile

[polina-c]

@mit-mit , I was not sure what term to use. I took 'productive' from the article I linked, because I did not find anything else.

Your link helps a lot. Updated README. Thank you!

Yes, it seems clarification of compilation modes on this page will help: https://dart.dev/tools/dart-compile

[parlough]

Ah, I forgot about that picture, thanks! Might be nice to be a bit more explicit in text so it's easier to search for.

Sounds like we potentially have a good step forward with improvements to the compile page.

[a-siva]

I believe the key concept that @polina-c wants to capture here is that dart compile exe bin/myapp.dart -o /tmp/myapp produces an executable /tmp/myapp which does not have vm service in it.

[polina-c]

if you go to dart sdk folder and run command tools/build.py --help, there will be line:

  --mode [all,debug,release,product], -m [all,debug,release,product]
                        Build variants (comma-separated). (default: debug)

The modes are different from what is explained here; https://dart.dev/tools/dart-compile

This instruction works just for debug and release modes: https://github.com/dart-lang/sdk/blob/main/runtime/tools/heapsnapshot/README.md

The limitation is hard to document well as the modes are not documented: https://github.com/dart-lang/sdk/pull/52114

[polina-c]

@atsansone @mkustermann

[mit-mit]

The instructions for tools/build.py --help are irrelevant to the vast majority of Dart developers who do not ever build the SDK, or run it's python scripts. Terms like "product mode" I believe only make sense to those that work on implementing the SDK. I think they are different for historical reasons.

[polina-c]

@mit-mit , per my understanding, the modes are for applications. And the modes define what features are available for the applications.

@a-siva and @mkustermann , can you comment on this? What should we say in documentation for, for example, NativeRuntime.writeHeapSnapshotToFile?

[a-siva]

@a-siva and @mkustermann , can you comment on this? What should we say in documentation for, for example, NativeRuntime.writeHeapSnapshotToFile?

Maybe the documentation of NativeRuntime.writeHeapSnapshotToFile can state that this function will not work in a self contained dart executable produced using the dart compile exe command. I presume for Flutter apps it is not confusing when we refer to the modes debug, profile and release and state that this functionality will not work for Flutter apps in release mode.

[polina-c]

There are may features like this. For example, leak tracker. Why do not we give names and explain Dart modes in a central place, that can be easily referenced in all other docs?

[mkustermann]

Terms like "product mode" I believe only make sense to those that work on implementing the SDK. I think they are different for historical reasons.

The name "product" does leak into users code via an environment define: Users that want to exclude certain code in production mode (e.g. for dart compile exe) - will guard such code e.g. via if (!const bool.fromEnvironment("dart.vm.product")) { ... }.

Flutter specifically provides a kReleaseMode constant that is implemented using this. So flutter users can use that more appropriate name instead. Though non-Flutter Dart users are currently required to use bool.fromEnvironment("dart.vm.product") directly.

@mit-mit Would it make sense that we expose kReleaseMode as a constant as part of a dart:* library instead?

[atsansone]

@polina-c , @mkustermann , @mit-mit : This is beginning to read like a code change before a documentation change. If that's the case, I can move this back into dart-lang/sdk for resolution. Thoughts?