DEV/flutter_flutter
1
0
Fork 0
mirror of https://github.com/flutter/flutter.git synced 2026-02-20 02:29:02 +08:00
Code Issues Packages Projects Releases Wiki Activity

[web] merge the README files into one (flutter/engine#29896)

Browse Source
This commit is contained in:
Yegor 2021-11-23 14:02:46 -08:00 committed by GitHub
parent 40aa6374ef
commit d76a9822ec
2 changed files with 208 additions and 205 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

211
engine/src/flutter/lib/web_ui/README.md
View File

@ -1,9 +1,159 @@
# Flutter Web Engine
This directory contains the source code for the Web Engine. The easiest way to
hack on the Web Engine is using the `felt` tool. See dev/README.md for details.
This directory contains the source code for the Web Engine.
## Rolling CanvasKit
## Hacking on the Web Engine
If you are setting up a workspace for the first time, start by following the
instructions at [Setting up the Engine development environment][1]. In addition,
it is useful to add the following to your `PATH` environment variable:
- `ENGINE_ROOT/src/flutter/lib/web_ui/dev`, so you can run the `felt` command
from anywhere.
- `FLUTTER_ROOT/bin`, so you can run `dart` and `flutter` commands from
anywhere.
### Using `felt`
`felt` (stands for "Flutter Engine Local Tester") is a command-line tool that
aims to make development in the Flutter web engine more productive and pleasant.
To tell `felt` to do anything you call `felt SUBCOMMAND`, where `SUBCOMMAND` is
one of the available subcommands, which can be listed by running `felt help`. To
get help for a specific subcommand, run `felt help SUBCOMMAND`.
The most useful subcommands are:
- `felt build` - builds a local Flutter Web engine ready to be used by the
Flutter framework. To use the local engine build, pass
`--local-engine=host_debug_unopt` to the `flutter` command, or to
`dev/bots/test.dart` when running a web shard, such as `web_tests`.
- `felt test` - runs web engine tests. By default, this runs all tests using
Chromium. Passing one or more paths to specific tests would run just the
specified tests. Run `felt help test` for more options.
`build` and `test` take the `--watch` option, which automatically reruns the
subcommand when a source file changes. This is handy when you are iterating
quickly.
#### Examples
Builds the web engine, the runs a Flutter app using it:
```
felt build
cd path/to/some/app
flutter --local-engine=host_debug_unopt run -d chrome
```
Runs all tests in Chromium:
```
felt test
```
Runs a specific test:
```
felt test test/engine/util_test.dart
```
Runs multiple specific tests:
```
felt test test/engine/util_test.dart test/alarm_clock_test.dart
```
Enable watch mode so that the test re-runs every time a source file changes:
```
felt test --watch test/engine/util_test.dart
```
Runs tests in Firefox (requires a Linux computer):
```
felt test --browser=firefox
```
Chromium and Firefox support debugging tests using the browser's developer
tools. To run tests in debug mode add `--debug` to the `test` command, e.g.:
```
felt test --debug --browser=firefox test/alarm_clock_test.dart
```
### Optimizing local builds
Concurrency of various build steps can be configured via environment variables:
- `FELT_DART2JS_CONCURRENCY` specifies the number of concurrent `dart2js`
processes used to compile tests. Default value is 8.
- `FELT_TEST_CONCURRENCY` specifies the number of tests run concurrently.
Default value is 10.
If you are a Google employee, you can use an internal instance of Goma (go/ma)
to parallelize your ninja builds. Because Goma compiles code on remote servers,
this option is particularly effective for building on low-powered laptops.
### Test browsers
Chromium, Firefox, and Safari for iOS are version-locked using the
[browser_lock.yaml][2] configuration file. Safari for macOS is supplied by the
computer's operating system. Tests can be run in Edge locally, but Edge is not
enabled on LUCI. Chromium is used as a proxy for Chrome, Edge, and other
Chromium-based browsers.
Changing parameters in the browser lock is effective immediately when running
tests locally. To make changes effective on LUCI follow instructions in
[Rolling Browsers][#rolling-browsers].
#### Local testing in Safari using the iOS Simulator
1. If you haven't already, install Xcode.
2. The iOS version and device type used by web engine tests are specified in
the [browser_lock.yaml][2] file. Install the iOS Simulator version using:
Xcode > Preferences > Components
3. Run `xcrun simctl list devices`. If the simulator you want is not installed
use step 4.
4. Use felt to create a simulator:
```
felt create_simulator
```
To run tests on ios-safari use the one of the following commands:
```
felt test --browser=ios-safari
felt test --browser=ios-safari test/alarm_clock_test.dart
```
### Rolling browsers
When running tests on LUCI using Chromium, LUCI uses the version of Chromium
fetched from CIPD.
Since the engine code and infra recipes do not live in the same repository
there are few steps to follow in order to upgrade a browser's version. For
now these instructins are most relevant to Chrome.
1. Dowload the binaries for the new browser/driver for each operaing system
(macOS, linux, windows).
2. Create CIPD packages for these packages (more documentation is available for
Googlers at go/cipd-flutter-web)
3. Update the version in this repo. Do this by changing the related fields in
`browser_lock.yaml` file.
Resources:
1. For Chrome downloads [link][3].
2. Browser and driver CIPD [packages][4] (required speciall access; ping
hackers-infra on Discord for more information)
3. LUCI web [recipe][5]
4. More general reading on CIPD packages [link][6]
### Rolling CanvasKit
CanvasKit is versioned separately from Skia and rolled manually. Flutter
consumes a pre-built CanvasKit provided by the Skia team, currently hosted on
@ -27,3 +177,58 @@ directly), follow these steps to roll to the new version:
If you have questions, contact the Flutter Web team on Flutter Discord on the
#hackers-web-🌍 channel.
### Configuration files
`browser_lock.yaml` contains the version of browsers we use to test Flutter for
web. Versions are not automatically updated whenever a new release is available.
Instead, we update this file manually once in a while.
`goldens_lock.yaml` refers to a revision in the https://github.com/flutter/goldens
repo. Screenshot tests are compared with the golden files at that revision.
When making engine changes that affect screenshots, first submit a PR to
flutter/goldens updating the screenshots. Then update this file pointing to
the new revision.
`canvaskit_lock.yaml` locks the version of CanvasKit for tests and production
use.
## Troubleshooting
### Can't load Kernel binary: Invalid kernel binary format version.
Sometimes `.dart_tool` cache invalidation fails, and you'll end up with a
cached version of `felt` that is not compatible with the Dart SDK that you're
using.
In that case, any invocation to `felt` will fail with:
```
Can't load Kernel binary: Invalid kernel binary format version.
```
The solution is to delete the cached `felt.snapshot` files under `lib/web_ui`:
```
rm .dart_tool/felt.snapshot*
```
## Hacking on the `felt` tool itself
If you are making changes in the `felt` tool itself, you need to be aware of
Dart snapshots. We create a Dart snapshot of the `felt` tool to make the startup
faster.
To run `felt` from sources, disable the snapshot using the `FELT_USE_SNAPSHOT`
environment variable:
```
FELT_USE_SNAPSHOT=false felt <command>
```
[1]: https://github.com/flutter/flutter/wiki/Setting-up-the-Engine-development-environment
[2]: https://github.com/flutter/engine/blob/main/lib/web_ui/dev/browser_lock.yaml
[3]: https://commondatastorage.googleapis.com/chromium-browser-snapshots/index.html
[4]: https://chrome-infra-packages.appspot.com/p/flutter_internal
[5]: https://flutter.googlesource.com/recipes/+/refs/heads/main/recipes/web_engine.py
[6]: https://chromium.googlesource.com/chromium/src.git/+/main/docs/cipd_and_3pp.md#What-is-CIPD

202
engine/src/flutter/lib/web_ui/dev/README.md
View File

@ -1,202 +0,0 @@
## What's `felt`?
`felt` stands for "Flutter Engine Local Tester". It's a cli tool that aims to make development in the Flutter web engine more productive and pleasant.
## What can `felt` do?
`felt` supports multiple commands as follows:
1. **`felt check-licenses`**: Checks that all Dart and JS source code files contain the correct license headers.
2. **`felt test`**: Runs all or some tests depending on the passed arguments. It supports a watch mode for convenience.
3. **`felt build`**: Builds the engine locally so it can be used by Flutter apps. It also supports a watch mode for more convenience.
You could also run `felt help` or `felt help <command>` to get more information about the available commands and arguments.
## How can I use `felt`?
Once you have your local copy of the engine [setup](https://github.com/flutter/flutter/wiki/Setting-up-the-Engine-development-environment), it's recommended that you add `/path/to/engine/src/flutter/lib/web_ui/dev` to your `PATH`.
Then you would be able to use the `felt` tool from anywhere:
```
felt check-licenses
```
or:
```
felt build --watch
```
If you don't want to add `felt` to your path, you can still invoke it using a relative path like `./web_ui/dev/felt <command>`
## Speeding up your builds and tests
If you are a Google employee, you can use an internal instance of Goma (go/ma)
to parallelize your builds. Because Goma compiles code on remote servers, this
option is particularly effective for building on low-powered laptops.
Concurrency of various build steps can be configured via environment variables:
- `FELT_DART2JS_CONCURRENCY` specifies the number of concurrent `dart2js`
processes used to compile tests. Default value is 8.
- `FELT_TEST_CONCURRENCY` specifies the number of tests run concurrently.
Default value is 10.
## Running web engine tests
To run all tests on Chrome. This will run both integration tests and the unit tests:
```
felt test
```
To run a specific test:
```
felt test test/engine/util_test.dart
```
To enable watch mode so that the test re-runs on every change:
```
felt test --watch test/engine/util_test.dart
```
To run unit tests only:
```
felt test --unit-tests-only
```
To run integration tests only. For now these tests are only available on Chrome Desktop browsers. These tests will fetch the flutter repository for using `flutter drive` and `flutter pub get` commands. The repository will be synced to the youngest commit older than the engine commit.
```
felt test --integration-tests-only
```
To skip cloning the flutter repository use the following flag. This flag can save internet bandwidth. However use with caution. Note the tests results will not be consistent with CIs when this flag is set. flutter command should be set in the PATH for this flag to be useful. This flag can also be used to test local Flutter changes.
```
felt test --integration-tests-only --use-system-flutter
```
To run tests on Firefox (this will work only on a Linux device):
```
felt test --browser=firefox
```
For Chrome and Firefox, the tests run on a version locked on the [browser_lock.yaml](https://github.com/flutter/engine/blob/main/lib/web_ui/dev/browser_lock.yaml). In order to use another version, add the version argument:
```
felt test --browser=firefox --firefox-version=70.0.1
```
To run tests on Safari use the following command. It works on macOS devices and it uses the Safari installed on the OS. Currently there is no option for using another Safari version.
```
felt test --browser=safari
```
One can also use Safari running in iOS Simulator for running unit tests. There are few prerequisite steps:
1. Please make sure that you installed Xcode.
2. The default version used in the tests are in browser_lock.yaml file. Install the ios version to use for simulators: Xcode > Preferences > Components
3. run `xcrun simctl list devices`. If the simulator you want is not installed use step 4.
4. Use felt to create a simulator:
```
felt create_simulator --type='iOS' --version='13.1' --device='iPhone.11.Pro'
```
To run tests on ios-safari use the one of the following commands:
```
felt test --browser=ios-safari
felt test --browser=ios-safari --version='13.1' --device='iPhone.11.Pro'
felt test --browser=ios-safari test/alarm_clock_test.dart
```
To run tests on Windows Edge use the following command. It works on Windows devices and it uses the Edge installed on the OS.
```
felt_windows.bat test --browser=edge
```
To run a single test use the following command. Note that it does not work on Windows.
```
felt test test/golden_tests/engine/canvas_golden_test.dart
```
To debug a test on Chrome:
```
felt test --debug test/golden_tests/engine/canvas_golden_test.dart
```
## Configuration files
`browser_lock.yaml` contains the version of browsers we use to test Flutter for
web. Versions are not automatically updated whenever a new release is available.
Instead, we update this file manually once in a while.
`goldens_lock.yaml` refers to a revision in the https://github.com/flutter/goldens
repo. Screenshot tests are compared with the golden files at that revision.
When making engine changes that affect screenshots, first submit a PR to
flutter/goldens updating the screenshots. Then update this file pointing to
the new revision.
## Developing the `felt` tool
If you are making changes in the `felt` tool itself, you need to be aware of Dart snapshots. We create a Dart snapshot of the `felt` tool to make the startup faster.
To make sure you are running the `felt` tool with your changes included, you would need to stop using the snapshot. This can be achieved through the environment variable `FELT_USE_SNAPSHOT`:
```
FELT_USE_SNAPSHOT=false felt <command>
```
or
```
FELT_USE_SNAPSHOT=0 felt <command>
```
_**Note**: if `FELT_USE_SNAPSHOT` is omitted or has any value other than "false" or "0", the snapshot mode will be enabled._
## Upgrade Browser Version
Since the engine code and infra recipes do not live in the same repository
there are few steps to follow in order to upgrade a browser's version. For
now these instructins are most relevant to Chrome.
1. Dowload the binaries for the new browser/driver for each operaing system (macOS, linux, windows).
2. Create CIPD packages for these packages. (More documentation is available for Googlers. go/cipd-flutter-web)
3. Update the version in this repo. Do this by changing the related fields in `browser_lock.yaml` file.
Note that for LUCI builders, for Chrome both unit and integration tests are using the same browser. (For Firefox [issue](https://github.com/flutter/flutter/issues/71617)
Some useful links:
1. For Chrome downloads [link](https://commondatastorage.googleapis.com/chromium-browser-snapshots/index.html)
2. Browser and driver CIPD [packages](https://chrome-infra-packages.appspot.com/p/flutter_internal) (note: access is restricted for these packages)
3. LUCI web [recipe](https://flutter.googlesource.com/recipes/+/refs/heads/main/recipes/web_engine.py)
4. More general reading on CIPD packages [link](https://chromium.googlesource.com/chromium/src.git/+/main/docs/cipd_and_3pp.md#What-is-CIPD)
## Troubleshooting
### Can't load Kernel binary: Invalid kernel binary format version.
Some times `.dart_tool` cache invalidation fails, and you'll end up with a cached version of `felt` that is not compatible with the Dart SDK that you're using.
In that case, any invocation to `felt` will fail with:
`Can't load Kernel binary: Invalid kernel binary format version.`
The solution is to delete the cached `felt.snapshot` files within `engine/src/flutter/lib/web_ui`:
**`rm .dart_tool/felt.snapshot*`**