From bd2f9f407480752a074fcb4edf19af8f90ce9bc6 Mon Sep 17 00:00:00 2001 From: Harry Terkelsen <1961493+harryterkelsen@users.noreply.github.com> Date: Wed, 29 Oct 2025 17:28:26 -0700 Subject: [PATCH] [web] Add GEMINI.md for web engine customizations (#177413) Adds a `GEMINI.md` for the Flutter Web engine to assist Gemini code assistant in building the web engine and running tests. ## 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]. - [ ] I listed at least one issue that this PR fixes in the description above. - [x] I updated/added relevant documentation (doc comments with `///`). - [ ] I added new tests to check the change I am making, or this PR is [test-exempt]. - [x] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [x] All existing and new tests are passing. If you need help, consider asking for advice on the #hackers-new channel on [Discord]. **Note**: The Flutter team is currently trialing the use of [Gemini Code Assist for GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code). Comments from the `gemini-code-assist` bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed. [Contributor Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview [Tree Hygiene]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md [test-exempt]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests [Flutter Style Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md [Features we expect every widget to implement]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement [CLA]: https://cla.developers.google.com/ [flutter/tests]: https://github.com/flutter/tests [breaking change policy]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes [Discord]: https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md [Data Driven Fixes]: https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md --- engine/src/flutter/lib/web_ui/GEMINI.md | 103 ++++++++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 engine/src/flutter/lib/web_ui/GEMINI.md diff --git a/engine/src/flutter/lib/web_ui/GEMINI.md b/engine/src/flutter/lib/web_ui/GEMINI.md new file mode 100644 index 00000000000..8cf6678ecc2 --- /dev/null +++ b/engine/src/flutter/lib/web_ui/GEMINI.md @@ -0,0 +1,103 @@ +# Customizing the Flutter Web Engine + +This document describes how to build the engine and run tests for the Flutter Web Engine using the `felt` tool. + +## `felt`: Flutter Engine Local Tester + +`felt` is a command-line tool for building and testing the Flutter web engine. To use it, you need to add `FLUTTER_ROOT/engine/src/flutter/lib/web_ui/dev` to your `PATH`. + +Before building the engine, ensure your dependencies are up to date by running the following command from the root of your Flutter checkout: + +```bash +gclient sync -D +``` + +### Building the Engine with `felt` + +The `felt build` command builds web engine targets. You can specify targets to build, or build all of them by default. + +**Common Targets:** + +* `sdk`: The Flutter Web SDK. +* `canvaskit`: Flutter's version of CanvasKit. +* `canvaskit_chromium`: A Chromium-optimized version of CanvasKit. +* `skwasm`: Experimental Skia Wasm module renderer. + +**Examples:** + +Build all web engine targets: + +```bash +felt build +``` + +Build the `sdk` and `canvaskit` targets: + +```bash +felt build sdk canvaskit +``` + +### Testing with `felt` + +The `felt test` command compiles and runs web engine unit tests. + +**Useful Flags:** + +* `--compile`: Compiles test bundles. +* `--run`: Runs unit tests. +* `--copy-artifacts`: Copies build artifacts needed for tests. +* `--list`: Lists all test suites and bundles. +* `--verbose`: Outputs extra debugging information. +* `--start-paused`: Pauses tests before starting to allow setting breakpoints. +* `--browser`: Filters tests by browser (e.g., `chrome`, `firefox`, `safari`). +* `--compiler`: Filters tests by compiler (e.g., `dart2js`, `dart2wasm`). +* `--renderer`: Filters tests by renderer (e.g., `html`, `canvaskit`, `skwasm`). + +**Examples:** + +Run all test suites: + +```bash +felt test +``` + +Run a specific test file: + +```bash +felt test test/engine/util_test.dart +``` + +Run tests that use the `dart2wasm` compiler: + +```bash +felt test --compiler dart2wasm +``` + +Run tests on Chrome using the CanvasKit renderer: + +```bash +felt test --browser chrome --renderer canvaskit +``` + +### Generating Golden Files + +To update the golden files for screenshot tests, use the `--update-screenshot-goldens` flag with the `felt test` command. This is useful when a browser update or other change affects the rendering of a test. + +The generated golden files are placed in the `.dart_tool/skia_gold` directory, under subdirectories for each test configuration (e.g., `chrome-dart2js-canvaskit-ui`). + +**Example:** + +```bash +felt test --update-screenshot-goldens test/ui/some_golden_test.dart +``` + +### Test Directory Structure + +The `test` directory contains the following subdirectories: + +* `canvaskit`: Tests for the CanvasKit backend. +* `common`: Common utilities for tests. +* `engine`: Core engine logic tests. +* `fallbacks`: Tests for fallback mechanisms (like fonts). +* `ui`: Tests for the `dart:ui` layer implementation for the web, including most of the golden tests. +* `webparagraph`: Tests related to paragraph and text layout on the web.