jezell · January 15, 2025 07:28
diff --git a/flutter engine build workflow b/flutter engine build workflow
 Below is an example GitHub Actions workflow that demonstrates **one possible approach** to building multiple variants (debug, profile, release) of the Flutter Engine on Linux, Windows, and macOS. 

 > **Important Caveats**  
 > 1. Building the Flutter Engine is fairly complex and typically uses [Chromium’s build tools](https://commondatastorage.googleapis.com/chrome-infra-docs/flat/developers_guide/index.html) (gclient, GN, ninja, etc.).  
 > 2. The official Flutter Engine uses [LUCI](https://chromium.googlesource.com/infra/luci/luci-py) for continuous integration, not GitHub Actions.  
 > 3. This example is **not** guaranteed to work out of the box for all scenarios, because setting up the full environment for iOS, Android, etc. often involves extra steps (e.g., Xcode installation for iOS, or the Android NDK for Android).  
 > 4. For a canonical reference on how to build the Flutter Engine locally, consult the [Flutter Engine’s CONTRIBUTING.md](https://github.com/flutter/engine/blob/main/CONTRIBUTING.md#compiling-the-engine).  

 With those disclaimers in mind, here’s a simplified GitHub workflow that shows how you might structure a matrix build for multiple platforms and build modes. Feel free to adapt it to your specific needs.

 ```yaml
 name: Build Flutter Engine

 on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

 jobs:
  # ---------------------------
  # 1) Build on Linux
  # ---------------------------
  build-linux:
    name: Build Flutter Engine (Linux)
    runs-on: ubuntu-latest
    strategy:
      matrix:
        build_mode: [debug, profile, release]
    steps:
      - name: Check out code
        uses: actions/checkout@v3

      - name: Install dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y curl python3 python3-pip python3-setuptools git clang cmake ninja-build pkg-config
          # Install depot_tools (which includes gclient, gn, ninja, etc.)
          git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git $HOME/depot_tools
          echo "::add-path::$HOME/depot_tools"

      - name: Sync dependencies (gclient sync)
        run: |
          # Typically you'd run something like:
          # gclient config --spec='solutions=[{
          #   "name": "src/flutter",
          #   "url": "https://github.com/flutter/engine.git",
          #   "deps_file": "DEPS",
          #   "managed": False,
          #   "custom_deps": {},
          #   "custom_vars": {}
          # }]'
          #
          # gclient sync --no-history
          #
          # This example assumes your repository is the engine repo
          # or already has the DEPS file. If not, adapt accordingly.
          echo "Running gclient sync..."
          gclient sync

      - name: Generate GN build files
        run: |
          # Example generating to out/linux_<mode>
          # Common GN flags you may need to tweak:
          #   --runtime-mode, --no-lto, --enable-fontconfig, etc.
          gn gen out/linux_${{ matrix.build_mode }} --args="is_debug=${{ matrix.build_mode == 'debug' }} is_profile=${{ matrix.build_mode == 'profile' }} target_os=\"linux\""

      - name: Build flutter engine
        run: |
          ninja -C out/linux_${{ matrix.build_mode }} flutter

  # ---------------------------
  # 2) Build on Windows
  # ---------------------------
  build-windows:
    name: Build Flutter Engine (Windows)
    runs-on: windows-latest
    strategy:
      matrix:
        build_mode: [debug, profile, release]
    steps:
      - name: Check out code
        uses: actions/checkout@v3

      - name: Install dependencies
        run: |
          # Windows-based commands:
          choco install python --version=3.9.0 -y
          choco install visualstudio2022buildtools -y
          choco install cmake ninja git -y
          # Set up depot_tools
          git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git C:\depot_tools
          echo "C:\\depot_tools" >> $env:GITHUB_PATH

      - name: Sync dependencies (gclient sync)
        run: |
          gclient sync

      - name: Generate GN build files
        run: |
          gn gen out\\windows_${{ matrix.build_mode }} --args="is_debug=${{ matrix.build_mode == 'debug' }} is_profile=${{ matrix.build_mode == 'profile' }} target_os=\"win\""

      - name: Build flutter engine
        run: |
          ninja -C out\\windows_${{ matrix.build_mode }} flutter

  # ---------------------------
  # 3) Build on macOS (including iOS, if desired)
  # ---------------------------
  build-macos:
    name: Build Flutter Engine (macOS)
    runs-on: macos-latest
    strategy:
      matrix:
        build_mode: [debug, profile, release]
    steps:
      - name: Check out code
        uses: actions/checkout@v3

      - name: Install dependencies
        run: |
          # macOS dependencies
          brew update
          brew install python git ninja cmake
          # depot_tools
          git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git $HOME/depot_tools
          echo "::add-path::$HOME/depot_tools"

      - name: Sync dependencies (gclient sync)
        run: |
          gclient sync

      - name: Generate GN build files
        run: |
          gn gen out/mac_${{ matrix.build_mode }} --args="is_debug=${{ matrix.build_mode == 'debug' }} is_profile=${{ matrix.build_mode == 'profile' }} target_os=\"mac\""

      - name: Build flutter engine
        run: |
          ninja -C out/mac_${{ matrix.build_mode }} flutter

  # ---------------------------
  # (Optional) Build iOS
  # ---------------------------
  build-ios:
    name: Build Flutter Engine (iOS)
    runs-on: macos-latest
    strategy:
      matrix:
        build_mode: [debug, profile, release]
    steps:
      - name: Check out code
        uses: actions/checkout@v3

      - name: Install dependencies
        run: |
          brew update
          brew install python git ninja cmake
          git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git $HOME/depot_tools
          echo "::add-path::$HOME/depot_tools"

      - name: Sync dependencies (gclient sync)
        run: |
          gclient sync

      - name: Generate GN build files
        run: |
          # For iOS, you might specify separate architecture builds (arm64, simulator, etc.)
          # This is a simple example for demonstration:
          gn gen out/ios_${{ matrix.build_mode }} --args="is_debug=${{ matrix.build_mode == 'debug' }} is_profile=${{ matrix.build_mode == 'profile' }} target_os=\"ios\""

      - name: Build flutter engine
        run: |
          ninja -C out/ios_${{ matrix.build_mode }} flutter

  # ---------------------------
  # (Optional) Build Android
  # ---------------------------
  build-android:
    name: Build Flutter Engine (Android)
    runs-on: ubuntu-latest
    strategy:
      matrix:
        build_mode: [debug, profile, release]
    steps:
      - name: Check out code
        uses: actions/checkout@v3

      - name: Install dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y curl python3 python3-pip python3-setuptools git clang cmake ninja-build pkg-config default-jdk
          # Install the Android SDK + NDK if needed:
          # (You would typically install the required NDK version, set environment variables, etc.)
          mkdir -p $HOME/depot_tools
          git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git $HOME/depot_tools
          echo "::add-path::$HOME/depot_tools"

      - name: Sync dependencies (gclient sync)
        run: |
          gclient sync

      - name: Generate GN build files
        run: |
          gn gen out/android_${{ matrix.build_mode }} --args="is_debug=${{ matrix.build_mode == 'debug' }} is_profile=${{ matrix.build_mode == 'profile' }} target_os=\"android\""

      - name: Build flutter engine
        run: |
          ninja -C out/android_${{ matrix.build_mode }} flutter

  # ---------------------------
  # (Optional) Build Web
  # ---------------------------
  build-web:
    name: Build Flutter Engine (Web)
    runs-on: ubuntu-latest
    strategy:
      matrix:
        build_mode: [debug, profile, release]
    steps:
      - name: Check out code
        uses: actions/checkout@v3

      - name: Install dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y curl python3 python3-pip python3-setuptools git clang cmake ninja-build pkg-config
          git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git $HOME/depot_tools
          echo "::add-path::$HOME/depot_tools"

      - name: Sync dependencies (gclient sync)
        run: |
          gclient sync

      - name: Generate GN build files
        run: |
          gn gen out/web_${{ matrix.build_mode }} --args="is_debug=${{ matrix.build_mode == 'debug' }} is_profile=${{ matrix.build_mode == 'profile' }} target_os=\"wasm\""

      - name: Build flutter engine
        run: |
          ninja -C out/web_${{ matrix.build_mode }} flutter
 ```

 ## How this workflow is structured

 1. **Matrix builds**:  
   Each job (Linux, Windows, macOS, iOS, Android, Web) uses a matrix of build modes (`debug`, `profile`, `release`). GitHub Actions will run a separate instance for each entry in the matrix.

 2. **Installing Dependencies**:  
   - We install [depot_tools](https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools.html) to get the `gclient`, `gn`, and `ninja` commands necessary to sync and build the Flutter Engine.  
   - We install OS-specific dependencies like compilers, build tools, etc.

 3. **Syncing & Generating**:  
   - We run `gclient sync` to pull down the dependencies specified in the Engine’s `DEPS` file.  
   - We run `gn gen out/...` to generate build configurations for each platform and build mode.  
   - We run `ninja` to actually compile the engine (`flutter` target, among others).

 4. **Optional Jobs**:  
   - The iOS, Android, and Web builds are shown as separate example jobs because they often require extra environment setup (like Xcode for iOS, the Android SDK/NDK for Android, etc.).  
   - If you don’t need these platforms, feel free to remove those jobs.  
   - If you need more complexity (like building for both `arm64` and `x86_64` for iOS simulators vs. real devices), you’ll need to further customize GN args or add more matrix entries.

 ## Next Steps

 - **Tweak GN args** based on [official docs](https://github.com/flutter/engine/blob/main/CONTRIBUTING.md#compiling-the-engine).  
 - **Set up caching** for dependencies if builds take too long ([actions/cache](https://github.com/actions/cache)).  
 - **Add artifact uploads** if you want to download the compiled engine artifacts ([actions/upload-artifact](https://github.com/actions/upload-artifact)).  
 - **Improve environment setup** for iOS (Xcode versions), Android (specific NDK versions), or other specialized needs.  

 This workflow is intended as a **starting point** or example. Building the Flutter Engine is non-trivial, and you may need to refine the steps or environment setup for your specific project. Good luck!
	Below is an example GitHub Actions workflow that demonstrates one possible approach to building multiple variants (debug, profile, release) of the Flutter Engine on Linux, Windows, and macOS.

	> Important Caveats
	> 1. Building the Flutter Engine is fairly complex and typically uses [Chromium’s build tools](https://commondatastorage.googleapis.com/chrome-infra-docs/flat/developers_guide/index.html) (gclient, GN, ninja, etc.).
	> 2. The official Flutter Engine uses [LUCI](https://chromium.googlesource.com/infra/luci/luci-py) for continuous integration, not GitHub Actions.
	> 3. This example is not guaranteed to work out of the box for all scenarios, because setting up the full environment for iOS, Android, etc. often involves extra steps (e.g., Xcode installation for iOS, or the Android NDK for Android).
	> 4. For a canonical reference on how to build the Flutter Engine locally, consult the [Flutter Engine’s CONTRIBUTING.md](https://github.com/flutter/engine/blob/main/CONTRIBUTING.md#compiling-the-engine).

	With those disclaimers in mind, here’s a simplified GitHub workflow that shows how you might structure a matrix build for multiple platforms and build modes. Feel free to adapt it to your specific needs.

	```yaml
	name: Build Flutter Engine

	on:
	push:
	branches: [ "main" ]
	pull_request:
	branches: [ "main" ]

	jobs:
	# ---------------------------
	# 1) Build on Linux
	# ---------------------------
	build-linux:
	name: Build Flutter Engine (Linux)
	runs-on: ubuntu-latest
	strategy:
	matrix:
	build_mode: [debug, profile, release]
	steps:
	- name: Check out code
	uses: actions/checkout@v3

	- name: Install dependencies
	run: \|
	sudo apt-get update
	sudo apt-get install -y curl python3 python3-pip python3-setuptools git clang cmake ninja-build pkg-config
	# Install depot_tools (which includes gclient, gn, ninja, etc.)
	git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git $HOME/depot_tools
	echo "::add-path::$HOME/depot_tools"

	- name: Sync dependencies (gclient sync)
	run: \|
	# Typically you'd run something like:
	# gclient config --spec='solutions=[{
	# "name": "src/flutter",
	# "url": "https://github.com/flutter/engine.git",
	# "deps_file": "DEPS",
	# "managed": False,
	# "custom_deps": {},
	# "custom_vars": {}
	# }]'
	#
	# gclient sync --no-history
	#
	# This example assumes your repository is the engine repo
	# or already has the DEPS file. If not, adapt accordingly.
	echo "Running gclient sync..."
	gclient sync

	- name: Generate GN build files
	run: \|
	# Example generating to out/linux_<mode>
	# Common GN flags you may need to tweak:
	# --runtime-mode, --no-lto, --enable-fontconfig, etc.
	gn gen out/linux_${{ matrix.build_mode }} --args="is_debug=${{ matrix.build_mode == 'debug' }} is_profile=${{ matrix.build_mode == 'profile' }} target_os=\"linux\""

	- name: Build flutter engine
	run: \|
	ninja -C out/linux_${{ matrix.build_mode }} flutter

	# ---------------------------
	# 2) Build on Windows
	# ---------------------------
	build-windows:
	name: Build Flutter Engine (Windows)
	runs-on: windows-latest
	strategy:
	matrix:
	build_mode: [debug, profile, release]
	steps:
	- name: Check out code
	uses: actions/checkout@v3

	- name: Install dependencies
	run: \|
	# Windows-based commands:
	choco install python --version=3.9.0 -y
	choco install visualstudio2022buildtools -y
	choco install cmake ninja git -y
	# Set up depot_tools
	git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git C:\depot_tools
	echo "C:\\depot_tools" >> $env:GITHUB_PATH

	- name: Sync dependencies (gclient sync)
	run: \|
	gclient sync

	- name: Generate GN build files
	run: \|
	gn gen out\\windows_${{ matrix.build_mode }} --args="is_debug=${{ matrix.build_mode == 'debug' }} is_profile=${{ matrix.build_mode == 'profile' }} target_os=\"win\""

	- name: Build flutter engine
	run: \|
	ninja -C out\\windows_${{ matrix.build_mode }} flutter

	# ---------------------------
	# 3) Build on macOS (including iOS, if desired)
	# ---------------------------
	build-macos:
	name: Build Flutter Engine (macOS)
	runs-on: macos-latest
	strategy:
	matrix:
	build_mode: [debug, profile, release]
	steps:
	- name: Check out code
	uses: actions/checkout@v3

	- name: Install dependencies
	run: \|
	# macOS dependencies
	brew update
	brew install python git ninja cmake
	# depot_tools
	git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git $HOME/depot_tools
	echo "::add-path::$HOME/depot_tools"

	- name: Sync dependencies (gclient sync)
	run: \|
	gclient sync

	- name: Generate GN build files
	run: \|
	gn gen out/mac_${{ matrix.build_mode }} --args="is_debug=${{ matrix.build_mode == 'debug' }} is_profile=${{ matrix.build_mode == 'profile' }} target_os=\"mac\""

	- name: Build flutter engine
	run: \|
	ninja -C out/mac_${{ matrix.build_mode }} flutter

	# ---------------------------
	# (Optional) Build iOS
	# ---------------------------
	build-ios:
	name: Build Flutter Engine (iOS)
	runs-on: macos-latest
	strategy:
	matrix:
	build_mode: [debug, profile, release]
	steps:
	- name: Check out code
	uses: actions/checkout@v3

	- name: Install dependencies
	run: \|
	brew update
	brew install python git ninja cmake
	git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git $HOME/depot_tools
	echo "::add-path::$HOME/depot_tools"

	- name: Sync dependencies (gclient sync)
	run: \|
	gclient sync

	- name: Generate GN build files
	run: \|
	# For iOS, you might specify separate architecture builds (arm64, simulator, etc.)
	# This is a simple example for demonstration:
	gn gen out/ios_${{ matrix.build_mode }} --args="is_debug=${{ matrix.build_mode == 'debug' }} is_profile=${{ matrix.build_mode == 'profile' }} target_os=\"ios\""

	- name: Build flutter engine
	run: \|
	ninja -C out/ios_${{ matrix.build_mode }} flutter

	# ---------------------------
	# (Optional) Build Android
	# ---------------------------
	build-android:
	name: Build Flutter Engine (Android)
	runs-on: ubuntu-latest
	strategy:
	matrix:
	build_mode: [debug, profile, release]
	steps:
	- name: Check out code
	uses: actions/checkout@v3

	- name: Install dependencies
	run: \|
	sudo apt-get update
	sudo apt-get install -y curl python3 python3-pip python3-setuptools git clang cmake ninja-build pkg-config default-jdk
	# Install the Android SDK + NDK if needed:
	# (You would typically install the required NDK version, set environment variables, etc.)
	mkdir -p $HOME/depot_tools
	git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git $HOME/depot_tools
	echo "::add-path::$HOME/depot_tools"

	- name: Sync dependencies (gclient sync)
	run: \|
	gclient sync

	- name: Generate GN build files
	run: \|
	gn gen out/android_${{ matrix.build_mode }} --args="is_debug=${{ matrix.build_mode == 'debug' }} is_profile=${{ matrix.build_mode == 'profile' }} target_os=\"android\""

	- name: Build flutter engine
	run: \|
	ninja -C out/android_${{ matrix.build_mode }} flutter

	# ---------------------------
	# (Optional) Build Web
	# ---------------------------
	build-web:
	name: Build Flutter Engine (Web)
	runs-on: ubuntu-latest
	strategy:
	matrix:
	build_mode: [debug, profile, release]
	steps:
	- name: Check out code
	uses: actions/checkout@v3

	- name: Install dependencies
	run: \|
	sudo apt-get update
	sudo apt-get install -y curl python3 python3-pip python3-setuptools git clang cmake ninja-build pkg-config
	git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git $HOME/depot_tools
	echo "::add-path::$HOME/depot_tools"

	- name: Sync dependencies (gclient sync)
	run: \|
	gclient sync

	- name: Generate GN build files
	run: \|
	gn gen out/web_${{ matrix.build_mode }} --args="is_debug=${{ matrix.build_mode == 'debug' }} is_profile=${{ matrix.build_mode == 'profile' }} target_os=\"wasm\""

	- name: Build flutter engine
	run: \|
	ninja -C out/web_${{ matrix.build_mode }} flutter
	```

	## How this workflow is structured

	1. Matrix builds:
	Each job (Linux, Windows, macOS, iOS, Android, Web) uses a matrix of build modes (`debug`, `profile`, `release`). GitHub Actions will run a separate instance for each entry in the matrix.

	2. Installing Dependencies:
	- We install [depot_tools](https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools.html) to get the `gclient`, `gn`, and `ninja` commands necessary to sync and build the Flutter Engine.
	- We install OS-specific dependencies like compilers, build tools, etc.

	3. Syncing & Generating:
	- We run `gclient sync` to pull down the dependencies specified in the Engine’s `DEPS` file.
	- We run `gn gen out/...` to generate build configurations for each platform and build mode.
	- We run `ninja` to actually compile the engine (`flutter` target, among others).

	4. Optional Jobs:
	- The iOS, Android, and Web builds are shown as separate example jobs because they often require extra environment setup (like Xcode for iOS, the Android SDK/NDK for Android, etc.).
	- If you don’t need these platforms, feel free to remove those jobs.
	- If you need more complexity (like building for both `arm64` and `x86_64` for iOS simulators vs. real devices), you’ll need to further customize GN args or add more matrix entries.

	## Next Steps

	- Tweak GN args based on [official docs](https://github.com/flutter/engine/blob/main/CONTRIBUTING.md#compiling-the-engine).
	- Set up caching for dependencies if builds take too long ([actions/cache](https://github.com/actions/cache)).
	- Add artifact uploads if you want to download the compiled engine artifacts ([actions/upload-artifact](https://github.com/actions/upload-artifact)).
	- Improve environment setup for iOS (Xcode versions), Android (specific NDK versions), or other specialized needs.

	This workflow is intended as a starting point or example. Building the Flutter Engine is non-trivial, and you may need to refine the steps or environment setup for your specific project. Good luck!