7da78cb7b8
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 #173114 (try 2) re-land attempt for #172792 (original) The first commit in this PR is the previously LGTM'd changes for the above; with tests. The second commit is the critical change to make this work in post submits (fixes #173143). It turns out that while LUCI reports the GitHub private branches; our recipes directly checkout the git sha. This matters because the content scripts couldn't determine the branch name and the rev-parse was just HEAD. This lead the scripts down the merge-base logic, which returns the previous commit. A test was added specifically for this. Alternatively to this change, we could have checked for LUCI_CONTEXT being present in the environment. This is checked by Flutter tools in some cases, but not by any other scripts in `bin/internal`. The downside to checking HEAD: if you have a local branch with engine changes and you move back a revision - `dart`/`flutter` invocations will generate the hash for your local changes and fail.
6.3 KiB
How flutter fetches engine artifacts
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 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), 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:
$ FLUTTER_PREBUILT_ENGINE_VERSION=abc123 flutter --version
..
Engine • revision abc123 ..
..
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/A1 | content.sha |
stable or beta |
N/A2 | N/A1 | N/A2 |
| anything else3 | content.sha |
content.sh |
content.sha |
To generate a new
engine.version:./bin/internal/content_aware_hash.sh > ./bin/internal/engine.versionAs of
b0ccfb53801abc9b0aa93e7cca3a3841513c3086(May 6 2025), the packaging release process will refuse to let you publish a release with an out of dateengine.version.
Content Hashing
The content hash is a fingerprint of the assets used in producing engine artifacts. These include:
DEPS: Used to pull third_party dependencies.engine/: The entire engine subfolder4.bin/internal/release-candidate-branch.version: A signal for release builds, keeping builds hermetic.
The Flutter project has a plethora of users: engineers working from local branches, release branches, GitHub merge queues, and downstream shallow consumers to name the known ones. The following table shows where the content hash is calculated from:
| Branch | Hashed From |
|---|---|
main,master |
HEAD |
stable, beta |
HEAD |
| GitHub Merge Queue | HEAD |
flutter-*-candidate.x |
HEAD |
HEAD |
HEAD |
| Shallow Clones | HEAD |
| Everything Else. | merge-base between HEAD and(origin or upstream)/(main or master) |
References
The script(s) that compute (and test the computation of) the engine version:
bin/internal/update_engine_version.shbin/internal/update_engine_version.ps1dev/tools/test/update_engine_version_test.dartbin/internal/last_engine_commit.shbin/internal/last_engine_commit.ps1dev/tools/test/last_engine_commit_test.dartbin/internal/content_aware_hash.shbin/internal/content_aware_hash.ps1dev/tools/test/content_aware_hash_test.dart
The tool uses the engine version in the following locations:
-
Does not use a merge queue. ↩︎
-
Only updated through
flutter-x.x-candidate.xbranches. ↩︎ -
I.e. experimental branches that do not fall into one of the above. ↩︎
-
This is suboptimal from an artifact building perspective, but optimal for the speed of each
dartandfluttercall. Flutter is called more often than it is built. ↩︎