☂️ Help Dart developers navigate Dart's platform interop support

[parlough]

Overview

This is an overarching project that will continue throughout the year and beyond, as we aim to help Dart developers learn about, understand, use, and build on Dart's evolving platform interoperability support. Over the past few years, Dart's interop story has completely changed, and we're long past the world of using the embedder API or native VM extensions. The interop story for web was more foundational for Dart but is now entering its next generation.

As Dart (and Flutter) target many platforms, this development has occurred in many different forms, in many different places, and across almost a decade, but we're nearing a point where it's all starting to come together. Now we have to help Dart developers actually understand how it comes together and how to take advantage of that in their own projects. A few savvy community members have been following along or picking up the pieces along the way, but now every Dart developer should be able to benefit.

Goal and structure

To be filled in...

Subtasks

The following is an incomplete and in progress list, but groups some related tasks and issues. In no way do each of these have to be resolved as part of this, but they're included here to not get lost or help inspire ideas.

Introduce developers to interoperability and help them determine next steps

• Take "Interop" contents out from under "Development" #5364
• ☂️ Add a new Dart platform interoperability overview #5439
• Add Dart's interop story to the documentation #4563
• Introduce overarching native interop introduction page #5286
• Include "other interop solutions" section in interop overview page #6244

Teach developers how to interop with native platforms

• 'C interop using dart:ffi' page mention package:ffi #3084
• [doc/ffi] More actively push package:ffigen? sdk#54505
• Overhaul existing FFI documentation for new site standards
• Separate standard ffi docs from ffigen docs
• Separate reference material from guides
• Provide better guidance on interacting with Dart code from the native side
• Help Flutter developers understand when to use ffi vs pigeon

Help developers publish packages and plugins that use native interop

• [Future] Document native assets and library bundling #5388
• Provide an end-to-end example of building and publishing a package

Teach developers how to use and/or migrate to Dart's new JS static interop

• ☂️ JS/web static interop overview, docs, and tutorials #5438
• ☂️ [Extension type] Language feature docs #4177
• Document external on the Functions page #5478
• Help developers use JS interop with non-web targets

Document the Wasm platform and any relevant interop functionality

• ☂️ Document Dart's support for compilation to Wasm #5609
• Explain Wasm support status and limitations
• Clarify support is for compiling to Wasm, not running
• Document how to interop with web/JS
• Add examples for interacting with Dart from Wasm source

Provide some guidelines and best practices for developers

• Put more emphasis on generating any bindings
• Add memory management tips to dart:ffi page #3193
• Customers want guidance and docs for tree-shaking sdk#33920
• Document some common issues to look out for

Enable developers to adapt their app to different platforms

• [Future] Documentation and call out for platform API changes #5334
• Document configuration-specific imports #4225
• Link to new platform specific networking #4175

Help developers understand differences between platforms

• Update 'Numbers in Dart' and elsewhere to account for dart2wasm supporting native semantics #5345
• Update dart:developer support note on 'Core libraries' #5107
• Reintroduce and update Dart SIMD guide #3679

[andycall]

Teach developers how to interop with native platforms

I’m writing a series of articles to teach Dart developers how to use FFI effectively, aimed at helping those without much native development experience.

Memory Management in Dart FFI
How to Debug Your C/C++ Codes in Flutter