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:

• ../../tools/android_lint/bin/main.dart
• Android Platform Views
• Hosting native Android views in your Flutter app with Platform Views
• Testing Android Changes in the Devicelab on an Emulator
• Texture Layer Hybrid Composition

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:

• test: Java unit tests.
• C++ files that end in _unittests.cc in shell/platform/android.

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:

• Setting up the Engine development environment
• Compiling for Android

You should also have a working Android development environment:

• Android Studio
• Install Flutter > Test Drive

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:

• context/android_context.h: Holds state that is shared across Android surfaces.
• jni/platform_view_android_jni.h: Allows calling Java code running in the JVM.
• AndroidManifest.xml: Used by android_lint.
• BUILD.gn: Used by GN to build the C++-side embedder tests and the flutter.jar file for the engine.
• ndk_helpers.h: Helper functions for dynamically loading and calling Android NDK (C/C++) functions.
• platform_view_android.h: The main entry point for the Android embedder.

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

[!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:

• io/flutter/embedding/android/FlutterActivity.java: An activity that displays a full-screen Flutter UI.
• io/flutter/embedding/engine/FlutterJNI.java: The Java interface for the C++ engine.
• io/flutter/view/TextureRegistry.java: Registry of backend textures used by a Flutter View.

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:

   • Preferences | Build, Execution, Deployment | Gradle-Android Compiler

     Command-line Options:

     -Pbuild_dir="/tmp/build_dir" -Pflutter_jar="$ENGINE/src/out/android_debug_unopt_arm64/flutter.jar"
     

   • Preferences | Build, Execution, Deployment | Build Tools | Gradle

     Distribution of Local Installation with:

     $ENGINE/src/third_party/gradle
     

     Gradle SDK using Android Studio (path depends on your machine):

     /Applications/Android Studio.app/Contents/jbr/Contents/Home
     

3. Sync Gradle.

   

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:

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.*.