From 597f07b268bdb47fc6e14894fae2db53516708da Mon Sep 17 00:00:00 2001 From: b-luk <97480502+b-luk@users.noreply.github.com> Date: Thu, 9 Oct 2025 12:44:25 -0700 Subject: [PATCH] Update engine setup docs. (#176750) - Move "gclient bootstrap" out of engine/README.md into a section in the "Setting up the Engine development environment" doc. - In the "gclient bootstrap" section, instruct Googlers to follow the RBE setup docs. - Update the "Additional Steps for Web Engine" to reflect the fact that the user's gclient file is copied from a template that contains a commented-out web engine entry. - Link to the "Engine Tool" docs instead of to "Compiling the engine" for the next steps. - In the RBE doc: - Update the gclient instructions to reflect that the gclient file may be copied from rbe.gclient. - Move the "gcloud" section into the "Getting started" parent section. The gcloud setup is required before any of the next steps. - Instead of suggested the "gcloud auth application-default login" command in case of an error, directly instruct the user to run this command. It's required for things to work. - Add a "Too many open files" section to the Troubleshooting parent section. *Replace this paragraph with a description of what this PR is changing or adding, and why. Consider including before/after screenshots.* *List which issues are fixed by this PR. You must list at least one issue. An issue is not required if the PR fixes something trivial like a typo.* *If you had to change anything in the [flutter/tests] repo, include a link to the migration guide as per the [breaking change policy].* ## Pre-launch Checklist - [ ] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [ ] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [ ] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [ ] I signed the [CLA]. - [ ] I listed at least one issue that this PR fixes in the description above. - [ ] I updated/added relevant documentation (doc comments with `///`). - [ ] I added new tests to check the change I am making, or this PR is [test-exempt]. - [ ] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [ ] All existing and new tests are passing. If you need help, consider asking for advice on the #hackers-new channel on [Discord]. **Note**: The Flutter team is currently trialing the use of [Gemini Code Assist for GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code). Comments from the `gemini-code-assist` bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed. [Contributor Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview [Tree Hygiene]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md [test-exempt]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests [Flutter Style Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md [Features we expect every widget to implement]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement [CLA]: https://cla.developers.google.com/ [flutter/tests]: https://github.com/flutter/tests [breaking change policy]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes [Discord]: https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md [Data Driven Fixes]: https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md --- .../contributing/Compiling-the-engine.md | 2 +- ...g-up-the-Engine-development-environment.md | 29 ++++++------ docs/engine/rbe/rbe.md | 45 +++++++++++-------- engine/README.md | 13 +----- 4 files changed, 43 insertions(+), 46 deletions(-) diff --git a/docs/engine/contributing/Compiling-the-engine.md b/docs/engine/contributing/Compiling-the-engine.md index 9c845fbe56f..b8a9e239f5d 100644 --- a/docs/engine/contributing/Compiling-the-engine.md +++ b/docs/engine/contributing/Compiling-the-engine.md @@ -35,7 +35,7 @@ Depending on the platform you are making changes for, you may be interested in a - Make sure to exclude the `out` directory from any backup scripts, as many large binary artifacts are generated. This is also generally true for all of the directories outside of the `engine/src/flutter` directory. -- See [gclient bootstrap](https://github.com/flutter/flutter/tree/main/engine#gclient-bootstrap) +- See [gclient bootstrap](Setting-up-the-Engine-development-environment.md#gclient-bootstrap) section for details on how to setup `gclient`. ## Updating the engine diff --git a/docs/engine/contributing/Setting-up-the-Engine-development-environment.md b/docs/engine/contributing/Setting-up-the-Engine-development-environment.md index 1c4963a890a..c875ebc1717 100644 --- a/docs/engine/contributing/Setting-up-the-Engine-development-environment.md +++ b/docs/engine/contributing/Setting-up-the-Engine-development-environment.md @@ -1,5 +1,6 @@ _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](Compiling-the-engine.md)._ +actually compiling the code, see [Compiling the engine](Compiling-the-engine.md) or +[Engine Tool](https://github.com/flutter/flutter/blob/main/engine/src/flutter/tools/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`._ @@ -47,24 +48,22 @@ Clone the Flutter source code. As of late 2024, the engine source is part of the > [!IMPORTANT] > On Windows, the following must be run as an Administrator due to [a known issue](https://github.com/flutter/flutter/issues/94580). -[Setup a `.gclient` file](../../../engine/README.md) in the repository -root (the `flutter/flutter` repository root), and run `gclient sync`. +### `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](https://github.com/flutter/flutter/blob/main/docs/engine/rbe/rbe.md#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`](https://github.com/flutter/flutter/tree/0c3359df8c8342c8907316488b1404a216f215b6/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 -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, - }, - }, -] -``` +Open the `.gclient` file in the repository root. Uncomment the lines indicated for building the web engine. Now, run: @@ -74,7 +73,7 @@ gclient sync ## Next steps: - * [Compiling the engine](Compiling-the-engine.md) explains how to actually get builds, now that you have the code. + * Use `et`, the [Engine Tool](https://github.com/flutter/flutter/blob/main/engine/src/flutter/tools/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](https://github.com/flutter/flutter/blob/main/docs/tool/README.md#using-a-locally-built-engine-with-the-flutter-tool). * [Signing commits](https://github.com/flutter/flutter/blob/main/docs/contributing/Signing-commits.md), to configure your environment to securely sign your commits. diff --git a/docs/engine/rbe/rbe.md b/docs/engine/rbe/rbe.md index ff94c641c93..f837348666d 100644 --- a/docs/engine/rbe/rbe.md +++ b/docs/engine/rbe/rbe.md @@ -1,6 +1,5 @@ # RBE for Flutter Engine Developers -g ## Overview This is documentation on setting up RBE for building the Flutter engine. It is @@ -9,21 +8,21 @@ including cloudtop instances. ## Getting started -The first step is to add an entry to the `.gclient` file. The entry to add is -`"use_rbe": True` in the `custom_vars` section. It should look like this: +The first step is ensure RBE is enabled in `.gclient` file. Add the entry +`"use_rbe": True` in the `custom_vars` section if it is not already present. + +> **TIP**: If your `.gclient` file was copied from `engine/scripts/rbe.gclient`, +> the entry will already be present. + +`.gclient` should look like this: ``` solutions = [ { - "managed": False, - "name": "src/flutter", - "url": "git@github.com:zanderso/engine.git", - "custom_deps": {}, + # ... "custom_vars": { "use_rbe": True, }, - "deps_file": "DEPS", - "safesync_url": "", }, ] ``` @@ -38,12 +37,6 @@ cipd auth-login After authentication successfully, run `gclient sync -D`. -## Running an RBE build - -In the engine repo, all RBE builds must be initiated through the `et` tool whose -entrypoint is the script `//flutter/bin/et`. This is so that the local RBE -proxy is correctly initialized and shut down around invocations of `ninja`. - ### gcloud Before running an RBE build, you must be authenticated with the Google cloud @@ -59,14 +52,18 @@ return `/usr/bin/python3`. gcloud init --project flutter-rbe-prod ``` -If you get an error from `bootstrap` about not being able to find `Application -Default Credentials` you may need to execute the following to create the default -credentials: +Execute the following to create application default credentials: ```sh gcloud auth application-default login ``` +## Running an RBE build + +In the engine repo, all RBE builds must be initiated through the `et` tool whose +entrypoint is the script `//flutter/bin/et`. This is so that the local RBE +proxy is correctly initialized and shut down around invocations of `ninja`. + ### Listing builds The builds available to the `et` tool are those specified by the build @@ -153,6 +150,18 @@ Check your `${HOME}/.config/gcloud/application_default_credentials.json` to see gcloud auth application-default login ``` +### Too many open files + +For developers on a macOS device, if you get the following error while running +`et build`: + +```shell +ninja: fatal: pipe: Too many open files +``` + +Increase the maximum number of open files on your machine with the instructions +[here](go/building-chrome-mac#configure-your-mac-for-remote-execution). + ### Slow builds RBE builds can be slow for a few different reasons. The most common reason is diff --git a/engine/README.md b/engine/README.md index f0278c2f782..c4848bab03a 100644 --- a/engine/README.md +++ b/engine/README.md @@ -2,15 +2,4 @@ ## Setting up the Engine development environment -See [here](https://github.com/flutter/flutter/blob/master/docs/engine/contributing/Setting-up-the-Engine-development-environment.md#getting-the-source) - -## `gclient` bootstrap - -Flutter engine uses `gclient` to manage dependencies. - -If you've already cloned the flutter repository: - -1. Copy one of the `engine/scripts/*.gclient` to the [root](../) folder as `.gclient`: - 1. Googlers: copy `rbe.gclient` to enable faster builds with [RBE](https://github.com/flutter/flutter/blob/master/docs/engine/rbe/rbe.md) - 2. Everyone else: copy `standard.gclient` -2. run `gclient sync` from the [root](../) folder +See [here](https://github.com/flutter/flutter/blob/main/docs/engine/contributing/Setting-up-the-Engine-development-environment.md#getting-the-source)