diff --git a/.github/labeler.yml b/.github/labeler.yml index a5c599b829..cfc4c0f517 100644 --- a/.github/labeler.yml +++ b/.github/labeler.yml @@ -57,6 +57,7 @@ engine: - changed-files: - any-glob-to-any-file: - bin/internal/engine.version + - docs/engine/**/* 'f: cupertino': - changed-files: @@ -152,6 +153,11 @@ team-ecosystem: - any-glob-to-any-file: - docs/ecosystem/**/* +team-engine: + - changed-files: + - any-glob-to-any-file: + - docs/engine/**/* + tool: - changed-files: - any-glob-to-any-file: diff --git a/dev/bots/analyze.dart b/dev/bots/analyze.dart index b42aa92550..98f39e3f54 100644 --- a/dev/bots/analyze.dart +++ b/dev/bots/analyze.dart @@ -1304,6 +1304,8 @@ Future verifyRepositoryLinks(String workingDirectory) async { // Repos whose default branch is still 'master' const Set repoExceptions = { + 'bdero/flutter-gpu-examples', + 'chromium/chromium', 'clojure/clojure', 'dart-lang/test', // TODO(guidezpl): remove when https://github.com/dart-lang/test/issues/2209 is closed 'eseidelGoogle/bezier_perf', diff --git a/docs/unsorted_wiki/The-Engine-architecture.md b/docs/about/The-Engine-architecture.md similarity index 98% rename from docs/unsorted_wiki/The-Engine-architecture.md rename to docs/about/The-Engine-architecture.md index 8406779e60..24b7da33bf 100644 --- a/docs/unsorted_wiki/The-Engine-architecture.md +++ b/docs/about/The-Engine-architecture.md @@ -13,7 +13,7 @@ The following diagram gives an overview of the pieces that make up a regular Flu * Implements business logic. * Owned by app developer. -#### Framework ([source code](https://github.com/flutter/flutter/tree/master/packages/flutter/lib)) +#### Framework ([source code](https://github.com/flutter/flutter/tree/main/packages/flutter/lib)) * Provides higher-level API to build high-quality apps (e.g. widgets, hit-testing, gesture detection, accessibility, text input, etc.). * Composites the app's widget tree into a scene. @@ -34,7 +34,7 @@ The following diagram gives an overview of the pieces that make up a regular Flu ## Architecture overview -Flutter's engine takes core technologies, Skia, a 2D graphics rendering library, and Dart, a VM for a garbage-collected object-oriented language, and hosts them in a shell. Different platforms have different shells, for example we have shells for [Android](https://github.com/flutter/engine/tree/main/shell/platform/android) and [iOS](https://github.com/flutter/engine/tree/main/shell/platform/darwin). We also have an [embedder API](https://github.com/flutter/engine/tree/main/shell/platform/embedder) which allows Flutter's engine to be used as a library (see [[Custom Flutter Engine Embedders]]). +Flutter's engine takes core technologies, Skia, a 2D graphics rendering library, and Dart, a VM for a garbage-collected object-oriented language, and hosts them in a shell. Different platforms have different shells, for example we have shells for [Android](https://github.com/flutter/engine/tree/main/shell/platform/android) and [iOS](https://github.com/flutter/engine/tree/main/shell/platform/darwin). We also have an [embedder API](https://github.com/flutter/engine/tree/main/shell/platform/embedder) which allows Flutter's engine to be used as a library (see [Custom Flutter Engine Embedders](../engine/Custom-Flutter-Engine-Embedders.md)). The shells implement platform-specific code such as communicating with IMEs (on-screen keyboards) and the system's application lifecycle events. diff --git a/docs/unsorted_wiki/Why-we-have-a-separate-engine-repo.md b/docs/about/Why-we-have-a-separate-engine-repo.md similarity index 100% rename from docs/unsorted_wiki/Why-we-have-a-separate-engine-repo.md rename to docs/about/Why-we-have-a-separate-engine-repo.md diff --git a/docs/unsorted_wiki/Crashes.md b/docs/engine/Crashes.md similarity index 97% rename from docs/unsorted_wiki/Crashes.md rename to docs/engine/Crashes.md index 16afc191d2..3d20b20b85 100644 --- a/docs/unsorted_wiki/Crashes.md +++ b/docs/engine/Crashes.md @@ -8,7 +8,7 @@ The easiest way to symbolicate stack traces for Android and iOS is running the [ 1. Get the Flutter Framework or Flutter Engine revision from the report. If you have the Engine revision, skip to step 3. -2. Get the Engine revision from the Framework (this could be automated). https://github.com/flutter/flutter/blob/master/bin/internal/engine.version is the file which contains the information. Substitute the framework hash for `master` in that url. +2. Get the Engine revision from the Framework (this could be automated). https://github.com/flutter/flutter/blob/main/bin/internal/engine.version is the file which contains the information. Substitute the framework hash for `main` in that url. 3. With the full engine revision (e.g. cea5ed2b9be42a981eac762af3664e4a17d0a53f), you can now get the proper symbol files: diff --git a/docs/unsorted_wiki/Custom-Flutter-Engine-Embedders.md b/docs/engine/Custom-Flutter-Engine-Embedders.md similarity index 88% rename from docs/unsorted_wiki/Custom-Flutter-Engine-Embedders.md rename to docs/engine/Custom-Flutter-Engine-Embedders.md index cf9d543fc2..3c8a74f666 100644 --- a/docs/unsorted_wiki/Custom-Flutter-Engine-Embedders.md +++ b/docs/engine/Custom-Flutter-Engine-Embedders.md @@ -12,11 +12,11 @@ This is a very low level API and is not suitable for beginners. * The binary is not stripped and contains debug information. Embedders are advised to strip the binary before deployment. * The Windows buildbot uploads the artifacts to a known location. Access it here [`https://storage.googleapis.com/flutter_infra_release/flutter/FLUTTER_ENGINE/windows-x64/windows-x64-embedder.zip`](https://storage.googleapis.com/flutter_infra_release/flutter/080fbcb1759e5916f0d6cdcdfd945c053320e6b3/windows-x64/windows-x64-embedder.zip) * Replace `FLUTTER_ENGINE` with the SHA of the Flutter engine you wish to use. - * You can also obtain that SHA from the [`engine.version`](https://github.com/flutter/flutter/blob/master/bin/internal/engine.version) file in your Flutter framework checkout. This allows you to exactly match the engine version with the Flutter framework version. + * You can also obtain that SHA from the [`engine.version`](https://github.com/flutter/flutter/blob/main/bin/internal/engine.version) file in your Flutter framework checkout. This allows you to exactly match the engine version with the Flutter framework version. * The Flutter engine API has no platform specific dependencies, has a stable ABI and is available in its entirety in a [single C header file available here](https://github.com/flutter/engine/blob/main/shell/platform/embedder/embedder.h). * To use as a guide, you may use [this example embedder that uses GLFW](https://github.com/flutter/engine/blob/main/examples/glfw/FlutterEmbedderGLFW.cc) for window management and rendering. -While we do not object to teams creating custom builds of the Flutter engine for their purposes, we do not support this configuration. Not supporting it means that we do not commit to any timelines for fixing bugs that may come up in such a configuration, even for customers for which we would usually be willing to make commitments (see the [[Issue Hygiene]] page). It also means that we encourage teams to view such configurations as short-term solutions only and encourage teams to transition away from such configurations at the earliest possible opportunity. +While we do not object to teams creating custom builds of the Flutter engine for their purposes, we do not support this configuration. Not supporting it means that we do not commit to any timelines for fixing bugs that may come up in such a configuration, even for customers for which we would usually be willing to make commitments (see the [Issue Hygiene](https://github.com/flutter/flutter/wiki/Issue-hygiene) page). It also means that we encourage teams to view such configurations as short-term solutions only and encourage teams to transition away from such configurations at the earliest possible opportunity. We do not expect custom engine builds to be long-term sustainable. They are not supported on any platform where we plan to be the publisher of a Flutter runtime distinct from the applications that run on the runtime, and they require significant effort to port to our new target platforms such as Web and desktop. There is also an expensive maintenance burden (for example, if we add new features, a custom engine build would need to be updated to support that feature). diff --git a/docs/unsorted_wiki/Custom-Flutter-Engine-Embedding-in-AOT-Mode.md b/docs/engine/Custom-Flutter-Engine-Embedding-in-AOT-Mode.md similarity index 100% rename from docs/unsorted_wiki/Custom-Flutter-Engine-Embedding-in-AOT-Mode.md rename to docs/engine/Custom-Flutter-Engine-Embedding-in-AOT-Mode.md diff --git a/docs/unsorted_wiki/Debugging-the-engine.md b/docs/engine/Debugging-the-engine.md similarity index 92% rename from docs/unsorted_wiki/Debugging-the-engine.md rename to docs/engine/Debugging-the-engine.md index db7bc0c004..114160c9c5 100644 --- a/docs/unsorted_wiki/Debugging-the-engine.md +++ b/docs/engine/Debugging-the-engine.md @@ -1,10 +1,10 @@ This page has some hints about debugging the engine. -See also [[Crashes]] for advice on handling engine crashes (specifically around obtaining stack traces, and reporting crashes in AOT Dart code). +See also [Crashes](Crashes.md) for advice on handling engine crashes (specifically around obtaining stack traces, and reporting crashes in AOT Dart code). ## Running a Flutter app with a local engine -First, make sure the appropriate version of the engine is built (see [[Compiling the engine]]). +First, make sure the appropriate version of the engine is built (see [Compiling the engine](./dev/Compiling-the-engine.md)). ### Using the Flutter tool @@ -47,7 +47,7 @@ You will need to add a new [launch configuration](https://code.visualstudio.com/ ## Bisecting a roll failure -If the engine roll is failing (see [[Autorollers]]), you can use `git bisect` on the engine repo to track down the offending commit, using the `--local-engine` and `--local-engine-host` arguments as described above to run the failing framework test with each version of the engine. +If the engine roll is failing (see [Autorollers](https://github.com/flutter/flutter/wiki/Autorollers)), you can use `git bisect` on the engine repo to track down the offending commit, using the `--local-engine` and `--local-engine-host` arguments as described above to run the failing framework test with each version of the engine. ## Tracing OpenGL calls in Skia @@ -77,7 +77,7 @@ You can also set a breakpoint directly with [lldb](https://lldb.llvm.org/tutoria ## Debugging Android builds with gdb -See https://github.com/flutter/engine/blob/master/sky/tools/flutter_gdb#L13 +See https://github.com/flutter/engine/blob/main/sky/tools/flutter_gdb#L13 ## Debugging native engine code on Android with Android Studio diff --git a/docs/unsorted_wiki/Engine-disk-footprint.md b/docs/engine/Engine-disk-footprint.md similarity index 82% rename from docs/unsorted_wiki/Engine-disk-footprint.md rename to docs/engine/Engine-disk-footprint.md index 404b10f5f4..6108aaeaf9 100644 --- a/docs/unsorted_wiki/Engine-disk-footprint.md +++ b/docs/engine/Engine-disk-footprint.md @@ -10,7 +10,7 @@ Alternatively, a link to a treemap can be constructed as follows: ## Benchmarks -In [devicelab](https://github.com/flutter/flutter/tree/master/dev/devicelab) we run various benchmarks to track the APK/IPA sizes and various (engine) artifacts contained within. These benchmarks run for every commit to [flutter/flutter](https://github.com/flutter/flutter) and are visible on our [build dashboard](https://flutter-dashboard.appspot.com/). The most relevant benchmarks for engine size are: +In [devicelab](https://github.com/flutter/flutter/tree/main/dev/devicelab) we run various benchmarks to track the APK/IPA sizes and various (engine) artifacts contained within. These benchmarks run for every commit to [flutter/flutter](https://github.com/flutter/flutter) and are visible on our [build dashboard](https://flutter-dashboard.appspot.com/). The most relevant benchmarks for engine size are: * APK/IPA size of Flutter Gallery * Android: `flutter_gallery_android__compile/release_size_bytes` diff --git a/docs/unsorted_wiki/Engine-specific-Service-Protocol-extensions.md b/docs/engine/Engine-specific-Service-Protocol-extensions.md similarity index 94% rename from docs/unsorted_wiki/Engine-specific-Service-Protocol-extensions.md rename to docs/engine/Engine-specific-Service-Protocol-extensions.md index be34b20c28..73e5b28fcd 100644 --- a/docs/unsorted_wiki/Engine-specific-Service-Protocol-extensions.md +++ b/docs/engine/Engine-specific-Service-Protocol-extensions.md @@ -1,4 +1,4 @@ -The Flutter engine adds several extensions to the [Dart VM Service Protocol](https://github.com/dart-lang/sdk/blob/master/runtime/vm/service/service.md). The Flutter Engine specific extensions are documented here. Applications may also choose to register their [own extensions](https://api.dartlang.org/stable/1.24.3/dart-developer/registerExtension.html). +The Flutter engine adds several extensions to the [Dart VM Service Protocol](https://github.com/dart-lang/sdk/blob/main/runtime/vm/service/service.md). The Flutter Engine specific extensions are documented here. Applications may also choose to register their [own extensions](https://api.dartlang.org/stable/1.24.3/dart-developer/registerExtension.html). ## List views: `_flutter.listViews` diff --git a/docs/unsorted_wiki/Flutter's-modes.md b/docs/engine/Flutter's-modes.md similarity index 100% rename from docs/unsorted_wiki/Flutter's-modes.md rename to docs/engine/Flutter's-modes.md diff --git a/docs/unsorted_wiki/Flutter-engine-operation-in-AOT-Mode.md b/docs/engine/Flutter-engine-operation-in-AOT-Mode.md similarity index 100% rename from docs/unsorted_wiki/Flutter-engine-operation-in-AOT-Mode.md rename to docs/engine/Flutter-engine-operation-in-AOT-Mode.md diff --git a/docs/unsorted_wiki/Image-Codecs-in-the-Flutter-Engine.md b/docs/engine/Image-Codecs-in-the-Flutter-Engine.md similarity index 100% rename from docs/unsorted_wiki/Image-Codecs-in-the-Flutter-Engine.md rename to docs/engine/Image-Codecs-in-the-Flutter-Engine.md diff --git a/docs/unsorted_wiki/JIT-Release-Modes.md b/docs/engine/JIT-Release-Modes.md similarity index 100% rename from docs/unsorted_wiki/JIT-Release-Modes.md rename to docs/engine/JIT-Release-Modes.md diff --git a/docs/unsorted_wiki/Life-of-a-Flutter-Frame.md b/docs/engine/Life-of-a-Flutter-Frame.md similarity index 100% rename from docs/unsorted_wiki/Life-of-a-Flutter-Frame.md rename to docs/engine/Life-of-a-Flutter-Frame.md diff --git a/docs/engine/README.md b/docs/engine/README.md new file mode 100644 index 0000000000..3a9a2945f8 --- /dev/null +++ b/docs/engine/README.md @@ -0,0 +1,32 @@ +This is an index of team-facing documentation for the [flutter/engine repository](https://github.com/flutter/engine/). + +- [Accessibility on Windows](https://github.com/flutter/flutter/wiki/Accessibility-on-Windows) +- [Code signing metadata](./release/Code-signing-metadata.md) for engine binaries +- [Compiling the engine](./dev/Compiling-the-engine.md) +- [Comparing AOT Snapshot Sizes](./benchmarks/Comparing-AOT-Snapshot-Sizes.md) +- [Crashes](./Crashes.md) +- [Custom Flutter engine embedders](./Custom-Flutter-Engine-Embedders.md) +- [Custom Flutter Engine Embedding in AOT Mode](./Custom-Flutter-Engine-Embedding-in-AOT-Mode.md) +- [Debugging the engine](./Debugging-the-engine.md) +- [Flutter engine operation in AOT Mode](./Flutter-engine-operation-in-AOT-Mode.md) +- [Flutter Test Fonts](https://github.com/flutter/flutter/wiki/Flutter-Test-Fonts) +- [Flutter's modes](./Flutter's-modes.md) +- [Engine Clang Tidy Linter](./ci/Engine-Clang-Tidy-Linter.md) +- [Engine disk footprint](./Engine-disk-footprint.md) +- [Engine-specific Service Protocol extensions](./Engine-specific-Service-Protocol-extensions.md) +- [Engine pre‐submits and post‐submits](./ci/Engine-pre‐submits-and-post‐submits.md) +- [Image Codecs in the Flutter Engine](Image-Codecs-in-the-Flutter-Engine.md) +- [Impeller](./impeller/README.md) documentation index +- [Life of a Flutter Frame](Life-of-a-Flutter-Frame.md) +- [Reduce Flutter engine size with MLGO](Reduce-Flutter-engine-size-with-MLGO.md) +- [Resolving common build failures](https://github.com/flutter/flutter/wiki/Resolving-common-build-failures) +- [Setting up the Engine development environment](./dev/Setting-up-the-Engine-development-environment.md) +- [Supporting legacy platforms](Supporting-legacy-platforms.md) +- [Testing Android Changes in the Devicelab on an Emulator](https://github.com/flutter/flutter/wiki/Testing-Android-Changes-in-the-Devicelab-on-an-Emulator) +- [Testing the engine](./testing/Testing-the-engine.md) +- [Testing presubmit Engine PRs with the Flutter framework](Testing-presubmit-Engine-PRs-with-the-Flutter-framework.md) +- [The Engine architecture](../about/The-Engine-architecture.md) +- [Upgrading Engine's Android API version](https://github.com/flutter/flutter/wiki/Upgrading-Engine%27s-Android-API-version) +- [Using the Dart Development Service (DDS) and Flutter DevTools with a custom Flutter Engine Embedding](./Using-the-Dart-Development-Service-(DDS)-and-Flutter-DevTools-with-a-custom-Flutter-Engine-Embedding.md) +- [Using Sanitizers with the Flutter Engine](./Using-Sanitizers-with-the-Flutter-Engine.md) +- [Why we have a separate engine repo](../about/Why-we-have-a-separate-engine-repo.md) diff --git a/docs/unsorted_wiki/Reduce-Flutter-engine-size-with-MLGO.md b/docs/engine/Reduce-Flutter-engine-size-with-MLGO.md similarity index 100% rename from docs/unsorted_wiki/Reduce-Flutter-engine-size-with-MLGO.md rename to docs/engine/Reduce-Flutter-engine-size-with-MLGO.md diff --git a/docs/unsorted_wiki/Supporting-legacy-platforms.md b/docs/engine/Supporting-legacy-platforms.md similarity index 100% rename from docs/unsorted_wiki/Supporting-legacy-platforms.md rename to docs/engine/Supporting-legacy-platforms.md diff --git a/docs/unsorted_wiki/Testing-presubmit-Engine-PRs-with-the-Flutter-framework.md b/docs/engine/Testing-presubmit-Engine-PRs-with-the-Flutter-framework.md similarity index 96% rename from docs/unsorted_wiki/Testing-presubmit-Engine-PRs-with-the-Flutter-framework.md rename to docs/engine/Testing-presubmit-Engine-PRs-with-the-Flutter-framework.md index 999a1112e2..d0961a2388 100644 --- a/docs/unsorted_wiki/Testing-presubmit-Engine-PRs-with-the-Flutter-framework.md +++ b/docs/engine/Testing-presubmit-Engine-PRs-with-the-Flutter-framework.md @@ -39,7 +39,7 @@ Any other failures are possibly due to the changes to flutter/engine, so deflake # 5. Devicelab tests -A subset of devicelab tests are available for optionally running in presubmit on flutter/flutter PRs. They are the tests listed in the flutter/flutter [.ci.yaml](https://github.com/flutter/flutter/blob/master/.ci.yaml) file that are prefixed with `Linux_android`, `Mac_android`, and `Mac_ios`. +A subset of devicelab tests are available for optionally running in presubmit on flutter/flutter PRs. They are the tests listed in the flutter/flutter [.ci.yaml](https://github.com/flutter/flutter/blob/main/.ci.yaml) file that are prefixed with `Linux_android`, `Mac_android`, and `Mac_ios`. To run one of these tests, remove the line `presubmit: false` from the `.ci.yaml` file under the test you'd like to run. For an example, see the PR [here](https://github.com/flutter/flutter/pull/135254). diff --git a/docs/unsorted_wiki/Using-Sanitizers-with-the-Flutter-Engine.md b/docs/engine/Using-Sanitizers-with-the-Flutter-Engine.md similarity index 100% rename from docs/unsorted_wiki/Using-Sanitizers-with-the-Flutter-Engine.md rename to docs/engine/Using-Sanitizers-with-the-Flutter-Engine.md diff --git a/docs/unsorted_wiki/Using-the-Dart-Development-Service-(DDS)-and-Flutter-DevTools-with-a-custom-Flutter-Engine-Embedding.md b/docs/engine/Using-the-Dart-Development-Service-(DDS)-and-Flutter-DevTools-with-a-custom-Flutter-Engine-Embedding.md similarity index 100% rename from docs/unsorted_wiki/Using-the-Dart-Development-Service-(DDS)-and-Flutter-DevTools-with-a-custom-Flutter-Engine-Embedding.md rename to docs/engine/Using-the-Dart-Development-Service-(DDS)-and-Flutter-DevTools-with-a-custom-Flutter-Engine-Embedding.md diff --git a/docs/unsorted_wiki/Comparing-AOT-Snapshot-Sizes.md b/docs/engine/benchmarks/Comparing-AOT-Snapshot-Sizes.md similarity index 100% rename from docs/unsorted_wiki/Comparing-AOT-Snapshot-Sizes.md rename to docs/engine/benchmarks/Comparing-AOT-Snapshot-Sizes.md diff --git a/docs/unsorted_wiki/Engine-Clang-Tidy-Linter.md b/docs/engine/ci/Engine-Clang-Tidy-Linter.md similarity index 100% rename from docs/unsorted_wiki/Engine-Clang-Tidy-Linter.md rename to docs/engine/ci/Engine-Clang-Tidy-Linter.md diff --git a/docs/unsorted_wiki/Engine-pre‐submits-and-post‐submits.md b/docs/engine/ci/Engine-pre‐submits-and-post‐submits.md similarity index 100% rename from docs/unsorted_wiki/Engine-pre‐submits-and-post‐submits.md rename to docs/engine/ci/Engine-pre‐submits-and-post‐submits.md diff --git a/docs/unsorted_wiki/Compiling-the-engine.md b/docs/engine/dev/Compiling-the-engine.md similarity index 95% rename from docs/unsorted_wiki/Compiling-the-engine.md rename to docs/engine/dev/Compiling-the-engine.md index 64c645c591..b5db8a0917 100644 --- a/docs/unsorted_wiki/Compiling-the-engine.md +++ b/docs/engine/dev/Compiling-the-engine.md @@ -73,14 +73,14 @@ Run the following steps, from the `src` directory created in [Setting up the Eng * For MacOS, you will need older version of XCode(9.4 or below) to compile android_debug_unopt and android_debug_unopt_x86. If you only care about x64, you can ignore this This builds a debug-enabled ("unoptimized") binary configured to run Dart in -checked mode ("debug"). There are other versions, see [[Flutter's modes]]. +checked mode ("debug"). There are other versions, see [Flutter's modes](../Flutter's-modes.md). If you're going to be debugging crashes in the engine, make sure you add `android:debuggable="true"` to the `` element in the `android/AndroidManifest.xml` file for the Flutter app you are using to test the engine. -See [[The flutter tool]] for instructions on how to use the `flutter` tool with a local engine. +See [The flutter tool](https://github.com/flutter/flutter/wiki/The-flutter-tool) for instructions on how to use the `flutter` tool with a local engine. You will typically use the `android_debug_unopt` build to debug the engine on a device, and `android_debug_unopt_x64` to debug in on a simulator. Modifying dart sources in the engine will require adding a `dependency_override` section in you app's `pubspec.yaml` as detailed @@ -125,7 +125,7 @@ Run the following steps, from the `src` directory created in the steps above: 3. `./flutter/tools/gn --ios --unoptimized` to prepare build files for device-side executables (or `--ios --simulator --unoptimized` for simulator). * This also produces an Xcode project for working with the engine source code at `out/ios_debug_unopt/flutter_engine.xcodeproj` - * For a discussion on the various flags and modes, see [[Flutter's modes]]. + * For a discussion on the various flags and modes, see [Flutter's modes](../Flutter's-modes.md). * Add the `--simulator-cpu=arm64` argument for an arm64 Mac simulator to output to `out/ios_debug_sim_unopt_arm64`. 4. `./flutter/tools/gn --unoptimized` to prepare the build files for host-side executables. @@ -133,7 +133,7 @@ Run the following steps, from the `src` directory created in the steps above: 5. `ninja -C out/ios_debug_unopt && ninja -C out/host_debug_unopt` to build all artifacts (use `out/ios_debug_sim_unopt` for Simulator). -See [[The flutter tool]] for instructions on how to use the `flutter` tool with a local engine. +See [The flutter tool](https://github.com/flutter/flutter/wiki/The-flutter-tool) for instructions on how to use the `flutter` tool with a local engine. You will typically use the `ios_debug_unopt` build to debug the engine on a device, and `ios_debug_sim_unopt` to debug in on a simulator. Modifying dart sources in the engine will require adding a `dependency_override` section in you app's `pubspec.yaml` as detailed @@ -155,7 +155,7 @@ These steps build the desktop embedding, and the engine used by `flutter test` o 4. `ninja -C out/host_debug_unopt` to build a desktop unoptimized binary. * If you skipped `--unoptimized`, use `ninja -C out/host_debug` instead. -See [[The flutter tool]] for instructions on how to use the `flutter` tool with a local engine. +See [The flutter tool](https://github.com/flutter/flutter/wiki/The-flutter-tool) for instructions on how to use the `flutter` tool with a local engine. You will typically use the `host_debug_unopt` build in this setup. Modifying dart sources in the engine will require adding a `dependency_override` section in you app's `pubspec.yaml` as detailed [here](https://github.com/flutter/flutter/wiki/The-flutter-tool#using-a-locally-built-engine-with-the-flutter-tool). @@ -327,4 +327,4 @@ Running `gclient sync` does not update the tags, there are two solutions: 1. under `engine/src/third_party/dart` run `git fetch --tags origin` 2. or run gclient sync with with tags parameter: `gclient sync --with_tags` -_See also: [[Debugging the engine]], which includes instructions on running a Flutter app with a local engine._ +_See also: [Debugging the engine](../Debugging-the-engine.md), which includes instructions on running a Flutter app with a local engine._ diff --git a/docs/unsorted_wiki/Setting-up-the-Engine-development-environment.md b/docs/engine/dev/Setting-up-the-Engine-development-environment.md similarity index 95% rename from docs/unsorted_wiki/Setting-up-the-Engine-development-environment.md rename to docs/engine/dev/Setting-up-the-Engine-development-environment.md index 88f45d60bb..523c270f84 100644 --- a/docs/unsorted_wiki/Setting-up-the-Engine-development-environment.md +++ b/docs/engine/dev/Setting-up-the-Engine-development-environment.md @@ -1,5 +1,5 @@ _If you've already built the engine and have the configuration set up but merely need a refresher on -actually compiling the code, see [[Compiling the engine]]._ +actually compiling the code, see [Compiling the engine](Compiling-the-engine.md)._ _If you are checking these instructions to refresh your memory and your fork of the engine is stale, make sure to merge up to HEAD before doing a `gclient sync`._ @@ -91,9 +91,9 @@ gclient sync ## Next steps: - * [[Compiling the engine]] explains how to actually get builds, now that you have the code. - * [[The flutter tool]] has a section explaining how to use custom engine builds. - * [[Signing commits]], to configure your environment to securely sign your commits. + * [Compiling the engine](Compiling-the-engine.md) explains how to actually get builds, now that you have the code. + * [The flutter tool](https://github.com/flutter/flutter/wiki/The-flutter-tool) has a section explaining how to use custom engine builds. + * [Signing commits](https://github.com/flutter/flutter/wiki/Signing-commits), to configure your environment to securely sign your commits. ## Editor autocomplete support diff --git a/docs/unsorted_wiki/Flutter-GPU.md b/docs/engine/impeller/Flutter-GPU.md similarity index 91% rename from docs/unsorted_wiki/Flutter-GPU.md rename to docs/engine/impeller/Flutter-GPU.md index 8aab02c513..96d6a6baca 100644 --- a/docs/unsorted_wiki/Flutter-GPU.md +++ b/docs/engine/impeller/Flutter-GPU.md @@ -18,7 +18,7 @@ Once released, Flutter GPU will be shipped as part of the Flutter SDK in the for Flutter GPU is currently unfinished, extremely experimental, and not well documented. [bdero](https://github.com/bdero) is actively developing and testing Flutter GPU against the MacOS desktop embedder; shader compilation and import likely don't function correctly on other platforms yet. However, if you wish to experiment with Flutter GPU, it is possible to do so without a custom Engine build: 1. Update your Flutter checkout to the latest version in the [master channel](https://docs.flutter.dev/release/upgrade#other-channels). -1. Clone [Flutter Engine](https://github.com/flutter/engine) and checkout the Engine commit that the Flutter master channel is currently pinned to. This can be found in the [`bin/internal/engine.version` file](https://github.com/flutter/flutter/blob/master/bin/internal/engine.version) of the main Flutter repository. +1. Clone [Flutter Engine](https://github.com/flutter/engine) and checkout the Engine commit that the Flutter master channel is currently pinned to. This can be found in the [`bin/internal/engine.version` file](https://github.com/flutter/flutter/blob/main/bin/internal/engine.version) of the main Flutter repository. ```sh git clone https://github.com/flutter/engine.git cd engine @@ -40,7 +40,7 @@ Flutter GPU is currently unfinished, extremely experimental, and not well docume ## Reporting bugs -If you run into issues while using Flutter GPU, please file a bug using the standard [bug report template](https://github.com/flutter/flutter/issues/new?assignees=&labels=&projects=&template=2_bug.yml). Additionally, mention "Flutter GPU" in the title, label the bug with the `e: impeller` label, and tag [bdero](https://github.com/bdero) in the issue description. +If you run into issues while using Flutter GPU, please file a bug using the standard [bug report template](https://github.com/flutter/flutter/issues/new?template=2_bug.yml). Additionally, mention "Flutter GPU" in the title, label the bug with the `e: impeller` label, and tag [bdero](https://github.com/bdero) in the issue description. ## Questions or feedback? diff --git a/docs/unsorted_wiki/Impeller-Scene.md b/docs/engine/impeller/Impeller-Scene.md similarity index 100% rename from docs/unsorted_wiki/Impeller-Scene.md rename to docs/engine/impeller/Impeller-Scene.md diff --git a/docs/engine/impeller/README.md b/docs/engine/impeller/README.md new file mode 100644 index 0000000000..0f04e700ad --- /dev/null +++ b/docs/engine/impeller/README.md @@ -0,0 +1,7 @@ +_For user information about Flutter's new rendering backend, check out [Impeller preview](https://docs.flutter.dev/perf/impeller)._ + +Team-facing documentation specific to Impeller: + +- [Setting up MoltenVK on macOS for Impeller](Setting-up-MoltenVK-on-macOS-for-Impeller.md) +- [Flutter GPU](Flutter-GPU.md) +- [Instructions for playing with the Impeller Scene demo|Impeller Scene](Impeller-Scene.md) diff --git a/docs/unsorted_wiki/Setting-up-MoltenVK-on-macOS-for-Impeller.md b/docs/engine/impeller/Setting-up-MoltenVK-on-macOS-for-Impeller.md similarity index 100% rename from docs/unsorted_wiki/Setting-up-MoltenVK-on-macOS-for-Impeller.md rename to docs/engine/impeller/Setting-up-MoltenVK-on-macOS-for-Impeller.md diff --git a/docs/unsorted_wiki/Code-signing-metadata.md b/docs/engine/release/Code-signing-metadata.md similarity index 100% rename from docs/unsorted_wiki/Code-signing-metadata.md rename to docs/engine/release/Code-signing-metadata.md diff --git a/docs/unsorted_wiki/Testing-the-engine.md b/docs/engine/testing/Testing-the-engine.md similarity index 97% rename from docs/unsorted_wiki/Testing-the-engine.md rename to docs/engine/testing/Testing-the-engine.md index 4dd58fde75..e8c0f278d7 100644 --- a/docs/unsorted_wiki/Testing-the-engine.md +++ b/docs/engine/testing/Testing-the-engine.md @@ -100,7 +100,7 @@ containing the test runner and dependencies. Then it uses the system `java` runtime to execute the .jar. JDK v8 must be set as your `$JAVA_HOME` to run the Robolectric tests. -See [[Setting-up-the-Engine-development-environment#using-vscode-as-an-ide-for-the-android-embedding-java]] +See [Setting-up-the-Engine-development-environment#using-vscode-as-an-ide-for-the-android-embedding-java](../dev/Setting-up-the-Engine-development-environment.md) for tips on setting up Java code completion and syntax highlighting in Visual Studio when working on the engine and tests. @@ -230,7 +230,7 @@ into a single `.dylib`. Then it uses Xcode and the Xcode project at If you get an `AssertionError: libios_test_flutter.dylib doesn't exist` error, you may need to manually run the ninja command that is printed to the terminal. e.g. `ninja -C $FLUTTER_ENGINE/out/ios_debug_sim_unopt_arm64 ios_test_flutter` -See [[Setting-up-the-Engine-development-environment#editor-autocomplete-support]] +See [Setting-up-the-Engine-development-environment#editor-autocomplete-support](../dev/Setting-up-the-Engine-development-environment.md) for tips on setting up C/C++/Objective-C code completion and syntax highlighting when working on the engine and tests. @@ -329,7 +329,7 @@ Xcode and hit CMD+U. Dart unit tests are executed during pre-submit on our CI system when submitting PRs to the `flutter/engine` repository. -_See also: [[Flutter Test Fonts]]_ +_See also: [Flutter Test Fonts](https://github.com/flutter/flutter/wiki/Flutter-Test-Fonts)_ ### Framework tests diff --git a/docs/unsorted_wiki/Engine-repo.md b/docs/unsorted_wiki/Engine-repo.md deleted file mode 100644 index 62ea1ac809..0000000000 --- a/docs/unsorted_wiki/Engine-repo.md +++ /dev/null @@ -1,32 +0,0 @@ -This is an index of team-facing documentation for the [flutter/engine repository](https://github.com/flutter/engine/). - -- [[Accessibility on Windows]] -- [[Code signing metadata]] for engine binaries -- [[Compiling the engine]] -- [[Comparing AOT Snapshot Sizes]] -- [[Crashes]] -- [[Custom Flutter engine embedders]] -- [[Custom Flutter Engine Embedding in AOT Mode]] -- [[Debugging the engine]] -- [[Flutter engine operation in AOT Mode]] -- [[Flutter Test Fonts]] -- [[Flutter's modes]] -- [[Engine Clang Tidy Linter]] -- [[Engine disk footprint]] -- [[Engine-specific Service Protocol extensions]] -- [[Engine pre‐submits and post‐submits]] -- [[Image Codecs in the Flutter Engine]] -- [[Impeller]] documentation index -- [[Life of a Flutter Frame]] -- [[Reduce Flutter engine size with MLGO]] -- [[Resolving common build failures]] -- [[Setting up the Engine development environment]] -- [[Supporting legacy platforms]] -- [[Testing Android Changes in the Devicelab on an Emulator]] -- [[Testing the engine]] -- [[Testing presubmit Engine PRs with the Flutter framework]] -- [[The Engine architecture]] -- [[Upgrading Engine's Android API version]] -- [[Using the Dart Development Service (DDS) and Flutter DevTools with a custom Flutter Engine Embedding]] -- [[Using Sanitizers with the Flutter Engine]] -- [[Why we have a separate engine repo]] diff --git a/docs/unsorted_wiki/Impeller.md b/docs/unsorted_wiki/Impeller.md deleted file mode 100644 index f86d80abd1..0000000000 --- a/docs/unsorted_wiki/Impeller.md +++ /dev/null @@ -1,7 +0,0 @@ -_For user information about Flutter's new rendering backend, check out [Impeller preview](https://docs.flutter.dev/perf/impeller)._ - -Team-facing documentation specific to Impeller: - -- [[Setting up MoltenVK on macOS for Impeller]] -- [[Flutter GPU]] -- [[Instructions for playing with the Impeller Scene demo|Impeller Scene]]