flutter_flutter/docs/engine/contributing/Setting-up-the-Engine-development-environment.md

If you've already built the engine and have the configuration set up but merely need a refresher on actually compiling the code, see Compiling the engine or Engine Tool.

If you are checking these instructions to refresh your memory and your fork of the engine is stale, make sure to merge up to HEAD before doing a gclient sync.

Getting dependencies

Make sure you have the following dependencies available:

• A Linux, macOS, or Windows host
  • Linux supports cross-compiling artifacts for Android and Fuchsia, but not iOS.
  • macOS supports cross-compiling artifacts for Android and iOS.
  • Windows doesn't support cross-compiling artifacts for any of Android, Fuchsia, or iOS.
• git (used for source version control).
• An ssh client (used to authenticate with GitHub).
• python3 (used by many of our tools, including gclient).
• Chromium's depot_tools (Which includes gclient)
  • Add the depot_tools directory to the front of your PATH.
• On macOS and Linux: curl and unzip (used by gclient sync).
• On Linux: The pkg-config package.
• On Windows:
  • Visual Studio 2017 or later (required for non-Googlers only).
  • Windows 10 SDK (required for non-Googlers only). Be sure to install the "Debugging Tools for Windows" feature.
• On macOS:
  • Install the latest Xcode.
  • On Apple Silicon arm64 Macs, install the Rosetta translation environment by running softwareupdate --install-rosetta.

You do not need to install Dart. A Dart toolchain is automatically downloaded as part of the "Getting the source" step. Similarly for the Android SDK, it is downloaded by the gclient sync step below.

Getting the source

Run the following steps to set up your environment:

Important

Non-Googler Windows users should set the following environment variables to point depot_tools to their Visual Studio installation directory:

• DEPOT_TOOLS_WIN_TOOLCHAIN=0
• GYP_MSVS_OVERRIDE_PATH=C:\Program Files\Microsoft Visual Studio\2022\Community
  • Use the path of your installation.

Clone the Flutter source code. As of late 2024, the engine source is part of the main flutter/flutter repo. The convention is to fork this repo and point origin to your fork and upstream to git@github.com:flutter/flutter.git. See Setting up the Framework development environment for more.

Important

On Windows, the following must be run as an Administrator due to a known issue.

gclient bootstrap

Flutter engine uses gclient to manage dependencies.

1. Copy one of the engine/scripts/*.gclient to the repository root as .gclient:
   1. Googlers: copy rbe.gclient to enable faster builds with RBE. Follow RBE Getting started to set up RBE.
   2. Everyone else: copy standard.gclient
2. Run gclient sync from the root folder

Add et to PATH

The "Engine Tool" called et is useful when working with the engine. It is located in the flutter/engine/src/flutter/bin directory. Add this to your $PATH in your .rc file: e.g. on UNIX, using export PATH=/path/to/flutter/engine/src/flutter/bin:$PATH.

Additional Steps for Web Engine

Open the .gclient file in the repository root. Uncomment the lines indicated for building the web engine.

Now, run:

gclient sync

Next steps:

• Use et, the Engine Tool, to actually get builds, now that you have the code.
• The docs for the flutter tool have a section on using a locally built engine with the flutter tool.
• Signing commits, to configure your environment to securely sign your commits.

Editor autocomplete support

Xcode [Objective-C++]

On Mac, you can simply use Xcode (e.g., open out/host_debug_unopt/flutter_engine.xcodeproj).

VSCode with C/C++ Intellisense [C/C++]

VSCode can provide some IDE features using the C/C++ extension. It will provide basic support on install without needing any additional configuration. There will probably be some issues, like header not found errors and incorrect jump to definitions.

Intellisense can also use our compile_commands.json for more robust functionality. Either symlink src/out/compile_commands.json to the project root at src or provide an absolute path to it in the c_cpp_properties.json config file. See "compile commands" in the c_cpp_properties.json reference. This will likely resolve the basic issues mentioned above.

The easiest way to do this is create a multi-root workspace that includes the Flutter SDK. For example, something like this:

# flutter.code-workspace
{
	"folders": [
		{
			"path": "path/to/the/flutter/sdk"
		}
	],
	"settings": {}
}

Then, install the clangd extension and edit the "settings" key:

"settings": {
    "html.format.enable": false,
    "githubPullRequests.ignoredPullRequestBranches": [
        "master"
    ],
    "clangd.path": "engine/src/flutter/buildtools/mac-arm64/clang/bin/clangd",
    "clangd.arguments": [
        "--compile-commands-dir=engine/src/out/host_debug_unopt_arm64"
    ],
    "clang-format.executable": "engine/src/flutter/buildtools/mac-arm64/clang/bin/clang-format"
}

... which is built with:

# M1 Mac (host_debug_unopt_arm64)
et build -c host_debug_unopt_arm64

Some files (such as the Android embedder) will require an Android clangd configuration.

For adding IDE support to the Java code in the engine with VSCode, see "Using VSCode as an IDE for the Android Embedding".

Zed Editor

Zed can be used to edit C++ code in the Engine. To enable analysis and auto-completion, symlink src/out/compile_commands.json to the project root at src.

cquery/ccls (multiple editors) [C/C++/Objective-C++]

Alternatively, cquery and a derivative ccls are highly scalable C/C++/Objective-C language server that supports IDE features like go-to-definition, call hierarchy, autocomplete, find reference etc that works reasonably well with our engine repo.

They(https://github.com/cquery-project/cquery/wiki/Editor-configuration) supports editors like VSCode, emacs, vim etc.

To set up:

1. Install cquery
   1. brew install cquery or brew install ccls on osx; or
   2. Build from source
2. Generate compile_commands.json which our GN tool already does such as via src/flutter/tools/gn --ios --unoptimized
3. Install an editor extension such as VSCode-cquery or vscode-ccls
   1. VSCode-query and vscode-ccls requires the compile_commands.json to be at the project root. Copy or symlink src/out/compile_commands.json to src/ or src/flutter depending on which folder you want to open.
   2. Follow Setting up the extension to configure VSCode-query.

Using VSCode as an IDE for the Android Embedding [Java]

1. Install the extensions vscjava.vscode-java-pack (Extension Pack for Java) and vscjava.vscode-java-dependency (Project Manager for Java).

2. Right click on the shell/platform/android folder in the engine source and click on Add Folder to Java Source Path. This creates an anonymous workspace and turns those files from "syntax mode" to "compile mode". At this point, you should see a lot of errors since none of the external imports are found.

3. Find the "Java Dependencies" pane in your Explorer view. Use the "Explorer: Focus on Java Dependencies View" command if hidden.

4. Refresh the view and find the "flutter_*" project. There should be a "_/shell/platform/android" source folder there.

5. In the "Referenced Libraries" sibling node, click the + button, navigate to engine/src/third_party/android_embedding_dependencies and add the entire folder. This is the equivalent of adding

   "java.project.referencedLibraries": [
     "{path to engine}/src/third_party/android_embedding_dependencies/lib/**/*.jar"
   ]
   

   to your VSCode's settings.json for your user or for your workspace.

6. If you previously had a shell/platform/android/.classpath, delete it.

Using Android Studio as an IDE for the Android Embedding [Java]

Alternatively, Android Studio can be used as an IDE for the Android Embedding Java code. See docs at https://github.com/flutter/flutter/blob/main/engine/src/flutter/shell/platform/android/README.md#editing-java-code for instructions.

VSCode Additional Useful Configuration

1. Create snippets for header files with this configuration. This will let you use hdr keyboard macro to create the boiler plate header code. Also consider some of these settings and more tips.

2. To format GN files on save, consider using this extension.