Request for feedback: Discontinuing support for dart:mirrors

[mit-mit]

The Dart mirrors core library (dart:mirrors) is currently in a sub-optimal state:

• It is marked "experimental" in the list of core libraries

• It is marked "unstable" in the API docs

• It is unsupported in the Dart web platform

• Is is disabled from use in the Flutter framework (and has been so for years)

We've investigated potentially making mirrors a stable, fully supported offering, however in its current form this has a few large challenges:

1. Dart has powerful "tree shaking" for ensuring we can produce apps with small code sizes. This relies on the ability to detect unused code, which doesn't work if reflection can use any of it dynamically (it essentially makes all code implicitly used).

2. The APIs supported by mirrors are significantly behind the current Dart language, for example they do not support extension methods or null safety.

We believe that one of the core uses of mirrors is to do various forms of code generation and meta-programming. Before we potentially fully discontinue mirrors, we'd like to better understand the desired use cases here so that we could have alternative solutions and migration path ready for current users before we make any changes to dart:mirrors. If you have any such use cases, please leave a comment.

[daniel-v]

To make sure the info gets to you, here is my response to dart-misc mailing list:

I might be reading too much into this but discontinuing dart:mirrors library has some serious consequences that were not mentioned in your mail. The most important is that we'd lose the ability to do runtime reflection at our server-side code. It is an HTTP server that uses mirrors for the most important bits of it. Transitioning away from it is a scary proposal for many reasons.

If anything I'd request to add mirrors to AOT snapshots too, instead of discontinuing, so that we'd get to deploy our code as a single binary with all the benefits and drawbacks it means. But... Let me address the concerns I have:

• There is no proposal as to what would replace it, we need more info what you had in mind.
• If there is no replacement, you'd effectively eliminate some useful features from the language/runtime we actively use. I don't think that's the case; I will assume for the rest of the mail that you are thinking in terms of migration to code generation.
• We enjoy the ability of quick iterations on BE code without having to run builders all the time, which adds a lot of compile time overhead.
• dart:mirrors is easy to learn and test, package:build is most definitely not
• I keep struggling with different build_runner versions on FE code where package:analyzer constraints prevent me from using certain packages together (eg. Angular 5.3 and freezed). This issue does not exist with runtime reflection.
• Builders can be really slow, in some cases I'd prefer the runtime overhead instead of the added minutes of wait time for the builders to complete.

I'm sure you have a list of pros and cons for mirrors vs. code generation too. Having said that, I'm not against the idea completely if there are good enough reasons.
I'd have to bite my lips hard if mirrors were removed today and would have to migrate to pacakge:build but luckily we still have some time.

There have been several precedents where such a change was preceded by preparing users, crafting new tools or giving some extra attention to alternatives. Most recent one is the NNBD tooling to this. I hope it is the case here as well, in which case feedback on why I'm nervous about moving to pacakge:build is warranted here. In my opinion, build and associated packages are in a bad spot right now.

My recent incursions to writing builders were ... trying because:

1. after awhile, I gave up trying to find written documentation for the questions I had, I started digging around in the code - this shows that the there is too little information out there about how to write builders, how it works and how to configure them. Eg. I was surprised to see that build.yaml and build.config.yaml are merged together instead of being taken as an absolute configuration BUT with a huge caveat: builder declarations are ignored from build.config.yaml.
2. the configuration space is very complex and the tools do not aid me rooting out configurations that make no sense. ( ref ) Figuring out what is OK and what is not can only be done through trial and error or by reading the implementation. This is a problem for every user of package:build, not just builder authors.
3. Contributors of package:build stated it is intended for "superusers" ( ref ). Context to it is: I brought up that it is difficult to map how I see code as a developer to how analyzer sees the same code, then write a builder around that mapping. dart:mirrors make it fairly easy. I fear that I would be required to run around in language specifications to figure out what is what for a question which as simple as: What is the first method in this class with an annotation of Route('/')? Example of how complicated it can be just to resolve types here (used by Angular Compiler too).

I've had some steep learning curves over the years. package:build was one of them. The primary reason - which I consider the most important of all - is a conceptual one: Code generation is becoming more and more important piece of the language ecosystem. As such, as a user of the language, my expectation is that such an important piece is well-documented, somewhat fool proof and fairly easily approachable.

I hope that this is the kind of feedback you were looking for to help you make the right decisions.

[mit-mit]

To those downvoting, it would be great if you could also post a comment with what concerns you. As mentioned, we'd like to understand the use cases where you use mirrors today, so that we can investigate if there is an alternate way by which we can support those use cases without mirrors.

[zmeggyesi]

I work with @daniel-v and @gothamgasworks - I can second Daniel's input that removing runtime reflection would impact us quite negatively.

Our product actively uses runtime reflection in server-side Dart code, both in production and in development, and our preference would be to retain the ability to introspect code rather than rely on build-time code generation, both in the interest of development cycle times and ease of understanding of deployed code.

[gothamgasworks]

@daniel-v 's summary is pretty good, I agree with them.

Some things I want to emphasize:

1. Quick iteration, because we don't need to wait for builds (we use kernel snapshots on the production server)
2. No need to develop builder code for every use case that may arise (we encountered quite a couple)
3. Builder code development is a drag, we have to constantly update the code compared to our mirrors code, which we only had to touch once (moving from Dart 1 to 2)

[gothamgasworks]

We use dart:mirrors in:

• Database record class representation
• Data merging tasks (like statistics, or updates coming from external systems)
• Mapping server side business object to client side business objects
• HTTP request routing
• Serialization libraries (object serialization, object factory registration, XML serialization required by some external systems)
• Report generation system

Of course we could work around it with builders, I would just like to be able to not work with the builder/analyzer API, which requires a serious amount of maintenance as opposed to the mirrors API.

[isoos]

The use cases I had in the past month:

• package:appengine uses reflection for entities that are stored in Datastore.
• package:json_rpc_adapter uses reflection for both HTTP-client and HTTP-server JSON-RPC, by taking the abstract class Api { Future<Rs> operation(Rq rq); ...} like API definition and binding it to both.

My wish-list, which would probably make the lack of dart:mirrors bearable:

• Fast and simple-to-use source code parser library and good AST/API to extract the annotations, classes and methods that are of the interest of the tool (without specifying upfront which parts we are interested in). My problem with package:source_gen and related build-utilities is their complexity: they are two levels up the chain, they use the framework approach (having a single but somewhat complex way to do things), as opposed to a library that exposes the data and allows the tool to process it as they want. package:analyzer is not really without ceremonies either, but at least it is "only" a library. Sometimes I don't even need to explore the types recursively, I just need the field/methods's name the parameter names and their types. It is not an issue if the full source graph is not available right away, in many cases it may be a (performance) benefit.

• A separate source code generator, that is not tied to any convention (e.g. not every project wants to use part for the generated files, nor do they necessarily want to place only a single file in the same directory as the source). I have done at least 4 separate code generators in the past years, and they had different requirements about these, and it was just easier to do String concatenation + custom file placement + calling dartfmt than to use any of the big frameworks. I want to build my source code in a programmatic way, the library can enforce the structure (class, method, function boundaries) and format it nicely, and that's all it needs to do. E.g. source_gen examples are full of generators, which assume that I want only to plug in a small piece somewhere. Instead, it should just take the tree as I build it.

• A trigger mechanism which detects when the generator chain needs to run. I think the situation here is rather good, and I don't have much preference: package:build_runner's approach may be okay (if made simple for generic tool use), or even package:watcher can be used if the programmatic approach is preferred by the developer.

• A more convenient way to live-reload classes in the Dart (JIT) VM. package:vm_service + package:watcher should be really a VM flag that can trigger a reload of classes locally, without further configuration or without adding dependencies to the application under development. (Yes, it may not cover 0.1% of the changes that may happen, e.g. depending on a new package, but restarting the local dev app every once in a while is not an issue. Restarting it every time is.)

Summary: To replace dart:mirrors, the following tools need to be available:

• parse and expose parts of the code efficiently
• generate source code in a convenient way
• (trigger source code generator when the inputs have changed)
• reload the source code in the local dev VM without long ceremonies

[scheglov]

The Dart Analyzer team uses package:test_reflective_loader extensively for all our tests, and it is based on using mirrors. We found out early that vanilla package:test is not structured enough for complicated package:analyzer tests.

[lexaknyazev]

My use case of reflection is docs generation via iterating over class members and invoking them to get sample outputs. The code using dart:mirrors resides in a grinder task thus being completely unaffected by the lack of support by web and AOT runtimes.

[jakemac53]

I have mentioned this elsewhere but worth mentioning here for posterity - build_runner uses dart:mirrors in order to discover all of the libraries that exist in a program. In our case that is the build script itself, and we use that to know if we need to invalidate the snapshot.

[gmpassos]

I think that a new framework for reflection should exists. For now we should kill dart:mirrors.

In the future, after NNBD, a new framework should exists with another name. One where you can mark classes that should have their full description after compilation (the main information needed for runtime reflection). The marked classes could be by annotation or passing a list of classes for the "refletor factory" that should be tracked, allowing any class to be tracked for reflection. With that approach,Dart tree shaking won't be affected, unless you really need a reflected class for your project.

[nex3]

dart:mirrors is used by Grinder, which is the best (and only) task runner for Dart with an 84% popularity rating on pub.dev, and my the mustache package which is used by both Dartdoc and the 99%-popularity google_fonts package. Both of these are load-bearing ecosystem packages. Removing dart:mirrors without a clear plan for something similarly usable for these packages would cause a lot of downstream pain and chaos.

It's worth noting that @isoos's proposed solution would likely not be sufficient for Grinder, since it's infeasible to have a code generation step as part of a task runner workflow.

[tvolkert]

This (a) doesn't solve all the problems with dart:mirrors, and (b) would only cater to specific use cases, but leaving the idea here nonetheless... what if we were to still tree-shake as normal even in the presence of dart:mirrors, and rely on developers marking methods as @pragma("vm:entry-point")?

[DavidLiedle]

My use case is... well, hold on just a dang minute.

I don't think I should have to lay out my thinking process to express the fact that I value the presence of dart:mirrors in the language. This "what is your use case?" approach smells of management and budgeting issues; not of nurturing the Dart ecosystem with an optimistic eye on the 10-20 year future of the language.

The APIs supported by mirrors are significantly behind the current Dart language, for example they do not support extension methods or null safety.

So allocate the dev resources to get on that. "Significantly behind" is a prioritization issue.

This is plainly technical debt. Defenestrating a sub-section of your server-side users building ORMs (oops, there's my use case..) would be an easy way out, and clearly a cheaper path forward. But seriously, cheaper over better? Not very Googley, imho. Do the right thing. Strive for excellence (and make the one thing you're doing really well be creating a language that can be used everywhere, including places where reflection makes sense). Keep an eye on the goals (both short and long term). Be proactive (and bring dart:mirrors up to par). Go the extra mile... Well, you know all this. You're the ones that work there.

I've been one of the earliest, most enthusiastic, and staunchest allies of both Dart and Flutter, but the bloom is off the rose with several prioritization choices that make me just, well, nervous. I'm tired of building things in AngularDart, or Polymer.dart (oy..), and then getting downstream just enough to feel the aging, unfinished edges and have to admit to myself that it's not a viable path forward. I have had to abandon chunks of my work because of hitting these dead ends and faded photos of what was planned. It's turning my attention to other places, and mine has teh sad. It took this thread for me to even glance back at AngularDart and see that it received an update in October of this year. Yay! But.. I can't trust it; already tried that, and got left behind.

TL;DR: this decision will impact the trust of your user base regarding your team's intentions in general; trust that is already flying on one engine. If we smell even a whiff of "Flutter doesn't need it so it's getting de-funded", even the features you do nurture will be untrusted for any other use case, and weaken your entire value proposition. Many of us, even your biggest fans, will simply walk. Not a rage-quit, but a pragmatic step out of what would appear to be a populism-driven-dev world and into other environments that focus on remaining well-rounded. Over time. For everyone.

The End

[zmeggyesi]

@gmpassos

For now we should kill dart:mirrors.

Not without a replacement being widely available and adopted we shouldn't!

Evidently, mirrors and reflection as a whole is widely used, in load-bearing packages as @nex3 points out, not to mention in the major task runner of the ecosystem. Killing mirrors without a replacement at this point pretty much breaks the ecosystem; killing it with a replacement that's not (near-)universally adopted does the same.

If the team moves forward with deprecating and removing this, it should only be done after they provided a replacement framework/solution, and the majority of the ecosystem, or at least its core components, have transitioned to the new way of doing things.