diff --git a/dev/tools/test/update_engine_version_test.dart b/dev/tools/test/update_engine_version_test.dart index b0c50b97ec..0ffd16c898 100644 --- a/dev/tools/test/update_engine_version_test.dart +++ b/dev/tools/test/update_engine_version_test.dart @@ -13,6 +13,15 @@ import 'package:file_testing/file_testing.dart'; import 'package:platform/platform.dart'; import 'package:test/test.dart'; +////////////////////////////////////////////////////////////////////// +// // +// ✨ THINKING OF MOVING/REFACTORING THIS FILE? READ ME FIRST! ✨ // +// // +// There is a link to this file in //docs/tool/Engine-artfiacts.md // +// and it would be very kind of you to update the link, if needed. // +// // +////////////////////////////////////////////////////////////////////// + void main() { const FileSystem localFs = LocalFileSystem(); final _FlutterRootUnderTest flutterRoot = _FlutterRootUnderTest.findWithin(); diff --git a/docs/contributing/testing/Running-and-writing-tests.md b/docs/contributing/testing/Running-and-writing-tests.md index a191c20a92..41b9d639b0 100644 --- a/docs/contributing/testing/Running-and-writing-tests.md +++ b/docs/contributing/testing/Running-and-writing-tests.md @@ -45,6 +45,8 @@ before the test runs. To run analysis and all the tests for the entire Flutter repository, the same way that LUCI runs them, run `dart dev/bots/test.dart` and `dart --enable-asserts dev/bots/analyze.dart`. +### Locally built engines + If you've built your own flutter engine (see [Setting up the Engine development environment](../../engine/contributing/Setting-up-the-Engine-development-environment.md)), you can pass `--local-engine` to change what flutter shell `flutter test` uses. For example, if you built an engine in the `out/host_debug_unopt` directory, you can use: diff --git a/docs/tool/Engine-artifacts.md b/docs/tool/Engine-artifacts.md new file mode 100644 index 0000000000..c4b1d646f4 --- /dev/null +++ b/docs/tool/Engine-artifacts.md @@ -0,0 +1,67 @@ +# How `flutter` fetches 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). + +![An example of cached engine artifacts](https://github.com/user-attachments/assets/47c45971-5c5c-4a01-8239-8af0b98cabb8) + +> [!NOTE] +> +> This process is changing, see [#163986](https://github.com/flutter/flutter/issues/163896). + +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 +git commit 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 git commit SHA is _computed_ by +using `git merge-base HEAD upstream/master` (falling back to `git merge-base HEAD origin/master` +to support direct forks or `flutter/flutter`). + +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 git commit SHA for a merged commit in `flutter/flutter`: + +```sh +$ FLUTTER_PREBUILT_ENGINE_VERSION=abc123 flutter --version +.. +Engine • revision abc123 .. +.. +``` + +```mermaid +stateDiagram-v2 + [*] --> CheckEnvVar + CheckEnvVar: FLUTTER_PREBUILT_ENGINE_VERSION set? + UseEnvVar: Use FLUTTER_PREBUILT_ENGINE_VERSION + CheckReleaseFile: bin/internal/engine.version exists? + UseReleaseFile: Use bin/internal/engine.version + UseMergeBase: git merge-base HEAD upstream/master + + CheckEnvVar --> UseEnvVar: Yes + CheckEnvVar --> CheckReleaseFile: No + UseEnvVar --> [*]: Done + CheckReleaseFile --> UseReleaseFile: Yes + CheckReleaseFile --> UseMergeBase: No + UseReleaseFile --> [*]: Done + UseMergeBase --> [*]: Done +``` + +## 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) + +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) diff --git a/packages/flutter_tools/lib/src/artifacts.dart b/packages/flutter_tools/lib/src/artifacts.dart index ab4dd17578..6ae0d666ce 100644 --- a/packages/flutter_tools/lib/src/artifacts.dart +++ b/packages/flutter_tools/lib/src/artifacts.dart @@ -16,6 +16,16 @@ import 'build_info.dart'; import 'cache.dart'; import 'globals.dart' as globals; +////////////////////////////////////////////////////////////////////// +// // +// ✨ THINKING OF MOVING/REFACTORING THIS FILE? READ ME FIRST! ✨ // +// // +// There is a link to this file in //docs/tool/Engine-artfiacts.md // +// and it would be very kind of you to update the link, if needed. // +// // +////////////////////////////////////////////////////////////////////// + +/// Defines what engine artifacts are available (not necessarily on each platform). enum Artifact { /// The tool which compiles a dart kernel file into native code. genSnapshot, diff --git a/packages/flutter_tools/lib/src/build_system/source.dart b/packages/flutter_tools/lib/src/build_system/source.dart index 2af3fc1552..f01b648bfb 100644 --- a/packages/flutter_tools/lib/src/build_system/source.dart +++ b/packages/flutter_tools/lib/src/build_system/source.dart @@ -8,6 +8,15 @@ import '../build_info.dart'; import 'build_system.dart'; import 'exceptions.dart'; +////////////////////////////////////////////////////////////////////// +// // +// ✨ THINKING OF MOVING/REFACTORING THIS FILE? READ ME FIRST! ✨ // +// // +// There is a link to this file in //docs/tool/Engine-artfiacts.md // +// and it would be very kind of you to update the link, if needed. // +// // +////////////////////////////////////////////////////////////////////// + /// A set of source files. abstract class ResolvedFiles { /// Whether any of the sources we evaluated contained a missing depfile.