Unify <Foo> and <Foo>Impl classes that are effectively simple enums or data classes #1604
Conversation
PR HealthBreaking changes ✔️
Changelog Entry ✔️
Changes to files need to be accounted for in their respective changelogs. API leaks ✔️The following packages contain symbols visible in the public API, but not exported by the library. Export these symbols or remove them from your publicly visible API.
License Headers ✔️
All source files should start with a license header. Unrelated files missing license headers
Package publish validation ✔️
Documentation at https://github.com/dart-lang/ecosystem/wiki/Publishing-automation. |
mkustermann
force-pushed
the
impl-removal
branch
from
5022193 to
1ab85f0
Compare
There was a problem hiding this comment.
The API of
package:native_assets_cliuses currently a one-size-fits-all approach:
- almost every API class is duplicated between a
<Foo>and<Foo>Implpackage:native_assets_cli/native_assets_cli.dartexposes<Foo>package:native_assets_cli/native_assets_cli_internal.dartexposes<Foo>ImplThis has a number of issues
- The
_internal.dartis actually a public API: It's used e.g. by flutter tools and breaking changes to it need major version bumps.
I believe this is a common and established pattern.
A user of the
<Foo>API doesn't know that such objects are for example
- hashable (e.g. go-to-definition to
<Foo>there's no indication of that), e.g.DynamicLoadingSystemmakes no mention of it, noget hashCodeoverride, ... only inDynamicLoadingSystemImplthere is.- have a
toString()that code can rely on the returned string not changing
This could be alternatively addressed by adding those methods to the API.
- It causes code to have to choose between e.g.
OSandOSImpl- which is very confusing as it's just one concept.
Yes, prioritizing hook writer API cleanliness for package:native_asset_cli makes the use of package:native_asset_cli/internal.dart in native_assets_builder, flutter_tools, and dartdev more ugly. That's the cost of the trade-off here.
I'm on the fence whether that cost is worth it.
- It causes code to have to downcast e.g.
os as OSImpl.
=> This is a very bad smell, as generally it's an unsafe operation to downcast.
For final classes the casts are guaranteed to succeed. The package owns all possible implementations. I believe this to be an accepted pattern. (Agreed it's ugly in the code!)
- It's code duplication across the
api/andmodel/folders, make it harder to navigate in codebase (as one may have to constantly switch between the files), ...One original intention for this separation may have been to hide all traces of the json protocol in the non-internal version
And any other things needed by any native_assets_builder, flutter_tools and dartdev that does not fit well in those packages and is more conveniently unit tests in native_assets_cli.
The JSON serialization/deserialization is probably the most important one, but some are not related to serialization:
Architecture.dartPlatformis now publicArchitecture.fromStringis now publicArchitecture.fromAbiis now public (not JSON serializable related)OS.dartPlatformis now publicOS.fromStringis now publicOS.architecturesis now public (not JSON serializable related)OS.osCrossCompilationDefaultis now public (not JSON serializable related)BuildMode.fromStringis now publicIOSSdk.xcodebuildSdkis now publicLinkModePreference.fromStringis now public
Can the non-JSON ones be made private or moved to native_assets_builder without breaking native_assets_builder, flutter_tools and dartdev?
but I think this is not needed at all, because the protocol itself will be more stable than the APIs offered by the package itself (much easier to break the dart API and publish and new version of the package than to break the CLI protocol).
The fromString/toString methods are not at all obvious that they are meant for json serialization and deserialization. So if we expose them, we should document accordingly that this is what they are meant for.
Ditto for Architecture.dartPlatform, OS.dartPlatform, IOSSdk.xcodebuildSdk. It's not obvious that these are the unique keys for JSON serialization.
=> So this PR starts to merge some
<Foo>and<Foo>Implclasses into one<Foo>. => This simplifies the code, removesas ...Impldowncasts, etc
There's an inherent trade-off between having a clean user API without clutter and a simpler implementation.
I believe this PR clutters the user API more. But indeed (after rolling) it makes our own job easier in native_assets_builder, flutter_tools and dartdev. So, I'm on the fence on whether we want to move this direction.
If we want to move this direction:
- All newly exposed public APIs should have doc comments. The doc comments should explain that this is their valid JSON serialization. And should explain that the
nameis unique and stable. - Some of the members should maybe be renamed:
Architecture.dartPlatform->Architecture.name? Ditto forOS.dartPlatformandIOSSdk.xcodebuildSdk. (Or can they be made private and we only exposetoString(). But maybe having anameis cleaner.) - Move the non-JSON serialization related things to extension methods in native_assets_builder or make them private if only used inside the implementation.
|
/cc @dart-lang/interop-team Any reservation against this? |
I like the change. |
Could we add |
|
@dcharkes Had offline conversation with @lrhn and it seems he agrees with me
|
I could mark it as @internal. But future refactoring will intentionally start exposing more of the underlying json protocol to make this package more extensible from the outside (so flutter can add flutter-specific configurations & asset types without touching dart-lang/native). Also: Anything flutter_tools uses is part of the public API. Even hook writers may want to use But if someone feels strongly about this, let me know and I can put the annotation on. |
mkustermann
force-pushed
the
impl-removal
branch
from
63340dc to
6ee53b3
Compare
PTAL |
There was a problem hiding this comment.
Also: Anything flutter_tools uses is part of the public API. Even hook writers may want to use
package:loggingand dump some of these values via.toJson()if they get into some build issues, so I don't think it's harmful to have those methods.
I don't believe this statement is true. It's perfectly fine to use internal.dart in flutter_tools. So what Flutter tools and dartdev need I don't consider part of the public API. What hook writers need I consider part of the public API.
Changes in general LGTM! 🚢
We could consider marking these things |
If this is a concern I can remove all the @dcharkes @HosseinYousefi let me know what you think! |
I guess it's terminology. We could have (I guess currently one could argue there's sort of an exception because Dart SDK uses this package from source and not from pub and flutter tools uses a specific pinpointed version, but this is also supposed to be usable from 3rd parties) |
If the problem is only with |
Yeah, if we have two APIs (one for hook writers, and one for embedders/launchers) we would want two semantic versions. Maybe we get the desired result if we export all types from |
Yeah, that's why I had the impl classes in the first place, I didn't want to have the methods not on the class, because that prevented using dynamic dispatch for any variants. So lets keep them in the class. No strong opinions, just do what you think is best w.r.t. annotations and privateness. |
…e data classes
The API of `package:native_assets_cli` uses currently a
one-size-fits-all approach:
* almost every API class is duplicated between a `<Foo>` and `<Foo>Impl`
* `package:native_assets_cli/native_assets_cli.dart` exposes `<Foo>`
* `package:native_assets_cli/native_assets_cli_internal.dart` exposes `<Foo>Impl`
This has a number of issues
* The `_internal.dart` is actually a public API: It's used e.g. by
flutter tools and breaking changes to it need major version bumps.
* A user of the `<Foo>` API doesn't know that such objects are for
example
* hashable (e.g. go-to-definition to `<Foo>` there's no
indication of that), e.g. `DynamicLoadingSystem` makes no mention
of it, no `get hashCode` override, ... only in
`DynamicLoadingSystemImpl` there is.
* have a `toString()` that code can rely on the returned string not
changing
* ...
* It causes code to have to choose between e.g. `OS` and `OSImpl` -
which is very confusing as it's just one concept.
* It causes code to have to downcast e.g. `os as OSImpl`.
=> This is a very bad smell, as generally it's an unsafe operation to
downcast.
* It's code duplication across the api/ and model/ folders, make it
harder to navigate in codebase (as one may have to constantly switch
between the files), ...
One original intention for this seperation may have been to hide all traces
of the json protocol in the non-internal version, but I think this is not
needed at all, because the protocol itself will be *more* stable than the APIs
offered by the package itself (much easier to break the dart API and publish and
new version of the package than to break the CLI protocol).
=> So this PR starts to merge some `<Foo>` and `<Foo>Impl` classes into
one `<Foo>`.
=> This simplifies the code, removes `as ...Impl` downcasts, etc
One extra thing this CL does is remove some members from e.g. `OS`. This
is part of disentangling the concepts. The build protocol may always
expose the target operating system, but it may only expose the target
ABI if the building code supports code assets.
=> So one should be able to use `OS` without `OS.dylibFileName` /
`OS.architectures` / ...
=> We may even decide to move code asset related code into it's own
package, making the core build protocol package not need the concept of
`Architecture` at all.
…fig is a plain data class)
mkustermann
force-pushed
the
impl-removal
branch
from
5155a61 to
e480b33
Compare
The dynamic dispatch will go away (if we don't know all asset types, we could call
I'll leave it like this for now. We have plenty of time to revisit and polish the APIs before declaring 1.0. For now my goal is to get the rough structure into a place that allows easy extension from flutter with custom asset types and custom confinguration. Thanks for the chiming in, everyone! |
The API of
package:native_assets_cliuses currently a one-size-fits-all approach:<Foo>and<Foo>Implpackage:native_assets_cli/native_assets_cli.dartexposes<Foo>package:native_assets_cli/native_assets_cli_internal.dartexposes<Foo>ImplThis has a number of issues
The
_internal.dartis actually a public API: It's used e.g. by flutter tools and breaking changes to it need major version bumps.A user of the
<Foo>API doesn't know that such objects are for example<Foo>there's no indication of that), e.g.DynamicLoadingSystemmakes no mention of it, noget hashCodeoverride, ... only inDynamicLoadingSystemImplthere is.toString()that code can rely on the returned string not changingIt causes code to have to choose between e.g.
OSandOSImpl- which is very confusing as it's just one concept.It causes code to have to downcast e.g.
os as OSImpl.=> This is a very bad smell, as generally it's an unsafe operation to downcast.
It's code duplication across the
api/andmodel/folders, make it harder to navigate in codebase (as one may have to constantly switch between the files), ...One original intention for this seperation may have been to hide all traces of the json protocol in the non-internal version, but I think this is not needed at all, because the protocol itself will be more stable than the APIs offered by the package itself (much easier to break the dart API and publish and new version of the package than to break the CLI protocol).
=> So this PR starts to merge some
<Foo>and<Foo>Implclasses into one<Foo>.=> This simplifies the code, removes
as ...Impldowncasts, etcOne extra thing this CL does is remove some members from e.g.
OS. This is part of disentangling the concepts. The build protocol may always expose the target operating system, but it may only expose the target ABI if the building code supports code assets.=> So one should be able to use
OSwithoutOS.dylibFileName/OS.architectures/ ...=> We may even decide to move code asset related code into it's own package, making the core build protocol package not need the concept of
Architectureat all.