mirror of
https://github.com/flutter/flutter.git
synced 2026-02-20 02:29:02 +08:00
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. <!-- Thanks for filing a pull request! Reviewers are typically assigned within a week of filing a request. To learn more about code review, see our documentation on Tree Hygiene: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md --> *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. <!-- Links --> [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
This commit is contained in:
b-luk
GitHub
parent
e04f0bcfc3
commit
597f07b268
@ -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
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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)
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user