Skip to content

Commit ab15d37

Browse files
authored
Update native interop overview and mark Pigeon native interop as preview (#14033)
## Description Updates the Native interop overview (`/interop`), Pigeon guide (`/interop/pigeon`), and Platform channels guide (`/platform-integration/platform-channels`) for the 3.41 native interop release: - **`/interop` (`sites/docs/src/content/interop/index.md`)**: - Replaces the prescriptive "Choose your interop solution" decision tree with an architectural "Overview of interop tools" section (preserving `<a id="choose-your-interop-solution" aria-hidden="true"></a>` for existing deep links) and a server-rendered Mermaid diagram comparing the **bottom-up** (`FFIgen` and `JNIgen`) and **top-down** (`Pigeon`) approaches. - Updates the tool comparison table to mark `Pigeon (native interop)` as `(preview)` and remove `(recommended)` from the header. - **`/interop/pigeon` (`sites/docs/src/content/interop/pigeon.md`)**: - Folds the `FFIgen`/`JNIgen` pointer into `## Overview` and removes "recommended default tool" framing. - Marks `### Pigeon with native interop (preview)` (`{:#pigeon-with-native-interop}`) as preview with a `:::note` banner. - Documents the multi-engine `<Api>Registrar` limitation under `## Constraints and limitations` (`### Multiple Flutter engines`). - **`/platform-integration/platform-channels` (`sites/docs/src/content/platform-integration/platform-channels.md`)**: - Simplifies the top `:::note` pointer to link to the [Native interop overview](/interop). ## Related Issue - Supersedes #14027 - Related to flutter/flutter#195877 ## Checklist - [x] I have read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I have reviewed the [Style Guide] to ensure my changes follow the style guidelines for this repo. - [x] I have tested the changes locally or on the staging URL to ensure they render as expected. [Contributor Guide]: https://github.com/flutter/website/blob/main/CONTRIBUTING.md [Style Guide]: https://developers.google.com/style
1 parent 7732c67 commit ab15d37

3 files changed

Lines changed: 95 additions & 100 deletions

File tree

‎sites/docs/src/content/interop/index.md‎

Lines changed: 64 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -10,88 +10,70 @@ with the host operating system or run code from an existing native library.
1010
To solve this, Flutter provides several interop tools ranging from
1111
code generators to direct FFI bindings.
1212

13-
Use the following decision tree to choose your interop solution,
14-
or read on to learn about the native interop layers.
13+
<a id="choose-your-interop-solution" aria-hidden="true"></a>
14+
## Overview of interop tools
1515

16-
## Choose your interop solution
16+
Flutter's interop tools take one of two architectural approaches
17+
to bridging Dart and native code.
18+
FFIgen and JNIgen use a bottom-up approach, which starts from existing
19+
native APIs and generates Dart bindings that mirror them directly.
20+
Pigeon uses a top-down approach, which starts from a single Dart schema
21+
and generates matching client and host interfaces across multiple platforms.
22+
Choose the approach that best fits your integration needs.
1723

1824
```mermaid
25+
%%{init: {'themeVariables': {'clusterBkg': '#1a73e80a', 'clusterBorder': '#1a73e8'}}}%%
1926
flowchart TD
20-
Start(["Question 1: What is your primary goal?"]) --> GoalA["Goal A: Platform integration<br>(Swift, Kotlin, Java, Obj-C)"]
21-
Start --> GoalB["Goal B: C-ABI wrapping<br>(C, C++, Rust, Go)"]
22-
Start --> GoalC["Goal C: Pure Dart package<br>(No Flutter framework)"]
23-
24-
GoalB --> FFIgen["Use FFIgen<br>(or Flutter Rust Bridge)"]:::directNode
25-
GoalC --> Direct["Use FFIgen or JNIgen"]:::directNode
26-
27-
GoalA --> EvalPigeon{"Question 2: Do high-complexity<br>constraints apply?"}
28-
EvalPigeon -->|"No (most common)"| Pigeon["Use Pigeon<br>(Recommended default)"]:::recommendedNode
29-
EvalPigeon -->|"Yes (advanced)"| DirectInterop["Use FFIgen or JNIgen"]:::directNode
30-
31-
classDef recommendedNode stroke:#1e8e3e,stroke-width:2px;
32-
classDef directNode stroke:#1a73e8,stroke-width:2px;
27+
subgraph TopDown["Top-down: Pigeon"]
28+
direction TB
29+
Contract["Single Dart schema<br>(Platform-agnostic API)"]:::flutterNode --> GenPigeon["Pigeon code generator<br>(Top-down boundary)"]:::flutterNode
30+
GenPigeon --> PigeonAPI["Dart and host interfaces<br>(Multi-platform APIs)"]:::flutterAccent
31+
end
32+
33+
subgraph BottomUp["Bottom-up: FFIgen and JNIgen"]
34+
direction TB
35+
NativeAPI["Existing native APIs<br>(C, Obj-C, Java, Kotlin)"]:::flutterNode --> GenDirect["FFIgen and JNIgen<br>(Bottom-up generators)"]:::flutterNode
36+
GenDirect --> DirectAPI["Direct Dart bindings<br>(Platform-shaped APIs)"]:::flutterAccent
37+
end
38+
39+
classDef flutterNode fill:#1a73e814,stroke:#1a73e8,stroke-width:1.5px;
40+
classDef flutterAccent fill:#1a73e826,stroke:#1a73e8,stroke-width:2px;
3341
```
3442

35-
---
36-
37-
Answer the following questions to walk through the decision tree in detail:
38-
39-
### Question 1: What is your primary goal?
40-
41-
**Goal A: Platform integration**
42-
: Communicate with native OS features (Swift, Kotlin, Java, or Objective-C)
43-
or expose an API surface.
44-
Proceed to [Question 2: Do high-complexity constraints apply?](#question-2-do-high-complexity-constraints-apply).
45-
46-
**Goal B: C-ABI wrapping**
47-
: Wrap an existing native library (C, C++, Rust, or Go).
48-
Use [FFIgen](/interop/ffigen)
49-
(or [Flutter Rust Bridge][frb] for Rust).
50-
51-
**Goal C: Pure Dart package**
52-
: Build a Dart CLI tool without Flutter framework dependencies.
53-
Use [FFIgen](/interop/ffigen) or
54-
[JNIgen](/interop/jnigen).
55-
56-
### Question 2: Do high-complexity constraints apply?
57-
58-
If you're building a Flutter plugin,
59-
first verify whether [Pigeon](/interop/pigeon) satisfies
60-
your technical constraints.
61-
62-
:::important
63-
Migrating a plugin between Pigeon and FFIgen or JNIgen is non-trivial
64-
because the glue code lives in different languages.
65-
Evaluate your plugin's constraints carefully before choosing between them.
66-
:::
67-
68-
Do any of the following requirements apply to your feature?
69-
70-
- Your app processes high-frequency raw data (for example, video processing).
71-
- Your integration requires advanced language bridging
72-
(for example, cross-language subclasses, delegates, or proxies).
73-
- Your feature requires manual memory management and multithreading over
74-
guardrails.
75-
- Your target language is C, C++, Rust, or Go.
76-
77-
Based on whether any of the preceding requirements apply,
78-
choose your interop tool:
79-
80-
**No (most common) — Use [Pigeon](/interop/pigeon)**
81-
: This is the default, recommended path.
82-
It provides necessary guardrails, creates easily digestible interface
83-
mappings, and is highly efficient for most API surface areas.
84-
85-
**Yes — Use [FFIgen](/interop/ffigen) or [JNIgen](/interop/jnigen)**
86-
: You need the flexibility, complexity, and performance of direct interop for
87-
larger surface areas.
88-
89-
:::note
90-
Directly using FFIgen and JNIgen introduces potential pitfalls,
91-
particularly around threading and memory management.
92-
Pigeon is generally recommended because it has fewer potential pitfalls
93-
and provides safer guardrails.
94-
:::
43+
### Bottom-up with FFIgen and JNIgen
44+
45+
FFIgen and JNIgen generate low-level Dart bindings directly from your
46+
target platform's headers or classes.
47+
Because the generated bindings call native code without serialization
48+
overhead, you're responsible for managing native memory lifetimes and
49+
threading in your Dart code.
50+
51+
- [FFIgen](/interop/ffigen) parses C and Objective-C headers
52+
(including `@objc`-annotated Swift) to generate direct
53+
[`dart:ffi`](/interop/dart-ffi) bindings.
54+
Wrapping an iOS or macOS framework with FFIgen produces an
55+
Apple-shaped Dart API; wrapping a C library or C-ABI binary
56+
(C, C++ with `extern "C"`, Rust, or Go) produces a C-shaped Dart API.
57+
- [JNIgen](/interop/jnigen) inspects Java and Kotlin classes,
58+
JAR and AAR files, or Android SDK packages to generate direct JNI bindings.
59+
Wrapping an Android package with JNIgen produces an
60+
Android-shaped Dart API.
61+
62+
### Top-down with Pigeon
63+
64+
[Pigeon](/interop/pigeon) starts from a single Dart schema that
65+
defines an intentional, platform-agnostic boundary contract once and
66+
enforces identical types and signatures across Android, iOS, macOS,
67+
Windows, and Linux.
68+
You implement the generated host interface on each target platform
69+
while Pigeon handles type safety, data conversion, and cross-runtime
70+
memory safety across the boundary.
71+
72+
Pigeon generates bindings over
73+
[platform channels](/platform-integration/platform-channels)
74+
for all supported platforms, and offers a preview option to generate
75+
direct native interop bindings using [FFIgen](/interop/ffigen)
76+
on iOS and macOS and [JNIgen](/interop/jnigen) on Android.
9577

9678
## Package your interop code
9779

@@ -128,8 +110,8 @@ The following table compares two interop solutions:
128110

129111
- **Direct interop:** Lower-level direct bindings with higher performance for
130112
large data; requires manual memory and threading management.
131-
- **Pigeon:** Structured, type-safe code generator; recommended default for
132-
Flutter plugins.
113+
- **Pigeon:** Structured, type-safe code generator for cross-platform
114+
boundary contracts.
133115

134116
| Target language | Direct interop | Pigeon |
135117
| --- | --- | --- |
@@ -140,10 +122,10 @@ The following table compares two interop solutions:
140122
| **Rust without `extern "C"`** | [Flutter Rust Bridge][frb] | Not supported |
141123
| **Go with `extern "C"`** | [FFIgen](/interop/ffigen) | Not supported directly |
142124
| **Go without `extern "C"`** | Not supported | Not supported |
143-
| **Java** | [JNIgen](/interop/jnigen) | Supported through Kotlin (native interop) or directly with platform channels |
144-
| **Kotlin** | [JNIgen](/interop/jnigen) | Supported (recommended) |
145-
| **Objective-C** | [FFIgen](/interop/ffigen) | Supported through Swift (native interop) or directly with platform channels |
146-
| **Swift without Obj-C compatibility annotations** | [`package:swiftgen`][swiftgen-pub] (experimental) | Supported (recommended) |
125+
| **Java** | [JNIgen](/interop/jnigen) | Supported with platform channels, or through Kotlin with native interop (preview) |
126+
| **Kotlin** | [JNIgen](/interop/jnigen) | Supported with platform channels or native interop (preview) |
127+
| **Objective-C** | [FFIgen](/interop/ffigen) | Supported with platform channels, or through Swift with native interop (preview) |
128+
| **Swift without Obj-C compatibility annotations** | [`package:swiftgen`][swiftgen-pub] (experimental) | Supported with platform channels or native interop (preview) |
147129

148130
{:.table .table-striped}
149131

‎sites/docs/src/content/interop/pigeon.md‎

Lines changed: 29 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -7,30 +7,32 @@ description: >-
77

88
## Overview
99

10-
Pigeon is the recommended default tool for building Flutter plugins.
11-
Pigeon replaces the manual setup of raw platform channels with generated,
12-
type-safe APIs.
10+
[Pigeon][pigeon-pub] replaces the manual setup of raw platform channels
11+
with generated, type-safe APIs.
1312
This helps prevent typos in method names or mismatched argument types.
1413

14+
For low-level integrations that require direct access to native memory
15+
or C and C++ libraries, use [FFIgen](/interop/ffigen)
16+
or [JNIgen](/interop/jnigen) instead.
17+
1518
## Choose a communication option with Pigeon
1619

17-
Pigeon supports the following two communication options depending on your target
18-
platform and performance needs:
19-
native interop (direct FFI and JNI) or platform channels.
20+
Pigeon supports the following two communication options
21+
depending on your target platform and performance needs:
22+
native interop (direct FFI and JNI, in preview) or platform channels.
23+
24+
### Pigeon with native interop (preview) {:#pigeon-with-native-interop}
2025

2126
:::note
22-
For low-level integrations that require direct access to native memory
23-
or C and C++ libraries, use [FFIgen](/interop/ffigen)
24-
or [JNIgen](/interop/jnigen) instead.
27+
Pigeon with native interop is in preview and isn't
28+
stable for production use.
2529
:::
2630

27-
### Pigeon with native interop
28-
29-
Pigeon with native interop uses [FFIgen](/interop/ffigen)
30-
and [JNIgen](/interop/jnigen) under the hood to generate
31-
direct native bindings (using FFI on iOS and macOS, and JNI on Android).
31+
Pigeon with native interop generates direct native bindings using
32+
[FFIgen](/interop/ffigen) (FFI on iOS and macOS) and
33+
[JNIgen](/interop/jnigen) (JNI on Android).
3234

33-
Use this option if your use case requires any of the following:
35+
Try this preview option if your use case requires any of the following:
3436

3537
- You need synchronous execution on your native platform.
3638
- You're doing high-frequency data streaming
@@ -117,6 +119,17 @@ where native code throws `FlutterError` or `PigeonError` directly.
117119
For `@asyncCallback` methods or other target languages,
118120
native code must return errors through the provided completion callback.
119121

122+
### Multiple Flutter engines
123+
124+
If you use [Pigeon with native interop](#pigeon-with-native-interop),
125+
`<MyApi>.createWithNativeInteropApi()` binds to the most recently registered
126+
host instance for a given `name` rather than looking up the calling
127+
`FlutterEngine` ([Flutter issue #195877][issue-195877]).
128+
Don't register multiple engines under the same `name` before each earlier
129+
engine initializes its Dart API client
130+
(such as pre-warming engines back-to-back or lazily instantiating the
131+
Dart client after another engine attaches).
132+
120133
## Resources
121134

122135
To learn about building and migrating plugins with Pigeon,
@@ -136,3 +149,4 @@ refer to the following resources:
136149
[pigeon-migration-guide]: {{site.repo.packages}}/blob/main/packages/pigeon/native_interop_migration_guide.md
137150
[shared-preferences-source]: {{site.repo.packages}}/tree/main/packages/shared_preferences
138151
[native-interop-demos]: {{site.repo.demos}}/tree/main/native_interop_demos
152+
[issue-195877]: {{site.repo.flutter}}/issues/195877

‎sites/docs/src/content/platform-integration/platform-channels.md‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ description: Learn how to write platform-specific code using Flutter's platform
88

99
:::note
1010
Refer to the [Native interop overview](/interop)
11-
for recommended approaches to calling native platform code.
11+
to learn about FFIgen, JNIgen, and Pigeon.
1212
:::
1313

1414
Platform channels pass messages between Flutter and your host platform
@@ -1145,8 +1145,7 @@ it displays 'Battery level not available'.
11451145
11461146
## Call platform-specific code using the Pigeon package {:#pigeon}
11471147
1148-
Pigeon is the recommended default tool for generating type-safe bindings
1149-
between Dart and host platforms.
1148+
Pigeon generates type-safe bindings between Dart and host platforms.
11501149
To learn how to use Pigeon, define API contracts, and choose between
11511150
native interop and platform channels,
11521151
refer to the dedicated [Pigeon guide](/interop/pigeon).

0 commit comments

Comments
 (0)