-
Notifications
You must be signed in to change notification settings - Fork 698
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add native assets documentation #5347
Conversation
@craiglabenz You know much better than me what a first user experience is, please feel free to push commits to this PR! @mit-mit See the questions at the top. Do we reference Flutter? FYI @mkustermann |
Visit the preview URL for this PR (updated for commit 33da4c8): https://dart-dev--pr5347-native-assets-gp8gcf4u.web.app (expires Wed, 22 Nov 2023 16:50:31 GMT) 🔥 via Firebase Hosting GitHub Action 🌎 Sign: d851bc446d3c4d7394c5406c6f07255afc7075f3 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Approving for the sake of release timing, but if you can incorporate this change that would be best:
Could you add a short introduction at the beginning of the section? Your content there does summarize the how, but maybe a clearer high-level summary will help people understand: why they might use this, what the benefit is to them, what workflow this experimental work is replacing, etc.
For example the summary from the 3.2 blog post is a good high-level intro:
...the Native Assets feature...aims to resolve a number of issues associated with the distribution of Dart packages that depend on native code. It does so by providing uniform hooks for integrating with various build systems involved in building Flutter and standalone Dart applications.
Ideally if you can add context, like "Instead of ...(doing it the old way that was bad because)..., Native Assets let you...." (I think this might be what you're alluding to when you said "To abstract over the bundle format..." later on)
And then follow with the part you already have written (summarizing how native assets does this):
With native assets, you can now include a
build.dart
script
as part of your package. This builds the native code contained in the package
that needs to be built before the package can be used.
Then, when the package needs to use the built, bundled code at runtime,
it can bypass the bundle format and access native code via the asset id property
of thebuild.dart
script.
I rewrote those slightly, not necessary though (and maybe no longer technically correct). And, I'd link to API docs / sample code examples for the script and asset id property, if that exists.
Co-authored-by: Marya <[email protected]>
Co-authored-by: Marya <[email protected]>
Co-authored-by: Marya <[email protected]>
Co-authored-by: Marya <[email protected]>
Thanks @parlough ! (Now that 3.2 stable is out, the links can all refer to the stable docs.) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks @dcharkes!! The Dart and Flutter communities are super excited to try native assets out.
I pushed a few formatting, Google style guide, and minor copy fixes. I also added a new simplified native-assets
anchor so we can link to just dart.dev/guides/libraries/c-interop#native-assets
.
I do have a few minor questions, but they don't block landing this.
Co-authored-by: Parker Lougheed <[email protected]>
There were a few other reviews requested from @craiglabenz and @mit-mit. I'm going to land this for now since the blog post links to the page, but please feel free to open a PR or let us know if we should make further changes :) |
Thanks for cleaning up all the small details @parlough! Much appreciated! ❤️ |
Adds documentation for the native assets feature. * dart-lang/sdk#50565 --------- Co-authored-by: Marya <[email protected]> Co-authored-by: Parker Lougheed <[email protected]>
Adds documentation for the native assets feature.
This is a first draft, any suggestions welcome.