Add native assets documentation

[dcharkes]

Adds documentation for the native assets feature.

• ☂️ [vm/ffi] Native assets feature sdk#50565

This is a first draft, any suggestions welcome.

• What should be in the docs and what should be links to samples / tracking bugs etc?
• Do we reference Flutter at all? (For example how to opt in to the experiment is different in flutter vs Dart. And also a Flutter example is accessed via running a template.)

---

• I’ve reviewed the contributor guide and applied the relevant portions to this PR.
• This PR doesn’t contain automatically generated corrections or text (Grammarly, LLMs, and similar).
• This PR follows the Google Developer Documentation Style Guidelines — for example, it doesn’t use i.e. or e.g., and it avoids I and we (first person).
• This PR uses semantic line breaks of 80 characters or fewer.

[dcharkes]

@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

[github-actions]

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}

[MaryaBelanger]

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 the build.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.

[dcharkes]

Thanks @parlough ! (Now that 3.2 stable is out, the links can all refer to the stable docs.)

[parlough]

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.

[parlough]

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 :)

[dcharkes]

Thanks for cleaning up all the small details @parlough! Much appreciated! ❤️