mirror of
https://github.com/flutter/flutter.git
synced 2026-02-20 02:29:02 +08:00
c50dd2ea93
<!-- start_original_pr_link -->
Reverts: flutter/flutter#173114
<!-- end_original_pr_link -->
<!-- start_initiating_author -->
Initiated by: jtmcdole
<!-- end_initiating_author -->
<!-- start_revert_reason -->
Reason for reverting: there is still another problem with the merge
queue causing the content hash to be different:
git revision: e13dd5384cc0db576291c2925852879f1111f284
actual hash: 4b6f7b0f9849efaa59f515c8e95f3f27a6eb2ffb
hash in the queue? 9e5b2eef4ba79b15b4f80dbba812d199d262366f
<!-- end_revert_reason -->
<!-- start_original_pr_author -->
Original PR Author: jtmcdole
<!-- end_original_pr_author -->
<!-- start_reviewers -->
Reviewed By: {matanlurey, chingjun}
<!-- end_reviewers -->
<!-- start_revert_body -->
This change reverts the following previous change:
The content hash doesn't exist for local engine changes, except for on
CI. If we detect we're on a branch with committed or uncommitted changes
to engine files; use "master".
towards #171790
re-land attempt for #172792 with the following changes:
1. content_aware_hash.(ps1|sh) now consider multiple branches to choose
between HEAD and merge-base.
2. content_aware_hash_test.dart updated for these new requirements
3. content_aware_hash_test.dart allows for forcing powershell on mac for
testing
4. updated docs/tool/Engine-artifacts.md documentation.
## Pre-launch Checklist
- [x] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [x] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [x] I read and followed the [Flutter Style Guide], including [Features
we expect every widget to implement].
- [x] I signed the [CLA].
- [x] I listed at least one issue that this PR fixes in the description
above.
- [x] I updated/added relevant documentation (doc comments with `///`).
- [x] 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.
- [x] All existing and new tests are passing.
<!-- end_revert_body -->
Co-authored-by: auto-submit[bot] <flutter-engprod-team@google.com>
98 lines
4.7 KiB
Markdown
98 lines
4.7 KiB
Markdown
# How `flutter` fetches engine artifacts
|
|
|
|
[flutter.dev/to/engine-artifacts](https://flutter.dev/to/engine-artifacts)
|
|
|
|
While in the same repository, the `flutter` (tool), which is used to run and
|
|
test the framework, needs to know how to download the engine artifacts for the
|
|
current platform and target device. Engine artifacts include `dart` (the
|
|
standalone Dart SDK), which runs `flutter` itself, and per-platform and build
|
|
mode prebuilt engines (which include the C++ compiled engine, and the embedders
|
|
for Android, iOS, and so-on).
|
|
|
|
|
|
|
|
When using a _released_ version of Flutter, i.e. from a channel such as `stable`,
|
|
[`bin/internal/engine.version`](../../bin/internal/engine.version) is set to the
|
|
content hash SHA for a merged commit in `https://github.com/flutter/flutter`, where
|
|
the engine artifacts have already been pre-built and uploaded.
|
|
|
|
When using the `master` channel, or _contributing_ to Flutter (which is typically
|
|
as a fork of Flutter's `master` channel), the engine SHA is _computed_ by
|
|
generating a content-aware hash of files that affect the engine build (such as
|
|
`DEPS` and the `engine` directory itself).
|
|
|
|
For _advanced_ use-cases, such as on CI platforms, or for custom 1-off testing
|
|
using a pre-built Flutter engine (to use a _locally_ built Flutter engine see
|
|
[locally built engines](../contributing/testing/Running-and-writing-tests.md#locally-built-engines)), the environment variable `FLUTTER_PREBUILT_ENGINE_VERSION` can be set,
|
|
again to a engine SHA for a merged commit in `flutter/flutter`. This is only needed
|
|
if different artifacts from the content sha are desired:
|
|
|
|
```sh
|
|
$ FLUTTER_PREBUILT_ENGINE_VERSION=abc123 flutter --version
|
|
..
|
|
Engine • revision abc123 ..
|
|
..
|
|
```
|
|
|
|
```mermaid
|
|
stateDiagram-v2
|
|
[*] --> CheckEnvVar
|
|
CheckEnvVar: <code>FLUTTER_PREBUILT_ENGINE_VERSION</code> set?
|
|
UseEnvVar: Use <code>FLUTTER_PREBUILT_ENGINE_VERSION</code>
|
|
CheckReleaseFile: <code>bin/internal/engine.version</code> exists?
|
|
UseReleaseFile: Use <code>bin/internal/engine.version</code>
|
|
UseContentAwareHash: Compute content-aware hash
|
|
|
|
CheckEnvVar --> UseEnvVar: Yes
|
|
CheckEnvVar --> CheckReleaseFile: No
|
|
UseEnvVar --> [*]: Done
|
|
CheckReleaseFile --> UseReleaseFile: Yes
|
|
CheckReleaseFile --> UseContentAwareHash: No
|
|
UseReleaseFile --> [*]: Done
|
|
UseContentAwareHash --> [*]: Done
|
|
```
|
|
|
|
## Flutter CI/CD Testing
|
|
|
|
On Cocoon (Flutter's internal CI/CD) we _often_ set
|
|
`FLUTTER_PREBUILT_ENGINE_VERSION` to the following:
|
|
|
|
| Branch | Presubmit | Merge Queue | Postsubmit |
|
|
| ------------------------- | ------------- | ------------- | ------------- |
|
|
| `main` | `content.sha` | `content.sha` | `content.sha` |
|
|
| `flutter-x.x-candidate.x` | `content.sha` | N/A[^1] | `content.sha` |
|
|
| `stable` or `beta` | N/A[^3] | N/A[^1] | N/A[^3] |
|
|
| _anything else_[^2] | `content.sha` | `content.sh` | `content.sha` |
|
|
|
|
> To generate a new `engine.version`:
|
|
>
|
|
> ```sh
|
|
> ./bin/internal/content_aware_hash.sh > ./bin/internal/engine.version
|
|
> ```
|
|
>
|
|
> As of [`b0ccfb53801abc9b0aa93e7cca3a3841513c3086`](https://flutter.googlesource.com/recipes/+/b0ccfb53801abc9b0aa93e7cca3a3841513c3086) (May 6 2025), the packaging release process will refuse to let you publish a
|
|
> release with an out of date `engine.version`.
|
|
|
|
[^1]: Does not use a merge queue.
|
|
[^2]: I.e. experimental branches that do not fall into one of the above.
|
|
[^3]: Only updated through `flutter-x.x-candidate.x` branches.
|
|
|
|
## References
|
|
|
|
The script(s) that compute (and test the computation of) the engine version:
|
|
|
|
- [`bin/internal/update_engine_version.sh`](../../bin/internal/update_engine_version.sh)
|
|
- [`bin/internal/update_engine_version.ps1`](../../bin/internal/update_engine_version.ps1)
|
|
- [`dev/tools/test/update_engine_version_test.dart`](../../dev/tools/test/update_engine_version_test.dart)
|
|
- [`bin/internal/last_engine_commit.sh`](../../bin/internal/last_engine_commit.sh)
|
|
- [`bin/internal/last_engine_commit.ps1`](../../bin/internal/last_engine_commit.ps1)
|
|
- [`dev/tools/test/last_engine_commit_test.dart`](../../dev/tools/test/last_engine_commit_test.dart)
|
|
- [`bin/internal/content_aware_hash.sh`](../../bin/internal/content_aware_hash.sh)
|
|
- [`bin/internal/content_aware_hash.ps1`](../../bin/internal/content_aware_hash.ps1)
|
|
- [`dev/tools/test/content_aware_hash_test.dart`](../../dev/tools/test/content_aware_hash_test.dart)
|
|
|
|
The tool uses the engine version in the following locations:
|
|
|
|
- [`lib/src/artifacts.dart`](../../packages/flutter_tools/lib/src/artifacts.dart)
|
|
- [`lib/src/build_system/source.dart`](../../packages/flutter_tools/lib/src/build_system/source.dart)
|