Contributing to the Flutter engine

See also: Flutter's code of conduct


For an introduction to contributing to Flutter, see our contributor guide.

For specific instructions regarding building Flutter's engine, see Setting up the Engine development environment on our wiki. Those instructions are part of the broader onboarding instructions described in the contributing guide.


The Flutter engine generally follows Google style for the languages it uses, with some exceptions.


Follows the Google C++ Style Guide and is automatically formatted with clang-format.

Some additional considerations that are in compliance with the style guide, but are worth noting:

Judiciously use shared_ptr

The engine currently (as of 2024-05-15) uses shared_ptr liberally, which can be expensive to copy, and is not always necessary.

The C++ style guide has a section on ownership and smart pointers worth reading:

Do not design your code to use shared ownership without a very good reason. One such reason is to avoid expensive copy operations, but you should only do this if the performance benefits are significant, and the underlying object is immutable.

Prefer using std::unique_ptr when possible.

Judiciously use auto

The C++ style guide has a section on type deduction that is worth reading:

The fundamental rule is: use type deduction only to make the code clearer or safer, and do not use it merely to avoid the inconvenience of writing an explicit type. When judging whether the code is clearer, keep in mind that your readers are not necessarily on your team, or familiar with your project, so types that you and your reviewer experience as unnecessary clutter will very often provide useful information to others. For example, you can assume that the return type of make_unique<Foo>() is obvious, but the return type of MyWidgetFactory() probably isn't.

Due to our codebase's extensive use of shared_ptr, auto can have surprising performance implications. See #49801 for an example.

Linux Embedding

The Linux embedding instead follows idiomatic GObject-based C style.

Use of C++ in the Linux embedding is discouraged in that embedding to avoid creating hybrid code that feels unfamiliar to either developers used to working with GObject or C++ developers.

For example, do not use STL collections or std::string, but do:

  • Use C++ casts (C-style casts are forbidden).
  • Use nullptr rather than NULL.
  • Avoid #define; for internal constants use static constexpr instead.


The Flutter engine intends to follow the Dart style guide but currently follows the Flutter style guide, with the following exceptions:

Use of type inference is allowed

The Dart style guide only requires explicit types when type inference is not possible, but the Flutter style guide always requires explicit types. The engine is moving towards the Dart style guide, but this is a gradual process. In the meantime, follow these guidelines:

  • Always annotate when inference is not possible.
  • Prefer annotating when inference is possible but the type is not obvious.

Some cases when using var/final/const is appropriate:

  • When the type is obvious from the right-hand side of the assignment:

    // Capitalized constructor name always returns a Foo.
    var foo = Foo();
    // Similar with factory constructors.
    var bar = Bar.create();
    // Literals (strings, numbers, lists, maps, etc) always return the same type.
    var name = 'John Doe';
    var flag = true;
    var numbers = [1, 2, 3];
    var map = {'one': 1, 'two': 2, 'three': 3};
  • When the type is obvious from the method name:

    // toString() always returns a String.
    var string = foo().toString();
    // It's reasonable to assume that length returns an int.
    var length = string.length;
  • When the type is obvious from the context:

    // When variables are in the same scope, reduce() clearly returns an int.
    var list = [1, 2, 3];
    var sum = list.reduce((a, b) => a + b);

Some cases where an explicit type should be considered:

  • When the type is not obvious from the right-hand side of the assignment:

    // What does 'fetchLatest()' return?
    ImageBuffer buffer = fetchLatest();
    // What does this large chain of method calls return?
    Iterable<int> numbers = foo().bar().map((b) => b.baz());
  • When there are semantic implications to the type:

    // Without 'num', the map would be inferred as 'Map<String, int>'.
    const map = <String, num>{'one': 1, 'two': 2, 'three': 3};
  • Or, when a reviewer requests it!

    Remember that the goal is to make the code more readable and maintainable, and explicit types can help with that. Code can be changed, so it's always possible to add or remove type annotations later as the code evolves, so avoid bikeshedding over this.


Follows the Google Java Style Guide and is automatically formatted with google-java-format.


Follows the Google Objective-C Style Guide, including for Objective-C++ and is automatically formatted with clang-format.


Follows the Google Python Style Guide and is automatically formatted with yapf.

[!WARNING] Historically, the engine grew a number of one-off Python scripts, often as part of the testing or build infrastructure (i.e. command-line tools). We are instead moving towards using Dart for these tasks, so new Python scripts should be avoided whenever possible.


Automatically formatted with gn format.


The testing policy for contributing to the flutter engine can be found at the Tree Hygiene Wiki. The summary is that all PR's to the engine should be tested or have an explicit test exemption.

Because the engine targets multiple platforms the testing infrastructure is fairly complicated. Here are some more resources to help guide writing tests:

  • Testing the engine wiki - A guide on writing tests for the engine including an overview of the different tests and the different technologies the engine uses.
  • //testing - This is where the script is located. All tests will have the ability to be executed with
  • //ci/builders - The JSON files that determine how tests are executed on CI.

Tests will be executed on CI, but some tests will be executed before PR's can be merged (presubmit) and others after they have been merged (postsubmit). Ideally everything would be presubmit but tests that take up more resources are executed in postsubmit.

Skia Gold

The Flutter engine uses Skia Gold for image comparison tests which fail if:

  • The image is different from an accepted baseline.
  • An image is not uploaded but is expected to be (see dir_contents_diff).

Any untriaged failures will block presubmit and postsubmit tests.

Example invocation

# Configure host build for macOS arm64 debug.
$ flutter/tools/gn --runtime-mode=debug --unoptimized --no-lto --mac-cpu=arm64
# Compile default targets (should cover all applicable requirements).
$ ninja -j100 -C out/host_debug_unopt_arm64
# Run all cross-platform C++ tests for the debug build arm64 variant.
$ cd flutter/testing
$ ./ --variant=host_debug_unopt_arm64 --type=engine

Directory typeDescription
feltn/aThe test runner for flutter web. See //lib/web_ui
flutter_testerdartLauncher for engine dart tests.
fml_unittestsengineUnit tests for //fml
impeller_golden_testsengine(mac)Generates golden images for impeller (vulkan, metal, opengles).
impeller_unittestsengineimpeller unit tests and interactive tests
ios_test_flutterobjcdynamic library of objc tests to be run with XCTest
jni_unittestsengine(not windows)
platform_view_android_delegate_unittestsengine(not windows)
shell_unittestsengine(not windows)
scenario_appandroidIntegration and golden tests for Android, iOS
tonic_unittestsengineUnit tests for //third_party/tonic

Fuchsia Contributions from Googlers

Googlers contributing to Fuchsia should follow the additional steps at: go/flutter-fuchsia-pr-policy.