Delete and update stale documentation regarding engine/engine hash. (#164324)
This is intended to be merged _after_ https://github.com/flutter/flutter/pull/164317.
This commit is contained in:
Matan Lurey
@@ -1,66 +1,39 @@
|
||||
# Autorollers
|
||||
|
||||
Several of our dependencies are automatically rolled (updated) by bots.
|
||||
|
||||
## Clang to Engine
|
||||
<img src="https://media1.tenor.com/m/8WV-qfNTVRMAAAAd/autobots-rollout-cat.gif" height="200" />
|
||||
|
||||
We use an auto-roller for Clang on [Linux](https://autoroll.skia.org/r/clang-linux-flutter-engine) and [macOS](https://autoroll.skia.org/r/clang-mac-flutter-engine) (Windows is pending availability of a Windows Clang package from the Fuchsia infra team). In case of build failures or other errors, ping the #hackers-engine channel on [Discord](../contributing/Chat.md).
|
||||
## Clang
|
||||
|
||||
We use an auto-roller for Clang <https://autoroll.skia.org/r/clang-flutter>.
|
||||
|
||||
These rollers may fail if Clang catches a new compilation warning or error that it previously did not, or if a test relies on undefined behavior that has now changed in the new revision of Clang. It is best to resolve such issues ASAP to let the rollers continue and avoid a pile up of issues to resolve.
|
||||
|
||||
The rollers work by updating a [CIPD](https://chrome-infra-packages.appspot.com/p/fuchsia/third_party/clang/) package version in the DEPS file. You can map from a CIPD version to a git revision by checking in CIPD.
|
||||
The rollers work by updating a [CIPD](https://chrome-infra-packages.appspot.com/p/fuchsia/third_party/clang/) package version in the [DEPS](../../DEPS) file. You can map from a CIPD version to a git revision by checking in CIPD.
|
||||
|
||||
## Fuchsia SDK to Engine
|
||||
|
||||
We use an auto-roller for the Fuchsia SDK on [Linux](https://autoroll.skia.org/r/fuchsia-linux-sdk-flutter-engine) and [macOS](https://autoroll.skia.org/r/fuchsia-mac-sdk-flutter-engine) (Windows is pending availability of a Windows Fuchsia SDK package from the Fuchsia infra team). In case of build failures or other errors, ping the #hackers-engine channel on [Discord](../contributing/Chat.md).
|
||||
## Fuchsia SDK
|
||||
|
||||
We use an auto-roller for the Fuchsia SDK on [Linux](https://autoroll.skia.org/r/fuchsia-linux-sdk-flutter)
|
||||
These rollers may fail if the Fuchsia SDK contains a breaking change. It is best to resolve such issues ASAP to let the rollers continue and avoid a pile up of issues to resolve.
|
||||
|
||||
The rollers work by updating a [CIPD](https://chrome-infra-packages.appspot.com/p/fuchsia/sdk/core) package version in the DEPS file. You can map from a CIPD version to a JIRI snapshot or a git revision by checking in CIPD.
|
||||
|
||||
## Skia to Engine
|
||||
## Skia
|
||||
|
||||
We use an auto-roller for Skia rolls. It's status can be viewed at <https://skia-flutter-roll.skia.org/>. In case of build failures or other errors, ping the Flutter-Skia chat channel. In case you get no response, you can log in with an @google.com account and pause the roller (or ask someone with an @google.com account to do so). Please specify a descriptive reason and file a bug to re-enable the rollers as soon as possible.
|
||||
We use an auto-roller for Skia rolls. It's status can be viewed at <https://skia-flutter-roll.skia.org/>. In case of build failures or other errors, ping the Flutter-Skia chat channel. In case you get no response, you can log in with an `@google.com` account and pause the roller (or ask someone with an `@google.com` account to do so). Please specify a descriptive reason and file a bug to re-enable the rollers as soon as possible.
|
||||
|
||||
The bot updates the `skia_revision` line of <https://github.com/flutter/engine/blob/main/DEPS>.
|
||||
The bot updates the `skia_revision` line of [`DEPS`](../../DEPS).
|
||||
|
||||
Skia also uses an auto-roller for Fuchsia; see <https://autoroll-internal.skia.org/r/fuchsia-autoroll>.
|
||||
## Dart
|
||||
|
||||
## Engine to Framework
|
||||
|
||||
The engine is automatically rolled to the framework. It is configured by <https://skia.googlesource.com/skia-autoroll-internal-config.git/+/main/skia-infra-public/flutter-engine-flutter.cfg>.
|
||||
|
||||
The bot updates <https://github.com/flutter/flutter/blob/main/bin/internal/engine.version> to point to the latest revision of the engine *whose artifacts built successfully*, as determined by looking at the [Engine Console](https://ci.chromium.org/p/flutter/g/engine/console).
|
||||
|
||||
|
||||
### Making a breaking change
|
||||
|
||||
Our [breaking change policy](../contributing/Tree-hygiene.md#handling-breaking-changes) disallows making changes to the engine that require changes to the framework. If you find the need to do this, you should instead make a soft-breaking change which you can land in multiple phases, as described in that process.
|
||||
|
||||
### Doing a manual roll
|
||||
|
||||
To roll the engine manually in the case you have a breaking change exemption, you'll need to land the change to `engine.version` manually in the same PR to the framework as the one where you fix the framework to work with the new API.
|
||||
|
||||
When you change the `engine.version` file locally, you should delete `$FLUTTER_ROOT/bin/cache` and then run `flutter precache` to ensure that all your local artifacts and snapshots are updated. You can then run tests and be sure that they are running against the latest version of the assets you need.
|
||||
|
||||
You may find it helpful to use the [`$ENGINE_ROOT/src/flutter/tools/engine_roll_pr_desc.sh`](https://github.com/flutter/engine/blob/main/tools/engine_roll_pr_desc.sh) to create a PR description. Doing this helps us track down what commits have rolled in more quickly, and properly link to other commits and pull requests for commenting and tracking.
|
||||
|
||||
For example, to generate a description from hash deadbeef to beefdead:
|
||||
|
||||
```bash
|
||||
$ ./tools/engine_roll_pr_desc.sh deadbeef..beefdead
|
||||
```
|
||||
|
||||
_See also: [Debugging the engine](../engine/Debugging-the-engine.md), which includes instructions on bisecting a roll failure._
|
||||
|
||||
|
||||
## Dart to Engine
|
||||
|
||||
The Dart SDK is automatically rolled into the engine on a regular basis, following the steps laid out at the [Rolling Dart](Rolling-Dart.md) page. Since this process is a bit more involved, this autoroller does not use the Skia infrastructure and has a custom dashboard hosted at [go/dart-sdk-roller-dashboard](http://go/dart-sdk-roller-dashboard) (**note: this is likely only accessible from a machine on the Google network**). Using the dashboard, the autoroller can be paused, rolls can be triggered and cancelled, and rolls to a particular revision can be done.
|
||||
The Dart SDK is automatically rolled by <https://autoroll.skia.org/r/dart-sdk-flutter>.
|
||||
|
||||
If there are any issues with this process or the autoroller dashboard, contact bkonyi@ or a member of the Dart VM team.
|
||||
|
||||
## Flutter Pub Roller
|
||||
|
||||
The bot account [flutter-pub-roller-bot](https://github.com/flutter-pub-roller-bot) runs the script at
|
||||
https://github.com/flutter/flutter/blob/main/dev/conductor/bin/packages_autoroller on post-submit of
|
||||
[`packages_autoroller`](../../dev/conductor/bin/packages_autoroller) on post-submit of
|
||||
every framework commit to keep the pub dependencies in the [framework](https://github.com/flutter/flutter)
|
||||
up to date.
|
||||
up to date.
|
||||
|
||||
@@ -1,18 +1,15 @@
|
||||
# Rolling the Dart SDK
|
||||
|
||||
Flutter is a series of connected repositories. Within each repository there are files (normally named `DEPS`) which determine which version of the other repositories the repository currently works with.
|
||||
|
||||
The three relevant repositories for this document are:
|
||||
|
||||
- Flutter. This is the top half of the Flutter project: [flutter/flutter on GitHub](https://github.com/flutter/flutter)
|
||||
- Engine. This is the Flutter Engine, the lower half of the Flutter project: [flutter/engine on GitHub](https://github.com/flutter/engine)
|
||||
- Flutter. The Flutter project: [flutter/flutter on GitHub](https://github.com/flutter/flutter)
|
||||
- Dart SDK. This is the language used for big parts of Flutter: [dart-lang/sdk on GitHub](https://github.com/dart-lang/sdk)
|
||||
|
||||
This document describes how to update the version of the Dart SDK that the Engine uses, and then update the version of the Engine that Flutter uses, so that Flutter gets the latest Dart.
|
||||
|
||||
The Flutter repo does not use a `DEPS` file and `gclient` for its dependencies. Instead, the Flutter Engine version is in `flutter/bin/internal/engine.version`.
|
||||
|
||||
## Dart Autoroller
|
||||
|
||||
Dart is now automatically rolled into the Flutter engine repository on a regular basis. See [Autorollers](Autorollers.md) for more information.
|
||||
Dart is now automatically rolled into the Flutter repository on a regular basis. See [Autorollers](Autorollers.md) for more information.
|
||||
|
||||
## Using dart_roll_helper.py to roll the version of Dart used by the engine
|
||||
|
||||
@@ -54,8 +51,8 @@ If the script completes without errors, move on to step 10 in the next section t
|
||||
linked to from [our contributing guide](../../CONTRIBUTING.md).
|
||||
2. Build the engine according to the instructions on the [Compiling the engine](../engine/contributing/Compiling-the-engine.md) page.
|
||||
3. Select a target Dart revision, typically use the [latest revision](https://github.com/dart-lang/sdk/commits/main). Check that the tests for that revision have all passed (all green) on the [Dart buildbot](https://ci.chromium.org/p/flutter/g/engine/console) and the [Internal Dart Flutter buildbot](https://ci.chromium.org/p/dart/g/flutter/console).
|
||||
4. Create a PR (see [Tree hygiene](../contributing/Tree-hygiene.md)) that updates `dart_revision` in [DEPS](https://github.com/flutter/engine/blob/main/DEPS) to your selected revision. Invoke `gclient sync` in the src directory to ensure versions corresponding to the DEPS file are synced up.
|
||||
5. Update all Dart-dependent DEPS entries using `engine/src/tools/dart/create_updated_flutter_deps.py` script. In case script complains that dart dependency was removed, remove entry from flutter DEPS file manually. If the list of library source files or patch files is modified, update the file [libraries.yaml](https://github.com/flutter/engine/blob/main/lib/snapshot/libraries.yaml) and regenerate the corresponding json file.
|
||||
4. Create a PR (see [Tree hygiene](../contributing/Tree-hygiene.md)) that updates `dart_revision` in [DEPS](../../DEPS) to your selected revision. Invoke `gclient sync` in the src directory to ensure versions corresponding to the DEPS file are synced up.
|
||||
5. Update all Dart-dependent DEPS entries using [`create_updated_flutter_deps.py`](../../engine/src/tools/dart/create_updated_flutter_deps.py) script. In case script complains that dart dependency was removed, remove entry from flutter DEPS file manually. If the list of library source files or patch files is modified, update the file [`libraries.yaml`](../../engine/src/flutter/lib/snapshot/libraries.yaml) and regenerate the corresponding json file.
|
||||
6. Invoke `gclient sync` in the src directory to ensure versions corresponding to the DEPS file are synced up.
|
||||
7. Build the debug, profile, and release versions of the engine, following the normal [Compiling the engine](../engine/contributing/Compiling-the-engine.md) instructions. You will need to build the host versions of the engine too. Here is a script with the build commands:
|
||||
|
||||
|
||||
@@ -167,7 +167,7 @@ and `local-engine`, which specifies which build of the engine to use.
|
||||
|
||||
**Important:** before building your local engine, you should ensure that your engine feature branch is based on the
|
||||
same upstream version of the engine that the Flutter SDK/flutter tool has pinned. You can find the engine version
|
||||
that the Flutter SDK has pinned at `flutter/bin/internal/engine.version`.
|
||||
that the Flutter SDK has pinned at `bin/cache/engine.stamp`.
|
||||
|
||||
A typical invocation would be: `--local-engine-src-path /path/to/engine/src --local-engine=android_debug_unopt --local-engine-host=host_debug_unopt`.
|
||||
|
||||
@@ -177,13 +177,6 @@ You can also set the environment variable `$FLUTTER_ENGINE` instead of specifyin
|
||||
|
||||
The `--local-engine` should specify the build of the engine to use, e.g. a profile build for Android, a debug build for Android, or whatever. It must match the other arguments provided to the tool, e.g. don't use the `android_debug_unopt` build when you specify `--release`, since the Debug build expects to compile and run Dart code in a JIT environment, while `--release` implies a Release build which uses AOT compilation.
|
||||
|
||||
<!-- TODO(matanl): https://github.com/flutter/flutter/issues/132245, update this. -->
|
||||
|
||||
> ⚠️ **WARNING**: As of [#132245](https://github.com/flutter/flutter/issues/132245), `--local-engine-host` will be mandatory.
|
||||
>
|
||||
> If you're currently relying on the host engine being implicitly defined, you will need to update your workflow to explicitly specify the host engine.
|
||||
> For example, if you're currently running `flutter run --local-engine=android_debug_unopt`, you will need to run `flutter run --local-engine=android_debug_unopt --local-engine-host=host_debug_unopt` instead.
|
||||
|
||||
If you've modified the public API of `dart:ui` in your local build of the engine
|
||||
and you need to be able to analyze the framework code with the new API,
|
||||
you will need to add a `dependency_overrides` section pointing to your
|
||||
|
||||
Reference in New Issue
Block a user