Applied diff from flutter/engine#57264

engine/src/flutter/docs/contributing/Compiling-the-engine.md

@@ -16,6 +16,8 @@ Depending on the platform you are making changes for, you may be interested in a
 
 ## General Compilation Tips
 
+- Consider using the `et`, the engine tool, located at
+  https://github.com/flutter/flutter/blob/master/engine/src/flutter/tools/engine_tool.
 - For local development and testing, it's generally preferable to use `--unopt` builds.
   These builds will have additional logging and checks enabled, and generally use build
   and link flags that lead to faster compilation and better debugging symbols.
@@ -43,11 +45,11 @@ source files, pass the flag `--no-prebuilt-dart-sdk` to `//flutter/tools/gn`.
 
 These steps build the engine used by `flutter run` for Android devices.
 
-Run the following steps, from the `src` directory created in [Setting up the Engine development environment](Setting-up-the-Engine-development-environment.md):
+Run the following steps from the `engine/src` directory in your local checkout. See [Setting up the Engine development environment](Setting-up-the-Engine-development-environment.md).
 
-1. `git pull upstream main` in `src/flutter` to update the Flutter Engine repo.
+1. Make sure your branch is up to date. Run `git pull upstream master` if needed.
 
-2. `gclient sync` to update dependencies.
+2. `gclient sync -D` to update dependencies.
 
 3. Prepare your build files
     * `./flutter/tools/gn --android --unoptimized` for device-side executables.
@@ -92,15 +94,16 @@ host build available next to it: if you use `android_debug_unopt`, you should ha
 
 ### Compiling everything that matters on Linux
 
-The following script will update all the builds that matter if you're developing on Linux and testing on Android and created the `.gclient` file in `~/dev/engine`:
+The following script will update all the builds that matter if you're developing on Linux and testing on Android if your `.gclient` file is located at `~/dev/flutter/engine/.gclient`:
 
 ```bash
 set -ex
 
-cd ~/dev/engine/src/flutter
+cd ~/dev/flutter
 git fetch upstream
-git rebase upstream/main
-gclient sync
+git rebase upstream/master
+cd engine/src/flutter
+gclient sync -D
 cd ..
 
 flutter/tools/gn --unoptimized --runtime-mode=debug
@@ -117,11 +120,11 @@ For `--runtime-mode=profile` build, please also consider adding `--no-lto` optio
 
 These steps build the engine used by `flutter run` for iOS devices.
 
-Run the following steps, from the `src` directory created in the steps above:
+Run the following steps, from the `engine/src` directory:
 
-1. `git pull upstream main` in `src/flutter` to update the Flutter Engine repo.
+1. `git pull upstream master` to update the Flutter repo.
 
-2. `gclient sync` to update dependencies.
+2. `gclient sync -D` to update dependencies.
 
 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`
@@ -145,9 +148,9 @@ See also [instructions for debugging the engine in a Flutter app in Xcode](../De
 
 These steps build the desktop embedding, and the engine used by `flutter test` on a host workstation.
 
-1. `git pull upstream main` in `src/flutter` to update the Flutter Engine repo.
+1. `git pull upstream master` to update the Flutter repo.
 
-2. `gclient sync` to update your dependencies.
+2. `gclient sync -D` to update your dependencies.
 
 3. `./flutter/tools/gn --unoptimized` to prepare your build files.
    * `--unoptimized` disables C++ compiler optimizations. On macOS, binaries are emitted unstripped; on Linux, unstripped binaries are emitted to an `exe.unstripped` subdirectory of the build.
@@ -170,7 +173,7 @@ On Windows, ensure that the engine checkout is not deeply nested. This avoid the
 
 1. Make sure you have Visual Studio installed (non-Googlers only). [Debugging Tools for Windows 10](https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/debugger-download-tools#small-classic-windbg-preview-logo-debugging-tools-for-windows-10-windbg) must be installed.
 
-2. `git pull upstream main` in `src/flutter` to update the Flutter Engine repo.
+2. `git pull upstream master` to update the Flutter repo.
 
 3. Ensure long path support is enabled on your machine. Launch PowerShell as an administrator and run:
 ```
@@ -185,9 +188,9 @@ WINDOWSSDKDIR="C:\Program Files (x86)\Windows Kits\10" # (or your location for W
 ```
 Also, be sure that Python27 is before any other python in your Path.
 
-5. `gclient sync` to update your dependencies.
+5. `gclient sync -D` to update your dependencies.
 
-6. switch to `src/` directory.
+6. switch to `engine/src/` directory.
 
 7. `python .\flutter\tools\gn --unoptimized` to prepare your build files.
    * If you are only building `gen_snapshot`: `python .\flutter\tools\gn [--unoptimized] --runtime-mode=[debug|profile|release] [--android]`.
@@ -216,7 +219,7 @@ solutions = [
 
 > You may ignore `"run_fuchsia_emu": True` if you won't run tests locally.
 
-Run `gclient sync`.
+Run `gclient sync -D`.
 
 > [!WARNING]
 > When running tests locally, you will also need kvm enabled, or nested virtualization on the gcloud VMs. Fuchsia and the tests will all be executed on the qemu.
@@ -263,7 +266,7 @@ python3 flutter/tools/fuchsia/with_envs.py flutter/testing/fuchsia/run_tests.py
 
 ## Compiling for the Web
 
-For building the engine for the Web we use the [felt](https://github.com/flutter/engine/blob/main/lib/web_ui/README.md) tool.
+For building the engine for the Web we use the [felt](https://github.com/flutter/flutter/blob/master/engine/src/flutter/lib/web_ui/README.md) tool.
 
 To test Flutter with a local build of the Web engine, add `--local-web-sdk=wasm_release` to your `flutter` command, e.g.:
 
@@ -282,7 +285,7 @@ Compiling the web engine might take a few extra steps on Windows. Use cmd.exe an
 2. Make sure, depot_tools, ninja and python are installed and added to the path. Also set the following environment variable for depot tools:
    * `DEPOT_TOOLS_WIN_TOOLCHAIN = 0`
    * Tip: if you get a python error try to use Python 2 instead of 3
-3. `git pull upstream main` in `src/flutter` to update the Flutter Engine repo.
+3. `git pull upstream master` to update the Flutter repo.
 4. `gclient sync` to update your dependencies.
    * Tip: If you get a git authentication errors on this step try Git Bash instead
 5. `python .\flutter\tools\gn --unoptimized --full-dart-sdk` to prepare your build files.

engine/src/flutter/docs/contributing/Setting-up-the-Engine-development-environment.md

@@ -42,31 +42,23 @@ Run the following steps to set up your environment:
 >   * `GYP_MSVS_OVERRIDE_PATH=C:\Program Files\Microsoft Visual Studio\2022\Community`
 >     * Use the path of your installation.
 
-Create a new directory to hold the source code and move into it. Here, we are using the "engine" directory.
+Clone the Flutter source code. As of late 2024, the engine source is part of the main [flutter/flutter repo](https://github.com/flutter/flutter). The convention is to fork this repo and point `origin` to your fork and `upstream` to `[email protected]:flutter/flutter.git`.
 ```sh
-mkdir engine; cd engine;
+git clone [email protected]:<YOUR GITHUB USERNAME>/flutter.git
+cd flutter
+git remote add upstream [email protected]:flutter/flutter.git
 ```
 
 > [!IMPORTANT]
 > On Windows, the following must be run as an Administrator due to [a known issue](https://github.com/flutter/flutter/issues/94580).
 
 Fetch the Flutter engine sources. This may take a while on a slow connection. Do **not** interrupt this process. Otherwise, a partial checkout cannot be resumed and you'll have to delete all the files including the hidden files in the engine directory and start over.
 ```sh
+cd engine
 fetch flutter
 ```
-The [Flutter Engine](https://github.com/flutter/engine) repository resides at `src/flutter`. The convention is to refer to this repository as `upstream`.
 
-```sh
-git -C src/flutter remote rename origin upstream
-```
-
-Optionally, if you are working with a fork of the engine, add that as a Git remote.
-
-```sh
-git -C src/flutter remote add origin <your_git_fork_location>
-```
-
-The "Engine Tool" called `et` is useful when working with the engine. It is located in the `flutter/bin` directory in the engine source checkout. Add this to your `$PATH` in your `.rc`.
+The "Engine Tool" called `et` is useful when working with the engine. It is located in the [`engine/src/flutter/bin`](https://github.com/flutter/flutter/tree/0c3359df8c8342c8907316488b1404a216f215b6/engine/src/flutter/bin) directory. Add this to your `$PATH` in your `.rc` file.
 
 ### Additional Steps for Web Engine
 
@@ -171,7 +163,7 @@ To set up:
 ### Using Android Studio as an IDE for the Android Embedding [Java]
 
 Alternatively, Android Studio can be used as an IDE for the Android Embedding Java code. See docs
-at https://github.com/flutter/engine/blob/main/shell/platform/android/README.md#editing-java-code for
+at https://github.com/flutter/flutter/blob/master/engine/src/flutter/shell/platform/android/README.md#editing-java-code for
 instructions.
 
 ## VSCode Additional Useful Configuration