See also: Flutter's code of conduct
This guide introduces you to building and contributing to the Flutter engine. For an introduction to contributing to the Flutter framework, see the equivalent document in the framework's repository.
If you have previously built the engine (i.e. your environment is already setup) and just want a refresher, then feel free to skip to one of the following sections:
Otherwise, begin from the next section, which will help you prepare your environment.
gclient
tool from depot_tools.gclient sync
).You do not need Dart installed, as a Dart tool chain is automatically downloaded as part of the “getting the code” step. Similarly for the Android SDK, it's downloaded by the gclient sync
step below.
https://github.com/flutter/engine
into your own GitHub account. If you already have a fork, and are now installing a development environment on a new machine, make sure you‘ve updated your fork so that you don’t use stale configuration options from long ago. Do not use git clone
to check out this repository; gclient
will do it for you.engine
: some of the tools assume this name when working across repositories. (They can be configured to use other names too, so this isn't a strict requirement.).gclient
file in the engine
directory with the following contents, replacing <your_name_here>
with your GitHub account name:solutions = [ { "managed": False, "name": "src/flutter", "url": "git@github.com:<your_name_here>/engine.git", "custom_deps": {}, "deps_file": "DEPS", "safesync_url": "", }, ]
cd engine
(Change to the directory in which you put the .gclient
file.)gclient sync
This will fetch all the source code that Flutter depends on. Avoid interrupting this script, it can leave your repository in an inconsistent state that is tedious to clean up. (This step automatically runs git clone
, among other things.)cd src/flutter
(Change to the flutter
directory of the src
directory that gclient sync
created in your engine
directory.)git remote add upstream git@github.com:flutter/engine.git
(So that you fetch from the master flutter/engine
repository, not your clone, when running git fetch
et al.)cd ..
(Return to the src
directory that gclient sync
created in your engine
directory.)sudo ./build/install-build-deps-android.sh
sudo ./build/install-build-deps.sh
ant
: brew install ant
src
directory to update your git remotes accordingly:git remote rename origin upstream git remote add origin git@github.com:<your_name_here>/buildroot.git
Most developers will use the flutter
tool in the main Flutter repository for interacting with their built flutter/engine. To do so, the flutter
tool accepts two global parameters local-engine-src-path
and local-engine
, a typical invocation would be: --local-engine-src-path /path/to/engine/src --local-engine=android_debug_unopt
.
Additionally if you‘ve modified dart sources in flutter/engine
, you’ll need to add a dependency_overrides
section to point to your modified package:sky_engine
and package:sky_services
to the pubspec.yaml
for the flutter app you're using the custom engine with. A typical example would be:
dependency_overrides: sky_engine: path: /path/to/flutter/engine/out/host_debug/gen/dart-pkg/sky_engine sky_services: path: /path/to/flutter/engine/out/host_debug/gen/dart-pkg/sky_services
Depending on the platform you choose below, you will need to replace host_debug
with the appropriate directory.
Run the following steps, from the src
directory created in the steps above:
git pull upstream master
in src/flutter
gclient sync
./flutter/tools/gn --android --unoptimized
for device-side executables./flutter/tools/gn --android --android-cpu x86 --unoptimized
for x86 emulators./flutter/tools/gn --android --android-cpu x64 --unoptimized
for x64 emulators./flutter/tools/gn --unoptimized
for host-side executablesninja -C out/android_debug_unopt
for device-side executablesninja -C out/android_debug_unopt_x86
for x86 emulatorsninja -C out/android_debug_unopt_x64
for x64 emulatorsninja -C out/host_debug_unopt
for host-side executablesninja -C out/android_debug_unopt && ninja -C out/host_debug_unopt
-j 1000
to parallelize the build using Goma.This builds a debug-enabled (“unoptimized”) binary configured to run Dart in checked mode (“debug”). There are other versions, discussed on the wiki.
To run an example with your locally built binary, you'll also need to clone the main Flutter repository. See the instructions for contributing to the main Flutter repository for detailed instructions. For your convenience, the engine
and flutter
directories should be in the same parent directory.
Once you‘ve got everything set up, you can run an example using your locally built engine by switching to that example’s directory, running pub get
to make sure its dependencies have been downloaded, and using flutter run
with an explicit --local-engine-src-path
pointing at the engine/src
directory. Make sure you have a device connected over USB and debugging enabled on that device:
cd /path/to/flutter/examples/hello_world
../../bin/flutter run --local-engine-src-path /path/to/engine/src --local-engine=android_debug_unopt
or --local-engine=android_debug_unopt_x64
If you put the engine
and flutter
directories side-by-side, you can skip the tedious --local-engine-src-path
option and the flutter
tool will automatically determine the path.
You can also specify a particular Dart file to run if you want to run an example that doesn't have a lib/main.dart
file using the -t
command-line option. For example, to run the tabs.dart
example in the examples/widgets
directory on a connected Android device, from that directory you would run:
flutter run --local-engine=android_debug_unopt -t tabs.dart
If you're going to be debugging crashes in the engine, make sure you add android:debuggable="true"
to the <application>
element in the android/AndroidManifest.xml
file for the Flutter app you are using to test the engine.
git pull upstream master
in src/flutter
to update the Flutter Engine repo.gclient sync
to update dependencies../flutter/tools/gn --ios --unoptimized
to prepare build files for device-side executables (or --ios --simulator --unoptimized
for simulator).out/ios_debug_unopt
./flutter/tools/gn --unoptimized
to prepare the build files for host-side executables.ninja -C out/ios_debug_unopt && ninja -C out/host_debug_unopt
to build all artifacts (use out/ios_debug_sim_unopt
for Simulator).-j 1000
to parallelize the build using Goma.Once the artifacts are built, you can start using them in your application by following these steps:
cd /path/to/flutter/examples/hello_world
../../bin/flutter run --local-engine-src-path /path/to/engine/src --local-engine=ios_debug_unopt
or --local-engine=ios_debug_sim_unopt
for simulatorLLDB
debugger from Xcode
by opening ios/Runner.xcworkspace
and starting the application by clicking the Run button (CMD + R).ios/Runner.xcworkspace
, expand Flutter->Runner->Supporting Files->main.m in the Runner project. Put a breakpoint in main() then set your desired breakpoint in the engine in lldb via breakpoint set -...
.To run the tests, you should first clone the main Flutter repository. See the instructions for contributing to the main Flutter repository for detailed instructions. By default, Flutter will use the bundled version of the engine. Follow the next steps to run tests using the locally-built engine:
git pull upstream master
in src/flutter
to update the Flutter Engine repo.gclient sync
to update your dependencies../flutter/tools/gn --unoptimized
to prepare your build files.ninja -C out/host_debug_unopt
to build a desktop unoptimized binary.-j 1000
to parallelize the build using Goma.--unoptimized
disables C++ compiler optimizations and does not strip debug symbols. You may skip the flag and invoke ninja -C out/host_debug
if you would rather have the native components optimized.flutter test --local-engine=host_debug_unopt
will run tests using the locally-built flutter_tester
.You can only build selected binaries on Windows (mainly gen_snapshot
).
git pull upstream master
in src/flutter
to update the Flutter Engine repo.gclient sync
to update your dependencies.python .\flutter\tools\gn [--unoptimized] --runtime-mode=[debug|profile|release] [--android]
to prepare your build files.ninja -C .\out\<dir created by previous step> gen_snapshot
to build.The following script will update all the builds that matter if you're developing on Linux and testing on Android and created the .gclient
file in ~/dev/engine
:
set -ex cd ~/dev/engine/src/flutter git fetch upstream git rebase upstream/master gclient sync cd .. flutter/tools/gn --unoptimized --runtime-mode=debug flutter/tools/gn --android --unoptimized --runtime-mode=debug flutter/tools/gn --android --unoptimized --runtime-mode=profile flutter/tools/gn --android --unoptimized --runtime-mode=release flutter/tools/gn --android --runtime-mode=debug flutter/tools/gn --android --runtime-mode=profile flutter/tools/gn --android --runtime-mode=release cd out find . -mindepth 1 -maxdepth 1 -type d | xargs -n 1 sh -c 'ninja -C $0 || exit 255'
We gladly accept contributions via GitHub pull requests. See the wiki for information about the engine's architecture.
To start working on a patch:
engine/src/flutter
directory.git fetch upstream
git checkout upstream/master -b name_of_your_branch
clang-format
before submission (use buildtools/<OS>/clang/bin/clang-format --style=file -i
).git commit -a -m "<your brief but informative commit message>"
git push origin name_of_your_branch
To send us a pull request:
git pull-request
(if you are using Hub) or go to https://github.com/flutter/engine
and click the “Compare & pull request” buttonOnce you've gotten an LGTM from a project maintainer, submit your changes to the master
branch using one of the following methods:
git push upstream name_of_your_branch:master
(requires commit access)Then, make sure it doesn‘t make our tree catch fire by watching the waterfall. The waterfall runs slightly different tests than Travis, so it’s possible for the tree to go red even if Travis did not. If that happens, please immediately revert your change. Do not check anything in while the tree is red unless you are trying to resolve the problem.
Please make sure all your checkins have detailed commit messages explaining the patch. If you made multiple commits for a single pull request, either make sure each one has a detailed message explaining that specific commit, or squash your commits into one single checkin with a detailed message before sending the pull request.
You must complete the Contributor License Agreement. You can do this online, and it only takes a minute. If you‘ve never submitted code before, you must add your (or your organization’s) name and contact info to the AUTHORS file.