Overview

Re-lands #181632 which TLDR does the following:

Same old same old changes from original PR

• Refactors all engine flags recognized by the Flutter Android embedding (specifically those previously recognized by FlutterShellArgs and all of those used to initialize the engine in FlutterLoader) into a new class FlutterEngineFlags (FlutterShellArgs is kept for now to maintain backwards compatibility; see Android app using firebase_messaging package fails to build because of missing FlutterShellArgs.fromIntent symbol #182153 for details)
• Adds the ability to set engine flags (that are recognized by FlutterEngineFlags) via the manifest
• Adds warnings for developers that set engine flags via Intents as this will be disabled as part of [Android] Remove the ability to set engine shell arguments via Intent extras #180686.
• Disallows debug/test only flags in release mode

New changes/fixes

• [Critical change] To fix the bug caught by b/483299339, --merged-platform-ui-thread flag is added to FlutterEngineFlags
• [Behavior change, not critical] To avoid more bugs like b/483299339, FlutterLoader allows unrecognized flags specified by the command line or Intent extras to be used to initialize the engine for now (same behavior as before my original change but I plan to secure this in the future; see [Android] Only allow known engine flags specified on the command line #182557)
• [Small refactor] To speed up manifest argument processing time, FlutterLoader loops through all recognized FlutterEngineFlags to check if they are present in an application's manifest versus looping through all metadata in an application's manifest and looking for recognized FlutterEngineFlags (small improvement for apps with large manifests)
• [Small refactor] To speed up command line argument processing time, FlutterLoader processes the --aot-shared-library-name flag in the same loop as the other flags, reducing the number of loops ensureInitializationComplete has to do (minimal improvement perf-wise but kept it in because it's more readable to me)

Full description

(Mostly copied from #181632)

Adds a mechanism for setting Android engine flags via the manifest. If a flag is specified on the command line and in manifest metadata, the value specified on the command line will take precedence. Documentation is added on this mechanism

Additionally, this PR removes the exposure of--cache-sksl command line flag as per https://github.com/flutter/flutter/issues/140310#issuecomment-2708459007.

Additionally, this PR adds documentation for the only two supported ways of setting engine flags moving forward -- via the command line or manifest. The Intent mechanism will be removed when #180686 is completed (intended to be a follow up to this PR).

As the unit tests in this PR only cover setting flags via manifest in debug mode, I will follow up this PR with an integration test to test that flags are appropriately respected/ignored in release mode. See #178383 for my currently working but WIP draft.

Part of #172553.

Follow up work:

• Migrate flags all un-migrated flags FlutterEngineFlags [Android] Migrate content sizing and HCPP flags to FlutterEngineFlags #182852
• Add integration test for this new added mechanism. This will land as an immediate follow-up to this PR. WIP in [Android] Add integration test for setting engine flags via the manifest #182241.
• Remove support for setting shell arguments via Intent. This task will be a follow up to this work + the integration test landing, and will complete work for Harden FlutterFragment and FlutterActivity by restricting how flags are set (especially in release mode) #172553. See [Android] Remove the ability to set engine shell arguments via Intent extras #180686 for details.
• Only allow known engine flags to be passed to the engine. This is more of a P2 but would be a nice additional security feature; see [Android] Only allow known engine flags specified on the command line #182557.

Pre-launch Checklist

• I read the Contributor Guide and followed the process outlined there for submitting PRs.
• I read the Tree Hygiene wiki page, which explains my responsibilities.
• I read and followed the Flutter Style Guide, including Features we expect every widget to implement.
• I signed the CLA.
• I listed at least one issue that this PR fixes in the description above.
• I updated/added relevant documentation (doc comments with ///).
• I added new tests to check the change I am making, or this PR is test-exempt.
• I followed the breaking change policy and added Data Driven Fixes where supported.
• All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel on Discord.

Note: The Flutter team is currently trialing the use of Gemini Code Assist for GitHub. Comments from the gemini-code-assist bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.