Skip to content

Latest commit

 

History

History
181 lines (130 loc) · 9.6 KB

Setting-up-the-Engine-development-environment.md

File metadata and controls

181 lines (130 loc) · 9.6 KB
Raw

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.

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.

Create a new directory to hold the source code and move into it. Here, we are using the "engine" directory.

mkdir engine; cd engine;

Important

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

Fetch the Flutter engine sources. This may take a while on a slow connection. Do not interrupt this process. Otherwise, a partial checkout cannot be resumed and you'll have to delete all the files including the hidden files in the engine directory and start over.

fetch flutter

The Flutter Engine repository resides at src/flutter. The convention is to refer to this repository as upstream.

git -C src/flutter remote rename origin upstream

Optionally, if you are working with a fork of the engine, add that as a Git remote.

git -C src/flutter remote add origin <your_git_fork_location>

The "Engine Tool" called et is useful when working with the engine. It is located in the flutter/bin directory in the engine source checkout. Add this to your $PATH in your .rc.

Additional Steps for Web Engine

Amend the generated .gclient file in the root of the source directory to add the following:

solutions = [
  {
    # Same as above...
    "custom_vars": {
      "download_emsdk": True,
    },
  },
]

Now, run

gclient sync

Next steps:

Editor autocomplete support

Xcode [Objective-C++]

On Mac, you can simply use Xcode (e.g., open out/host_debug_unopt/products.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.

For example, in src/.vscode/settings.json:

{
  "clangd.path": "buildtools/mac-arm64/clang/bin/clangd",
  "clangd.arguments": [
    "--compile-commands-dir=out/host_debug_unopt_arm64"
  ],
  "clang-format.executable": "buildtools/mac-arm64/clang/bin/clang-format"
}

... which is built with:

# M1 Mac (host_debug_unopt_arm64)
./tools/gn --unopt --mac-cpu arm64 --enable-impeller-vulkan --enable-impeller-opengles --enable-unittests

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/engine/blob/main/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.