Skip to content

Latest commit

 

History

History
131 lines (105 loc) · 8.37 KB

CONTRIBUTING.md

File metadata and controls

131 lines (105 loc) · 8.37 KB
Raw

Contributing to the Flutter engine

See also: Flutter's code of conduct

Welcome

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.

Style

The Flutter engine follows Google style for the languages it uses:

  • C++
    • Note: The Linux embedding generally follows idiomatic GObject-based C style. Use of C++ 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. Exceptions:
      • C-style casts are forbidden; use C++ casts.
      • Use nullptr rather than NULL.
      • Avoid #define; for internal constants use static constexpr instead.
  • Objective-C (including Objective-C++)
  • Java

C/C++ and Objective-C/C++ files are formatted with clang-format, and GN files with gn format.

Testing

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 run_tests.py script is located. All tests will have the ability to be executed with run_tests.py.
  • //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 run_tests.py 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 run_tests.py requirements).
$ ninja -j100 -C out/host_debug_unopt_arm64
# Run all cross-platform C++ tests for the debug build arm64 variant.
$ cd flutter/testing
$ ./run_tests.py --variant=host_debug_unopt_arm64 --type=engine

Directory

Name run_tests.py type Description
accessibility_unittests engine
client_wrapper_glfw_unittests engine
client_wrapper_unittests engine
common_cpp_core_unittests engine
common_cpp_unittests engine
dart_plugin_registrant_unittests engine
display_list_rendertests engine
display_list_unittests engine
embedder_a11y_unittests engine
embedder_proctable_unittests engine
embedder_unittests engine
felt n/a The test runner for flutter web. See //lib/web_ui
flow_unittests engine
flutter_tester dart Launcher for engine dart tests.
fml_arc_unittests engine
fml_unittests engine Unit tests for //fml
framework_common_unittests engine(mac)
gpu_surface_metal_unittests engine(mac)
impeller_dart_unittests engine
impeller_golden_tests engine(mac) Generates golden images for impeller (vulkan, metal, opengles).
impeller_unittests engine impeller unit tests and interactive tests
ios_test_flutter objc dynamic library of objc tests to be run with XCTest
jni_unittests engine(not windows)
no_dart_plugin_registrant_unittests engine
platform_view_android_delegate_unittests engine(not windows)
runtime_unittests engine
shell_unittests engine(not windows)
scenario_app android Integration and golden tests for Android, iOS
testing_unittests engine
tonic_unittests engine Unit tests for //third_party/tonic
txt_unittests engine(linux)
ui_unittests engine

Fuchsia Contributions from Googlers

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