[ios] guideline on iOS engine feature flags: Info.plist vs cmd flag

Use case

There are currently 2 ways of setting the flag on iOS: via cmd line flags or via Info.plist. It's unclear to me which one to use, as I see pros and cons on both.

Also there's an inconsistent practice: on android, systrace is enabled via cmd flag(see), but on iOS it's enabled via Info.plist (see)

Proposal

Come up with a guideline for the future.

@matanlurey

Now that experimental flags can be set per-project #167667, is there a plan to add guidance for this question, @matanlurey and @loic-sharma?

I don't understand the question.

There is currently no way to configure the iOS engine using feature flags (and support is not immediately planned), or configure any embedder. For example, --enable-impeller is not a feature flag (not a FeatureFlag), and there is no path (today) to converting it to one.

If you're asking a more general question of "should someone configure a flag, that is possible to use flutter config for, using flutter config --enable-x or flutter: config: enable-x: true, I'd recommend the pubspec.yaml route, but we're keeping both around.

Here's the guidance on feature flags: https://github.com/flutter/flutter/blob/master/docs/contributing/Feature-flags.md

When possible, you should not use Info.plist flags. Instead, you should prefer Flutter's cross-platform feature flags.

The cross-platform flags are more convenient for app developers as they are already familiar with the flutter tool and the .pubspec file. On the other hand, app developers are less familiar with platform-specific configuration files like Info.plist.

However, Flutter's cross-platform feature flags can only be used in the Flutter tool and Flutter framework. If the embedder or engine needs to know the value of a feature flag before the Dart isolate is launched, you should continue to use platform-specific configuration files like Info.plist.

I'll update our feature flags guidance to explain this!

So the Flutter tool has multiple flags that it passes from the command line to the engine:

flutter/packages/flutter_tools/lib/src/device.dart

Lines 1192 to 1244 in b2d4210

    
           List<String> getIOSLaunchArguments( 
        
             EnvironmentType environmentType, 
        
             String? route, 
        
             Map<String, Object?> platformArgs, { 
        
             DeviceConnectionInterface interfaceType = DeviceConnectionInterface.attached, 
        
             bool isCoreDevice = false, 
        
           }) { 
        
             return <String>[ 
        
               if (enableDartProfiling) '--enable-dart-profiling', 
        
               if (disableServiceAuthCodes) '--disable-service-auth-codes', 
        
               if (disablePortPublication) '--disable-vm-service-publication', 
        
               if (startPaused) '--start-paused', 
        
               // Wrap dart flags in quotes for physical devices 
        
               if (environmentType == EnvironmentType.physical && dartFlags.isNotEmpty) 
        
                 '--dart-flags="$dartFlags"', 
        
               if (environmentType == EnvironmentType.simulator && dartFlags.isNotEmpty) 
        
                 '--dart-flags=$dartFlags', 
        
               if (useTestFonts) '--use-test-fonts', 
        
               // Core Devices (iOS 17 devices) are debugged through Xcode so don't 
        
               // include these flags, which are used to check if the app was launched 
        
               // via Flutter CLI and `ios-deploy`. 
        
               if (debuggingEnabled && !isCoreDevice) ...<String>[ 
        
                 '--enable-checked-mode', 
        
                 '--verify-entry-points', 
        
               ], 
        
               if (enableSoftwareRendering) '--enable-software-rendering', 
        
               if (traceSystrace) '--trace-systrace', 
        
               if (traceToFile != null) '--trace-to-file="$traceToFile"', 
        
               if (skiaDeterministicRendering) '--skia-deterministic-rendering', 
        
               if (traceSkia) '--trace-skia', 
        
               if (traceAllowlist != null) '--trace-allowlist="$traceAllowlist"', 
        
               if (traceSkiaAllowlist != null) '--trace-skia-allowlist="$traceSkiaAllowlist"', 
        
               if (endlessTraceBuffer) '--endless-trace-buffer', 
        
               if (profileMicrotasks) '--profile-microtasks', 
        
               if (verboseSystemLogs) '--verbose-logging', 
        
               if (purgePersistentCache) '--purge-persistent-cache', 
        
               if (route != null) '--route=$route', 
        
               if (platformArgs['trace-startup'] as bool? ?? false) '--trace-startup', 
        
               if (enableImpeller == ImpellerStatus.enabled) '--enable-impeller=true', 
        
               if (enableImpeller == ImpellerStatus.disabled) '--enable-impeller=false', 
        
               if (enableFlutterGpu) '--enable-flutter-gpu', 
        
               if (environmentType == EnvironmentType.physical && deviceVmServicePort != null) 
        
                 '--vm-service-port=$deviceVmServicePort', 
        
               // The simulator "device" is actually on the host machine so no ports will be forwarded. 
        
               // Use the suggested host port. 
        
               if (environmentType == EnvironmentType.simulator && hostVmServicePort != null) 
        
                 '--vm-service-port=$hostVmServicePort', 
        
               // Tell the VM service to listen on all interfaces, don't restrict to the loopback. 
        
               if (interfaceType == DeviceConnectionInterface.wireless) 
        
                 '--vm-service-host=${ipv6 ? '::0' : '0.0.0.0'}', 
        
               if (enableEmbedderApi) '--enable-embedder-api', 
        
             ]; 
        
           }

flutter/engine/src/flutter/shell/common/switches.h

Lines 28 to 297 in b2d4210

    
           DEF_SWITCH(AotSharedLibraryName, 
        
                      "aot-shared-library-name", 
        
                      "Name of the *.so containing AOT compiled Dart assets.") 
        
           DEF_SWITCH(AotVMServiceSharedLibraryName, 
        
                      "aot-vmservice-shared-library-name", 
        
                      "Name of the *.so containing AOT compiled Dart assets for " 
        
                      "launching the service isolate.") 
        
           DEF_SWITCH(SnapshotAssetPath, 
        
                      "snapshot-asset-path", 
        
                      "Path to the directory containing the four files specified by " 
        
                      "VmSnapshotData, VmSnapshotInstructions, " 
        
                      "VmSnapshotInstructions and IsolateSnapshotInstructions.") 
        
           DEF_SWITCH(VmSnapshotData, 
        
                      "vm-snapshot-data", 
        
                      "The VM snapshot data that will be memory mapped as read-only. " 
        
                      "SnapshotAssetPath must be present.") 
        
           DEF_SWITCH(VmSnapshotInstructions, 
        
                      "vm-snapshot-instr", 
        
                      "The VM instructions snapshot that will be memory mapped as read " 
        
                      "and executable. SnapshotAssetPath must be present.") 
        
           DEF_SWITCH(IsolateSnapshotData, 
        
                      "isolate-snapshot-data", 
        
                      "The isolate snapshot data that will be memory mapped as read-only. " 
        
                      "SnapshotAssetPath must be present.") 
        
           DEF_SWITCH(IsolateSnapshotInstructions, 
        
                      "isolate-snapshot-instr", 
        
                      "The isolate instructions snapshot that will be memory mapped as " 
        
                      "read and executable. SnapshotAssetPath must be present.") 
        
           DEF_SWITCH(CacheDirPath, 
        
                      "cache-dir-path", 
        
                      "Path to the cache directory. " 
        
                      "This is different from the persistent_cache_path in embedder.h, " 
        
                      "which is used for Skia shader cache.") 
        
           DEF_SWITCH(ICUDataFilePath, "icu-data-file-path", "Path to the ICU data file.") 
        
           DEF_SWITCH(ICUSymbolPrefix, 
        
                      "icu-symbol-prefix", 
        
                      "Prefix for the symbols representing ICU data linked into the " 
        
                      "Flutter library.") 
        
           DEF_SWITCH(ICUNativeLibPath, 
        
                      "icu-native-lib-path", 
        
                      "Path to the library file that exports the ICU data.") 
        
           DEF_SWITCH(DartFlags, 
        
                      "dart-flags", 
        
                      "Flags passed directly to the Dart VM without being interpreted " 
        
                      "by the Flutter shell.") 
        
           DEF_SWITCH(DeviceVMServiceHost, 
        
                      "vm-service-host", 
        
                      "The hostname/IP address on which the Dart VM Service should " 
        
                      "be served. If not set, defaults to 127.0.0.1 or ::1 depending on " 
        
                      "whether --ipv6 is specified.") 
        
           DEF_SWITCH(DeviceVMServicePort, 
        
                      "vm-service-port", 
        
                      "A custom Dart VM Service port. The default is to pick a randomly " 
        
                      "available open port.") 
        
           DEF_SWITCH( 
        
               DisableVMService, 
        
               "disable-vm-service", 
        
               "Disable the Dart VM Service. The Dart VM Service is never available " 
        
               "in release mode.") 
        
           DEF_SWITCH(DisableVMServicePublication, 
        
                      "disable-vm-service-publication", 
        
                      "Disable mDNS Dart VM Service publication.") 
        
           DEF_SWITCH(IPv6, 
        
                      "ipv6", 
        
                      "Bind to the IPv6 localhost address for the Dart VM Service. " 
        
                      "Ignored if --vm-service-host is set.") 
        
           DEF_SWITCH(EnableDartProfiling, 
        
                      "enable-dart-profiling", 
        
                      "Enable Dart profiling. Profiling information can be viewed from " 
        
                      "Dart / Flutter DevTools.") 
        
           DEF_SWITCH(EndlessTraceBuffer, 
        
                      "endless-trace-buffer", 
        
                      "Enable an endless trace buffer. The default is a ring buffer. " 
        
                      "This is useful when very old events need to viewed. For example, " 
        
                      "during application launch. Memory usage will continue to grow " 
        
                      "indefinitely however.") 
        
           DEF_SWITCH(EnableSoftwareRendering, 
        
                      "enable-software-rendering", 
        
                      "Enable rendering using the Skia software backend. This is useful " 
        
                      "when testing Flutter on emulators. By default, Flutter will " 
        
                      "attempt to either use OpenGL, Metal, or Vulkan.") 
        
           DEF_SWITCH(Route, 
        
                      "route", 
        
                      "Start app with an specific route defined on the framework") 
        
           DEF_SWITCH(SkiaDeterministicRendering, 
        
                      "skia-deterministic-rendering", 
        
                      "Skips the call to SkGraphics::Init(), thus avoiding swapping out " 
        
                      "some Skia function pointers based on available CPU features. This " 
        
                      "is used to obtain 100% deterministic behavior in Skia rendering.") 
        
           DEF_SWITCH(FlutterAssetsDir, 
        
                      "flutter-assets-dir", 
        
                      "Path to the Flutter assets directory.") 
        
           DEF_SWITCH(Help, "help", "Display this help text.") 
        
           DEF_SWITCH(LogTag, "log-tag", "Tag associated with log messages.") 
        
           DEF_SWITCH(DisableServiceAuthCodes, 
        
                      "disable-service-auth-codes", 
        
                      "Disable the requirement for authentication codes for communicating" 
        
                      " with the VM service.") 
        
           DEF_SWITCH(EnableServicePortFallback, 
        
                      "enable-service-port-fallback", 
        
                      "Allow the VM service to fallback to automatic port selection if" 
        
                      " binding to a specified port fails.") 
        
           DEF_SWITCH(StartPaused, 
        
                      "start-paused", 
        
                      "Start the application paused in the Dart debugger.") 
        
           DEF_SWITCH(EnableCheckedMode, "enable-checked-mode", "Enable checked mode.") 
        
           DEF_SWITCH(TraceStartup, 
        
                      "trace-startup", 
        
                      "Trace early application lifecycle. Automatically switches to an " 
        
                      "endless trace buffer.") 
        
           DEF_SWITCH(TraceSkia, 
        
                      "trace-skia", 
        
                      "Trace Skia calls. This is useful when debugging the GPU threed." 
        
                      "By default, Skia tracing is not enabled to reduce the number of " 
        
                      "traced events") 
        
           DEF_SWITCH(TraceSkiaAllowlist, 
        
                      "trace-skia-allowlist", 
        
                      "Filters out all Skia trace event categories except those that are " 
        
                      "specified in this comma separated list.") 
        
           DEF_SWITCH( 
        
               TraceAllowlist, 
        
               "trace-allowlist", 
        
               "Filters out all trace events except those that are specified in this " 
        
               "comma separated list of allowed prefixes.") 
        
           DEF_SWITCH(DumpSkpOnShaderCompilation, 
        
                      "dump-skp-on-shader-compilation", 
        
                      "Automatically dump the skp that triggers new shader compilations. " 
        
                      "This is useful for writing custom ShaderWarmUp to reduce jank. " 
        
                      "By default, this is not enabled to reduce the overhead. ") 
        
           DEF_SWITCH(CacheSkSL, 
        
                      "cache-sksl", 
        
                      "Only cache the shader in SkSL instead of binary or GLSL. This " 
        
                      "should only be used during development phases. The generated SkSLs " 
        
                      "can later be used in the release build for shader precompilation " 
        
                      "at launch in order to eliminate the shader-compile jank.") 
        
           DEF_SWITCH(PurgePersistentCache, 
        
                      "purge-persistent-cache", 
        
                      "Remove all existing persistent cache. This is mainly for debugging " 
        
                      "purposes such as reproducing the shader compilation jank.") 
        
           DEF_SWITCH( 
        
               TraceSystrace, 
        
               "trace-systrace", 
        
               "Trace to the system tracer (instead of the timeline) on platforms where " 
        
               "such a tracer is available. Currently only supported on Android and " 
        
               "Fuchsia.") 
        
           DEF_SWITCH(TraceToFile, 
        
                      "trace-to-file", 
        
                      "Write the timeline trace to a file at the specified path. The file " 
        
                      "will be in Perfetto's proto format; it will be possible to load " 
        
                      "the file into Perfetto's trace viewer.") 
        
           DEF_SWITCH(ProfileMicrotasks, 
        
                      "profile-microtasks", 
        
                      "Enable collection of information about each microtask. Information " 
        
                      "about completed microtasks will be written to the \"Microtask\" " 
        
                      "timeline stream. Information about queued microtasks will be " 
        
                      "accessible from Dart / Flutter DevTools.") 
        
           DEF_SWITCH(UseTestFonts, 
        
                      "use-test-fonts", 
        
                      "Running tests that layout and measure text will not yield " 
        
                      "consistent results across various platforms. Enabling this option " 
        
                      "will make font resolution default to the Ahem test font on all " 
        
                      "platforms (See https://www.w3.org/Style/CSS/Test/Fonts/Ahem/). " 
        
                      "This option is only available on the desktop test shells.") 
        
           DEF_SWITCH(DisableAssetFonts, 
        
                      "disable-asset-fonts", 
        
                      "Prevents usage of any non-test fonts unless they were explicitly " 
        
                      "Loaded via dart:ui font APIs. This option is only available on the " 
        
                      "desktop test shells.") 
        
           DEF_SWITCH(PrefetchedDefaultFontManager, 
        
                      "prefetched-default-font-manager", 
        
                      "Indicates whether the embedding started a prefetch of the " 
        
                      "default font manager before creating the engine.") 
        
           DEF_SWITCH(VerboseLogging, 
        
                      "verbose-logging", 
        
                      "By default, only errors are logged. This flag enabled logging at " 
        
                      "all severity levels. This is NOT a per shell flag and affect log " 
        
                      "levels for all shells in the process.") 
        
           DEF_SWITCH(RunForever, 
        
                      "run-forever", 
        
                      "In non-interactive mode, keep the shell running after the Dart " 
        
                      "script has completed.") 
        
           DEF_SWITCH(DisableDartAsserts, 
        
                      "disable-dart-asserts", 
        
                      "Dart code runs with assertions enabled when the runtime mode is " 
        
                      "debug. In profile and release product modes, assertions are " 
        
                      "disabled. This flag may be specified if the user wishes to run " 
        
                      "with assertions disabled in the debug product mode (i.e. with JIT " 
        
                      "or DBC).") 
        
           DEF_SWITCH(EnableSerialGC, 
        
                      "enable-serial-gc", 
        
                      "On low power devices with low core counts, running concurrent " 
        
                      "GC tasks on threads can cause them to contend with the UI thread " 
        
                      "which could potentially lead to jank. This option turns off all " 
        
                      "concurrent GC activities") 
        
           DEF_SWITCH(DisallowInsecureConnections, 
        
                      "disallow-insecure-connections", 
        
                      "By default, dart:io allows all socket connections. If this switch " 
        
                      "is set, all insecure connections are rejected.") 
        
           DEF_SWITCH(DomainNetworkPolicy, 
        
                      "domain-network-policy", 
        
                      "JSON encoded network policy per domain. This overrides the " 
        
                      "DisallowInsecureConnections switch. Embedder can specify whether " 
        
                      "to allow or disallow insecure connections at a domain level.") 
        
           DEF_SWITCH( 
        
               ForceMultithreading, 
        
               "force-multithreading", 
        
               "Uses separate threads for the platform, UI, GPU and IO task runners. " 
        
               "By default, a single thread is used for all task runners. Only available " 
        
               "in the flutter_tester.") 
        
           DEF_SWITCH(OldGenHeapSize, 
        
                      "old-gen-heap-size", 
        
                      "The size limit in megabytes for the Dart VM old gen heap space.") 
        
           DEF_SWITCH(ResourceCacheMaxBytesThreshold, 
        
                      "resource-cache-max-bytes-threshold", 
        
                      "The max bytes threshold of resource cache, or 0 for unlimited.") 
        
           DEF_SWITCH(EnableImpeller, 
        
                      "enable-impeller", 
        
                      "Enable the Impeller renderer on supported platforms. Ignored if " 
        
                      "Impeller is not supported on the platform.") 
        
           DEF_SWITCH(ImpellerBackend, 
        
                      "impeller-backend", 
        
                      "Requests a particular Impeller backend on platforms that support " 
        
                      "multiple backends. (ex `opengles` or `vulkan`)") 
        
           DEF_SWITCH(EnableVulkanValidation, 
        
                      "enable-vulkan-validation", 
        
                      "Enable loading Vulkan validation layers. The layers must be " 
        
                      "available to the application and loadable. On non-Vulkan backends, " 
        
                      "this flag does nothing.") 
        
           DEF_SWITCH(EnableOpenGLGPUTracing, 
        
                      "enable-opengl-gpu-tracing", 
        
                      "Enable tracing of GPU execution time when using the Impeller " 
        
                      "OpenGLES backend.") 
        
           DEF_SWITCH(EnableVulkanGPUTracing, 
        
                      "enable-vulkan-gpu-tracing", 
        
                      "Enable tracing of GPU execution time when using the Impeller " 
        
                      "Vulkan backend.") 
        
           DEF_SWITCH(LeakVM, 
        
                      "leak-vm", 
        
                      "When the last shell shuts down, the shared VM is leaked by default " 
        
                      "(the leak_vm in VM settings is true). To clean up the leak VM, set " 
        
                      "this value to false.") 
        
           DEF_SWITCH(EnableEmbedderAPI, 
        
                      "enable-embedder-api", 
        
                      "Enable the embedder api. Defaults to false. iOS only.") 
        
           DEF_SWITCH(EnablePlatformIsolates, 
        
                      "enable-platform-isolates", 
        
                      "Enable support for isolates that run on the platform thread.") 
        
           DEF_SWITCH(MergedPlatformUIThread, 
        
                      "merged-platform-ui-thread", 
        
                      "Sets whether the ui thread and platform thread should be merged.") 
        
           // This is a legacy flag that has been superseded by merged-platform-ui-thread. 
        
           // TODO(163064): remove this when users have been migrated. 
        
           DEF_SWITCH(DisableMergedPlatformUIThread, 
        
                      "no-enable-merged-platform-ui-thread", 
        
                      "Merge the ui thread and platform thread.") 
        
           DEF_SWITCH(EnableAndroidSurfaceControl, 
        
                      "enable-surface-control", 
        
                      "Enable the SurfaceControl backed swapchain when supported.") 
        
           DEF_SWITCH(EnableFlutterGPU, 
        
                      "enable-flutter-gpu", 
        
                      "Whether Flutter GPU is enabled.") 
        
           DEF_SWITCH(ImpellerLazyShaderMode, 
        
                      "impeller-lazy-shader-mode", 
        
                      "Whether to defer initialization of all required PSOs for the " 
        
                      "Impeller backend. Defaults to false.") 
        
           DEF_SWITCH(ImpellerAntialiasLines, 
        
                      "impeller-antialias-lines", 
        
                      "Experimental flag to test drawing lines with antialiasing.") 
        
           DEF_SWITCHES_END

Feature flags could hypothetically be passed through to the engine like this too, but it would need to be setup manually for each flag.

The reason you would want to put a setting in the Info.plist rather than as a flag is if you wanted it to persist for the project (get checked into git). Hypothetically with feature flags being able to get added to the pubspec now, that could be another way to do it. Again, feature flags would still need to be passed through to the engine.

The reason you would want to put a setting in the Info.plist rather than as a flag is if you wanted it to persist for the project (get checked into git). Hypothetically with feature flags being able to get added to the pubspec now, that could be another way to do it.

One caveat: this "tool to embedder" approach only works at development time, not at deployment time. For example, the embedder would get the correct value if I do flutter run -d macos, but not if if I flutter build macos and then launch the built app. That's why Impeller and thread merging both went with the platform-specific config option for their opt-outs.

This same concern doesn't apply to the framework's feature flags as the tool uses Dart defines to stamp the feature flags into your Dart application. (The embedder and engine can't use this trick as reading these Dart defines requires launching the Dart isolate).

@matanlurey

I don't understand the question.

There is currently no way to configure the iOS engine using feature flags

@matanlurey By "feature flag" I simply mean a flag to enable or disable things (for example, the 2 code links in my original post). With this info, is the question still confusing?

Recommend using Flutter feature flags over platform-specific configs (#…

Decision flowchart summarizing this conversation:

flowchart TD
    A[Does the embedder need the flag at startup?] -- Yes --> flutterflagsifdevtime
    A -- No --> B
    B[Does the engine need the flag at startup?] -- Yes --> flutterflagsifdevtime
    B -- No --> flutterflags
    flutterflagsifdevtime[Is the flag only for development time?] -- Yes --> flutterflags
    flutterflagsifdevtime -- No --> platformconfig
    flutterflags["Use Flutter's feature flags (flutter config --enable-foo)"]
    platformconfig["Use platform-specific config (Info.plist or AndroidManifest.xml)"]

Decision flowchart summarizing this conversation:

Nice chart! Where do you put systrace flag in this graph?

Recommend using Flutter feature flags over platform-specific configs (f…

Recommend using Flutter feature flags over platform-specific configs …

Navigation Menu

Repository navigation

[ios] guideline on iOS engine feature flags: Info.plist vs cmd flag #172183

Use case

Proposal

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

	List<String> getIOSLaunchArguments(
	EnvironmentType environmentType,
	String? route,
	Map<String, Object?> platformArgs, {
	DeviceConnectionInterface interfaceType = DeviceConnectionInterface.attached,
	bool isCoreDevice = false,
	}) {
	return <String>[
	if (enableDartProfiling) '--enable-dart-profiling',
	if (disableServiceAuthCodes) '--disable-service-auth-codes',
	if (disablePortPublication) '--disable-vm-service-publication',
	if (startPaused) '--start-paused',
	// Wrap dart flags in quotes for physical devices
	if (environmentType == EnvironmentType.physical && dartFlags.isNotEmpty)
	'--dart-flags="$dartFlags"',
	if (environmentType == EnvironmentType.simulator && dartFlags.isNotEmpty)
	'--dart-flags=$dartFlags',
	if (useTestFonts) '--use-test-fonts',
	// Core Devices (iOS 17 devices) are debugged through Xcode so don't
	// include these flags, which are used to check if the app was launched
	// via Flutter CLI and `ios-deploy`.
	if (debuggingEnabled && !isCoreDevice) ...<String>[
	'--enable-checked-mode',
	'--verify-entry-points',
	],
	if (enableSoftwareRendering) '--enable-software-rendering',
	if (traceSystrace) '--trace-systrace',
	if (traceToFile != null) '--trace-to-file="$traceToFile"',
	if (skiaDeterministicRendering) '--skia-deterministic-rendering',
	if (traceSkia) '--trace-skia',
	if (traceAllowlist != null) '--trace-allowlist="$traceAllowlist"',
	if (traceSkiaAllowlist != null) '--trace-skia-allowlist="$traceSkiaAllowlist"',
	if (endlessTraceBuffer) '--endless-trace-buffer',
	if (profileMicrotasks) '--profile-microtasks',
	if (verboseSystemLogs) '--verbose-logging',
	if (purgePersistentCache) '--purge-persistent-cache',
	if (route != null) '--route=$route',
	if (platformArgs['trace-startup'] as bool? ?? false) '--trace-startup',
	if (enableImpeller == ImpellerStatus.enabled) '--enable-impeller=true',
	if (enableImpeller == ImpellerStatus.disabled) '--enable-impeller=false',
	if (enableFlutterGpu) '--enable-flutter-gpu',
	if (environmentType == EnvironmentType.physical && deviceVmServicePort != null)
	'--vm-service-port=$deviceVmServicePort',
	// The simulator "device" is actually on the host machine so no ports will be forwarded.
	// Use the suggested host port.
	if (environmentType == EnvironmentType.simulator && hostVmServicePort != null)
	'--vm-service-port=$hostVmServicePort',
	// Tell the VM service to listen on all interfaces, don't restrict to the loopback.
	if (interfaceType == DeviceConnectionInterface.wireless)
	'--vm-service-host=${ipv6 ? '::0' : '0.0.0.0'}',
	if (enableEmbedderApi) '--enable-embedder-api',
	];
	}

	DEF_SWITCH(AotSharedLibraryName,
	"aot-shared-library-name",
	"Name of the *.so containing AOT compiled Dart assets.")
	DEF_SWITCH(AotVMServiceSharedLibraryName,
	"aot-vmservice-shared-library-name",
	"Name of the *.so containing AOT compiled Dart assets for "
	"launching the service isolate.")
	DEF_SWITCH(SnapshotAssetPath,
	"snapshot-asset-path",
	"Path to the directory containing the four files specified by "
	"VmSnapshotData, VmSnapshotInstructions, "
	"VmSnapshotInstructions and IsolateSnapshotInstructions.")
	DEF_SWITCH(VmSnapshotData,
	"vm-snapshot-data",
	"The VM snapshot data that will be memory mapped as read-only. "
	"SnapshotAssetPath must be present.")
	DEF_SWITCH(VmSnapshotInstructions,
	"vm-snapshot-instr",
	"The VM instructions snapshot that will be memory mapped as read "
	"and executable. SnapshotAssetPath must be present.")
	DEF_SWITCH(IsolateSnapshotData,
	"isolate-snapshot-data",
	"The isolate snapshot data that will be memory mapped as read-only. "
	"SnapshotAssetPath must be present.")
	DEF_SWITCH(IsolateSnapshotInstructions,
	"isolate-snapshot-instr",
	"The isolate instructions snapshot that will be memory mapped as "
	"read and executable. SnapshotAssetPath must be present.")
	DEF_SWITCH(CacheDirPath,
	"cache-dir-path",
	"Path to the cache directory. "
	"This is different from the persistent_cache_path in embedder.h, "
	"which is used for Skia shader cache.")
	DEF_SWITCH(ICUDataFilePath, "icu-data-file-path", "Path to the ICU data file.")
	DEF_SWITCH(ICUSymbolPrefix,
	"icu-symbol-prefix",
	"Prefix for the symbols representing ICU data linked into the "
	"Flutter library.")
	DEF_SWITCH(ICUNativeLibPath,
	"icu-native-lib-path",
	"Path to the library file that exports the ICU data.")
	DEF_SWITCH(DartFlags,
	"dart-flags",
	"Flags passed directly to the Dart VM without being interpreted "
	"by the Flutter shell.")
	DEF_SWITCH(DeviceVMServiceHost,
	"vm-service-host",
	"The hostname/IP address on which the Dart VM Service should "
	"be served. If not set, defaults to 127.0.0.1 or ::1 depending on "
	"whether --ipv6 is specified.")
	DEF_SWITCH(DeviceVMServicePort,
	"vm-service-port",
	"A custom Dart VM Service port. The default is to pick a randomly "
	"available open port.")
	DEF_SWITCH(
	DisableVMService,
	"disable-vm-service",
	"Disable the Dart VM Service. The Dart VM Service is never available "
	"in release mode.")
	DEF_SWITCH(DisableVMServicePublication,
	"disable-vm-service-publication",
	"Disable mDNS Dart VM Service publication.")
	DEF_SWITCH(IPv6,
	"ipv6",
	"Bind to the IPv6 localhost address for the Dart VM Service. "
	"Ignored if --vm-service-host is set.")
	DEF_SWITCH(EnableDartProfiling,
	"enable-dart-profiling",
	"Enable Dart profiling. Profiling information can be viewed from "
	"Dart / Flutter DevTools.")
	DEF_SWITCH(EndlessTraceBuffer,
	"endless-trace-buffer",
	"Enable an endless trace buffer. The default is a ring buffer. "
	"This is useful when very old events need to viewed. For example, "
	"during application launch. Memory usage will continue to grow "
	"indefinitely however.")
	DEF_SWITCH(EnableSoftwareRendering,
	"enable-software-rendering",
	"Enable rendering using the Skia software backend. This is useful "
	"when testing Flutter on emulators. By default, Flutter will "
	"attempt to either use OpenGL, Metal, or Vulkan.")
	DEF_SWITCH(Route,
	"route",
	"Start app with an specific route defined on the framework")
	DEF_SWITCH(SkiaDeterministicRendering,
	"skia-deterministic-rendering",
	"Skips the call to SkGraphics::Init(), thus avoiding swapping out "
	"some Skia function pointers based on available CPU features. This "
	"is used to obtain 100% deterministic behavior in Skia rendering.")
	DEF_SWITCH(FlutterAssetsDir,
	"flutter-assets-dir",
	"Path to the Flutter assets directory.")
	DEF_SWITCH(Help, "help", "Display this help text.")
	DEF_SWITCH(LogTag, "log-tag", "Tag associated with log messages.")
	DEF_SWITCH(DisableServiceAuthCodes,
	"disable-service-auth-codes",
	"Disable the requirement for authentication codes for communicating"
	" with the VM service.")
	DEF_SWITCH(EnableServicePortFallback,
	"enable-service-port-fallback",
	"Allow the VM service to fallback to automatic port selection if"
	" binding to a specified port fails.")
	DEF_SWITCH(StartPaused,
	"start-paused",
	"Start the application paused in the Dart debugger.")
	DEF_SWITCH(EnableCheckedMode, "enable-checked-mode", "Enable checked mode.")
	DEF_SWITCH(TraceStartup,
	"trace-startup",
	"Trace early application lifecycle. Automatically switches to an "
	"endless trace buffer.")
	DEF_SWITCH(TraceSkia,
	"trace-skia",
	"Trace Skia calls. This is useful when debugging the GPU threed."
	"By default, Skia tracing is not enabled to reduce the number of "
	"traced events")
	DEF_SWITCH(TraceSkiaAllowlist,
	"trace-skia-allowlist",
	"Filters out all Skia trace event categories except those that are "
	"specified in this comma separated list.")
	DEF_SWITCH(
	TraceAllowlist,
	"trace-allowlist",
	"Filters out all trace events except those that are specified in this "
	"comma separated list of allowed prefixes.")
	DEF_SWITCH(DumpSkpOnShaderCompilation,
	"dump-skp-on-shader-compilation",
	"Automatically dump the skp that triggers new shader compilations. "
	"This is useful for writing custom ShaderWarmUp to reduce jank. "
	"By default, this is not enabled to reduce the overhead. ")
	DEF_SWITCH(CacheSkSL,
	"cache-sksl",
	"Only cache the shader in SkSL instead of binary or GLSL. This "
	"should only be used during development phases. The generated SkSLs "
	"can later be used in the release build for shader precompilation "
	"at launch in order to eliminate the shader-compile jank.")
	DEF_SWITCH(PurgePersistentCache,
	"purge-persistent-cache",
	"Remove all existing persistent cache. This is mainly for debugging "
	"purposes such as reproducing the shader compilation jank.")
	DEF_SWITCH(
	TraceSystrace,
	"trace-systrace",
	"Trace to the system tracer (instead of the timeline) on platforms where "
	"such a tracer is available. Currently only supported on Android and "
	"Fuchsia.")
	DEF_SWITCH(TraceToFile,
	"trace-to-file",
	"Write the timeline trace to a file at the specified path. The file "
	"will be in Perfetto's proto format; it will be possible to load "
	"the file into Perfetto's trace viewer.")
	DEF_SWITCH(ProfileMicrotasks,
	"profile-microtasks",
	"Enable collection of information about each microtask. Information "
	"about completed microtasks will be written to the \"Microtask\" "
	"timeline stream. Information about queued microtasks will be "
	"accessible from Dart / Flutter DevTools.")
	DEF_SWITCH(UseTestFonts,
	"use-test-fonts",
	"Running tests that layout and measure text will not yield "
	"consistent results across various platforms. Enabling this option "
	"will make font resolution default to the Ahem test font on all "
	"platforms (See https://www.w3.org/Style/CSS/Test/Fonts/Ahem/). "
	"This option is only available on the desktop test shells.")
	DEF_SWITCH(DisableAssetFonts,
	"disable-asset-fonts",
	"Prevents usage of any non-test fonts unless they were explicitly "
	"Loaded via dart:ui font APIs. This option is only available on the "
	"desktop test shells.")
	DEF_SWITCH(PrefetchedDefaultFontManager,
	"prefetched-default-font-manager",
	"Indicates whether the embedding started a prefetch of the "
	"default font manager before creating the engine.")
	DEF_SWITCH(VerboseLogging,
	"verbose-logging",
	"By default, only errors are logged. This flag enabled logging at "
	"all severity levels. This is NOT a per shell flag and affect log "
	"levels for all shells in the process.")
	DEF_SWITCH(RunForever,
	"run-forever",
	"In non-interactive mode, keep the shell running after the Dart "
	"script has completed.")
	DEF_SWITCH(DisableDartAsserts,
	"disable-dart-asserts",
	"Dart code runs with assertions enabled when the runtime mode is "
	"debug. In profile and release product modes, assertions are "
	"disabled. This flag may be specified if the user wishes to run "
	"with assertions disabled in the debug product mode (i.e. with JIT "
	"or DBC).")
	DEF_SWITCH(EnableSerialGC,
	"enable-serial-gc",
	"On low power devices with low core counts, running concurrent "
	"GC tasks on threads can cause them to contend with the UI thread "
	"which could potentially lead to jank. This option turns off all "
	"concurrent GC activities")
	DEF_SWITCH(DisallowInsecureConnections,
	"disallow-insecure-connections",
	"By default, dart:io allows all socket connections. If this switch "
	"is set, all insecure connections are rejected.")
	DEF_SWITCH(DomainNetworkPolicy,
	"domain-network-policy",
	"JSON encoded network policy per domain. This overrides the "
	"DisallowInsecureConnections switch. Embedder can specify whether "
	"to allow or disallow insecure connections at a domain level.")
	DEF_SWITCH(
	ForceMultithreading,
	"force-multithreading",
	"Uses separate threads for the platform, UI, GPU and IO task runners. "
	"By default, a single thread is used for all task runners. Only available "
	"in the flutter_tester.")
	DEF_SWITCH(OldGenHeapSize,
	"old-gen-heap-size",
	"The size limit in megabytes for the Dart VM old gen heap space.")

	DEF_SWITCH(ResourceCacheMaxBytesThreshold,
	"resource-cache-max-bytes-threshold",
	"The max bytes threshold of resource cache, or 0 for unlimited.")
	DEF_SWITCH(EnableImpeller,
	"enable-impeller",
	"Enable the Impeller renderer on supported platforms. Ignored if "
	"Impeller is not supported on the platform.")
	DEF_SWITCH(ImpellerBackend,
	"impeller-backend",
	"Requests a particular Impeller backend on platforms that support "
	"multiple backends. (ex `opengles` or `vulkan`)")
	DEF_SWITCH(EnableVulkanValidation,
	"enable-vulkan-validation",
	"Enable loading Vulkan validation layers. The layers must be "
	"available to the application and loadable. On non-Vulkan backends, "
	"this flag does nothing.")
	DEF_SWITCH(EnableOpenGLGPUTracing,
	"enable-opengl-gpu-tracing",
	"Enable tracing of GPU execution time when using the Impeller "
	"OpenGLES backend.")
	DEF_SWITCH(EnableVulkanGPUTracing,
	"enable-vulkan-gpu-tracing",
	"Enable tracing of GPU execution time when using the Impeller "
	"Vulkan backend.")
	DEF_SWITCH(LeakVM,
	"leak-vm",
	"When the last shell shuts down, the shared VM is leaked by default "
	"(the leak_vm in VM settings is true). To clean up the leak VM, set "
	"this value to false.")
	DEF_SWITCH(EnableEmbedderAPI,
	"enable-embedder-api",
	"Enable the embedder api. Defaults to false. iOS only.")
	DEF_SWITCH(EnablePlatformIsolates,
	"enable-platform-isolates",
	"Enable support for isolates that run on the platform thread.")
	DEF_SWITCH(MergedPlatformUIThread,
	"merged-platform-ui-thread",
	"Sets whether the ui thread and platform thread should be merged.")
	// This is a legacy flag that has been superseded by merged-platform-ui-thread.
	// TODO(163064): remove this when users have been migrated.
	DEF_SWITCH(DisableMergedPlatformUIThread,
	"no-enable-merged-platform-ui-thread",
	"Merge the ui thread and platform thread.")
	DEF_SWITCH(EnableAndroidSurfaceControl,
	"enable-surface-control",
	"Enable the SurfaceControl backed swapchain when supported.")
	DEF_SWITCH(EnableFlutterGPU,
	"enable-flutter-gpu",
	"Whether Flutter GPU is enabled.")
	DEF_SWITCH(ImpellerLazyShaderMode,
	"impeller-lazy-shader-mode",
	"Whether to defer initialization of all required PSOs for the "
	"Impeller backend. Defaults to false.")
	DEF_SWITCH(ImpellerAntialiasLines,
	"impeller-antialias-lines",
	"Experimental flag to test drawing lines with antialiasing.")
	DEF_SWITCHES_END

[ios] guideline on iOS engine feature flags: Info.plist vs cmd flag #172183

Description

Use case

Proposal

Activity

jmagman commented on Jul 17, 2025

matanlurey commented on Jul 17, 2025

loic-sharma commented on Jul 17, 2025

vashworth commented on Jul 17, 2025

loic-sharma commented on Jul 17, 2025

hellohuanlin commented on Jul 18, 2025

loic-sharma commented on Jul 19, 2025

hellohuanlin commented on Jul 22, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions