|
| 1 | +# Setting Flutter Android engine flags |
| 2 | + |
| 3 | +You can set flags for the Flutter engine on Android in two different ways: |
| 4 | + |
| 5 | +- From the command line when launching an app with the Flutter tool |
| 6 | +- Via `AndroidManifest.xml` metadata (static, per-build configuration) |
| 7 | + |
| 8 | +Flags available on Android may be set via the command line **and/or** via |
| 9 | +manifest metadata depending on the flag. See |
| 10 | +`src/flutter/shell/platform/android/io/flutter/embedding/engine/` |
| 11 | +`FlutterEngineFlags.java` for the list of flags that can be set for |
| 12 | +the Android shell, and see `src/flutter/shell/common/switch_defs.h` |
| 13 | +for the list of all supported flags. |
| 14 | + |
| 15 | +For flags that can be set on the command line and via the manifest, |
| 16 | +see below to determine which method to use. |
| 17 | + |
| 18 | +## When to use manifest metadata versus the command line |
| 19 | + |
| 20 | +Use the manifest when: |
| 21 | + |
| 22 | +- You want a fixed, reproducible baseline of engine flags |
| 23 | + for your app across all launches. This is ideal for CI and for enforcing a |
| 24 | + consistent configuration for your app. |
| 25 | +- You want to vary flags by build mode or product flavor |
| 26 | + via manifest merging. For example, place metadata in |
| 27 | + `src/debug/AndroidManifest.xml`, `src/profile/AndroidManifest.xml`, and |
| 28 | + `src/release/AndroidManifest.xml` (or per-flavor manifests) to tailor flags |
| 29 | + per variant. |
| 30 | + |
| 31 | +Use the command line when: |
| 32 | + |
| 33 | +- You want to quickly experiment with a flag for a single run of your app. |
| 34 | +- You need to override a flag that is already set in the manifest temporarily for debugging |
| 35 | + or testing purposes. |
| 36 | + |
| 37 | +**Note: If a flag is specified both on the command line and in the manifest, |
| 38 | +the command-line value takes precedence at runtime.** |
| 39 | + |
| 40 | +See below for details on using each method. |
| 41 | + |
| 42 | +## How to set engine flags from the command line |
| 43 | + |
| 44 | +When you run a standalone Flutter app with the Flutter tool, engine flags |
| 45 | +can be passed directly and are forwarded to the Android engine. Examples: |
| 46 | + |
| 47 | +```bash |
| 48 | +flutter run --trace-startup \ |
| 49 | + --enable-software-rendering \ |
| 50 | + --dart-flags="--enable-asserts" |
| 51 | +``` |
| 52 | + |
| 53 | +Notes: |
| 54 | + |
| 55 | +- Flags that take values use the `--flag=value` form (with `=`). The Flutter |
| 56 | + tool forwards them in that form to the Android embedding. |
| 57 | + |
| 58 | +## How to set engine flags in the manifest |
| 59 | + |
| 60 | +All manifest metadata keys must be prefixed with the package name |
| 61 | +`io.flutter.embedding.android` and are suffixed with the metadata name for the |
| 62 | +related command line flag as determined in |
| 63 | +`src/flutter/shell/platform/android/io/flutter/embedding/engine/` |
| 64 | +`FlutterEngineFlags.java`. For example, the `--impeller-lazy-shader-mode=` |
| 65 | +command line flag corresponds to the metadata key |
| 66 | +`io.flutter.embedding.android.ImpellerLazyShaderInitialization`. |
| 67 | + |
| 68 | +For flags that take values, set the numeric, string, or boolean value (without |
| 69 | +the leading `--flag=` prefix). |
| 70 | + |
| 71 | +### Examples |
| 72 | + |
| 73 | +Set the `--trace-to-file=` flag to `some_file.txt`: |
| 74 | + |
| 75 | +```xml |
| 76 | +<manifest xmlns:android="http://schemas.android.com/apk/res/android" |
| 77 | + package="com.example.myapp"> |
| 78 | + <application ...> |
| 79 | + <meta-data |
| 80 | + android:name="io.flutter.embedding.android.TraceToFile" |
| 81 | + android:value="some_file.txt"/> |
| 82 | + ... |
| 83 | + </application> |
| 84 | +</manifest> |
| 85 | +``` |
| 86 | + |
| 87 | +Set the `--enable-flutter-gpu` flag: |
| 88 | + |
| 89 | +```xml |
| 90 | +<meta-data |
| 91 | + android:name="io.flutter.embedding.android.EnableFlutterGPU" |
| 92 | + android:value=true |
| 93 | +/> |
| 94 | +``` |
| 95 | + |
| 96 | +For flags that take boolean values, if you omit a value entirely, it |
| 97 | +will be assumed to be true. For example, this is the same as the |
| 98 | +example above: |
| 99 | + |
| 100 | +```xml |
| 101 | +<meta-data |
| 102 | + android:name="io.flutter.embedding.android.EnableFlutterGPU" |
| 103 | +/> |
| 104 | +``` |
| 105 | + |
| 106 | +## Release-mode restrictions |
| 107 | + |
| 108 | +- Some flags are not allowed in release mode. The Android embedding enforces |
| 109 | + this policy (see `src/flutter/shell/platform/android/io/flutter/ |
| 110 | + embedding/engine/FlutterEngineFlags`, which marks allowed flags |
| 111 | + with `allowedInRelease`). If a disallowed flag is set in release, it will |
| 112 | + be ignored. |
| 113 | +- If you need different behavior in release vs debug/profile mode, configure it |
| 114 | + via variant-specific manifests or product flavors. |
| 115 | + |
| 116 | +## How to set engine flags dynamically |
| 117 | + |
| 118 | +As of the writing of this document, setting Flutter shell arguments via an |
| 119 | +Android `Intent` is no longer supported. If you need per-launch or |
| 120 | +runtime-controlled flags in an add-to-app integration, you may do so |
| 121 | +programatically before engine initialization. |
| 122 | + |
| 123 | +To do that, supply engine arguments directly to a `FlutterEngine` with the |
| 124 | +desired flags from the earliest point you can control in your |
| 125 | +application. For example, if you are writing an add-to-app app that launches |
| 126 | +a `FlutterActivity` or `FlutterFragment`, then you can cache a |
| 127 | +`FlutterEngine` that is initialized with your desired |
| 128 | +engine flags: |
| 129 | + |
| 130 | +```kotlin |
| 131 | +// Your native Android application |
| 132 | +class MyApp : Application() { |
| 133 | + override fun onCreate() { |
| 134 | + super.onCreate() |
| 135 | + // Initialize the Flutter engine with desired flags |
| 136 | + val args = arrayOf( |
| 137 | + "--trace-startup", |
| 138 | + "--trace-to-file=some_file.txt", |
| 139 | + "--enable-software-rendering" |
| 140 | + ) |
| 141 | + val flutterEngine = FlutterEngine(this, args) |
| 142 | + |
| 143 | + // Start executing Dart code in the FlutterEngine |
| 144 | + flutterEngine.dartExecutor.executeDartEntrypoint( |
| 145 | + DartEntrypoint.createDefault() |
| 146 | + ) |
| 147 | + |
| 148 | + // Store the engine in the cache for later use |
| 149 | + FlutterEngineCache.getInstance().put("my_engine_id", flutterEngine) |
| 150 | + } |
| 151 | +} |
| 152 | +``` |
| 153 | + |
| 154 | +Then, your `Activity` can launch a `FlutterActivity` or `FlutterFragment` |
| 155 | +with that cached `FlutterEngine`: |
| 156 | + |
| 157 | +```kotlin |
| 158 | +// Start a FlutterActivity using the cached engine... |
| 159 | +val intent = FlutterActivity.withCachedEngine("my_engine_id").build(this) |
| 160 | +startActivity(intent) |
| 161 | + |
| 162 | +// Or launch a FlutterFragment using the cached engine |
| 163 | +val flutterFragment = FlutterFragment.withCachedEngine("my_engine_id").build() |
| 164 | +supportFragmentManager |
| 165 | + .beginTransaction() |
| 166 | + .add(R.id.fragment_container, flutterFragment, TAG_FLUTTER_FRAGMENT) |
| 167 | + .commit() |
| 168 | +``` |
| 169 | + |
| 170 | +For a normal Flutter Android app, you can create and initialize a `FlutterEngine` |
| 171 | +with your desired flags the same as in the example above, then override |
| 172 | +`provideFlutterEngine` in your app's `FlutterActivity` to provide the |
| 173 | +configured `FlutterEngine`. For example: |
| 174 | + |
| 175 | +```kotlin |
| 176 | +// Your Flutter Android application |
| 177 | +class MyApplication : FlutterApplication() { |
| 178 | + override fun onCreate() { |
| 179 | + super.onCreate() |
| 180 | + |
| 181 | + val args = arrayOf( |
| 182 | + "--trace-startup", |
| 183 | + "--trace-to-file=some_file.txt", |
| 184 | + "--enable-software-rendering" |
| 185 | + ) |
| 186 | + val flutterEngine = FlutterEngine(this, args) |
| 187 | + flutterEngine.dartExecutor.executeDartEntrypoint( |
| 188 | + DartExecutor.DartEntrypoint.createDefault() |
| 189 | + ) |
| 190 | + FlutterEngineCache |
| 191 | + .getInstance() |
| 192 | + .put(MY_ENGINE_ID, flutterEngine) |
| 193 | + } |
| 194 | +} |
| 195 | + |
| 196 | +// Your Flutter Android Activity |
| 197 | +class MainActivity: FlutterActivity() { |
| 198 | + override fun provideFlutterEngine(context: Context): FlutterEngine? { |
| 199 | + return FlutterEngineCache |
| 200 | + .getInstance() |
| 201 | + .get(MyApplication.MY_ENGINE_ID) |
| 202 | + } |
| 203 | +} |
| 204 | +``` |
0 commit comments