Android Platform Embedder

Android embedder for Flutter, including Java io.flutter sources and Android specific engine-side C++.

This code provides the glue between the Flutter engine and the Android platform, and is responsible for:

  • Initializing the Flutter engine.
  • Providing a platform view for the Flutter engine to render into.
  • Dispatching events to the Flutter engine.

[!CAUTION] This is a best effort attempt to document the Android embedder. It is not guaranteed to be up to date or complete. If you find a discrepancy, please send a pull request!

See also:

Testing

There are two classes of tests for the Android embedder: unit tests that tend to test contracts within the embedder, and integration tests that test the engine and embedder together, typically coupled with a Flutter app (that's how our users interact with the engine and embedder).

Unit tests

Unit tests for the Android embedder are located in:

The easiest way (though not the quickest) is to use run_tests.py:

# Assuming you're at the root of the engine repo where `run_tests.py` is located.
./testing/run_tests.py --type java

# Confusingly, these are C++ tests for Android.
./testing/run_tests.py --type android

# If you're using android_debug_unopt_arm64 builds:
./testing/run_tests.py --type android --android-variant android_debug_unopt_arm64
./testing/run_tests.py --type java --android-variant android_debug_unopt_arm64

You may also be able to run the tests directly from Android Studio.

Integration tests

Integration tests for the Android embedder mostly exist outside of the engine for dubious historical reasons.

To run these tests, you'll need to have a Flutter checkout and a working Android emulator or device:

# Build an up-to-date Flutter engine for Android.
cd $ENGINE/src

# Or, use your favorite arguments and build variant.
ninja -j1000 -C ../out/android_debug_unopt_arm64 android_jar

# Run the tests. Here is *1* example:
cd $FLUTTER/dev/integration_tests/external_textures
flutter drive \
  --local-engine-host=$ENGINE/out/host_debug_unopt_arm64 \
  --local-engine=$ENGINE/out/android_debug_unopt_arm64

Another good source of (unfortunately, manual) testing is flutter/packages:

cd $PACKAGES/packages/video_player/video_player_android/example
flutter run \
  --local-engine-host=$ENGINE/out/host_debug_unopt_arm64 \
  --local-engine=$ENGINE/out/android_debug_unopt_arm64

[!NOTE] External texture rendering on Android is based on the device API level. For example to test the OpenGLES branch (which uses SurfaceTexture), you'll typically need an older device or emulator with an API version 29 or lower.

You can also (locally) “force” the engine to use SurfaceTextures:

// shell/platform/android/io/flutter/embedding/engine/renderer/FlutterRenderer.java
-  @VisibleForTesting static boolean debugForceSurfaceProducerGlTextures = false;
+  @VisibleForTesting static boolean debugForceSurfaceProducerGlTextures = true;

... and rebuild the engine.

See our wiki also.

Developing

How to edit and contribute to the Android embedder.

[!TIP] This guide assumes you already have a working Engine development environment:

You should also have a working Android development environment:

It is also recommended (but not required) to install Visual Studio Code.

Depending on what you are trying to do, you may need to edit the Java code in io.flutter or the C++ code in shell/platform/android, sometimes both. Let's start with the C++ code, as it is more similar to developing for other platforms or platform-agnostic parts of the engine.

Editing C++ code

The C++ code for the Android embedder is located in shell/platform/android and subdirectories.

Some notable files include:

See VSCode with C/C++ Intellisense for how to use the clangd extension to get C++ code completion:

Example

[!NOTE] --compile-commands-dir must point to an Android build output:

{
  /* ... */
  "clangd.path": "buildtools/mac-arm64/clang/bin/clangd",
  "clangd.arguments": ["--compile-commands-dir=out/android_debug_unopt_arm64"]
  /* ... */
}

... but remember to change it back when editing other parts of the engine.

Editing Java code

The Java code for the Android embedder is located in io/flutter/ and subdirectories.

The tests are located in test/io/flutter/, and the test runner in test_runner.

Some notable files include:

It is non-trivial to get a working IDE setup for editing Java code in the Flutter engine. Some developers have had success using VSCode as an IDE for the Android Embedding, but the following instructions are for if that doesn't work, or you want to use Android Studio:

  1. Open shell/platform/android in Android Studio.

  2. Configure the following:

  3. Sync Gradle.

    Example

At this point you should be able to open Java files in Android Studio and get code completion in the io/flutter and test/io/flutter folders. For example, FlutterJNI.java:

Example

To get code coverage displayed in line: go to the test class you wish to run and

  1. Right click > Modify Run Configuration...,
  2. In the window that pops up click Modify options > Specify classes and packages (under “code coverage”).
  3. In the new box that appears at the bottom of the window, click the + > Add package, and then add io.flutter.*.