Document how engine.version (is/will be) computed (#164335)
Towards https://github.com/flutter/flutter/issues/163896.
This commit is contained in:
Matan Lurey
GitHub
parent
eb66d03350
commit
a19509c6c3
@ -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();
|
||||
|
||||
@ -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:
|
||||
|
||||
67
docs/tool/Engine-artifacts.md
Normal file
67
docs/tool/Engine-artifacts.md
Normal file
@ -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).
|
||||
|
||||
|
||||
|
||||
> [!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: <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>
|
||||
UseMergeBase: <code>git merge-base HEAD upstream/master</code>
|
||||
|
||||
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)
|
||||
@ -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,
|
||||
|
||||
@ -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.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user