release: Flutter 3.41.5 for Termux ARM64

- Upgrade Flutter 3.35.0 → 3.41.5 (Dart 3.11.3)
- Add Linux release/profile engine builds (build_all now builds all 3 modes)
- Fix utils.py __MODE__ ordering bug (debug must be first)
- Full build matrix verified: 6/6 (Linux debug/release/profile + APK debug/release/profile)
- Update all documentation, README, CHANGELOG, workflow
- Add version-specific patches for 3.41.5

Author: ImL1s

.agent/workflows/build-termux-flutter.md

@@ -13,8 +13,8 @@ description: 為 Termux 交叉編譯 Flutter Engine 並打包成 .deb 安裝包
 ## 快速構建 (一鍵)
 // turbo-all
 ```bash
-cd /mnt/d/OtherProject/mine/flutter_termux/termux-flutter
-./build_termux_flutter.sh
+cd /home/iml1s/projects/termux-flutter
+python3 build.py build_all --arch=arm64
 ```
 
 ## 分步驟構建
@@ -24,41 +24,79 @@ cd /mnt/d/OtherProject/mine/flutter_termux/termux-flutter
 python3 build.py sysroot --arch=arm64
 ```
 
-### 2. 配置 GN
+### 2. Linux Debug Engine (主要)
 ```bash
-python3 build.py configure arch=arm64 mode=debug
+python3 build.py configure --arch=arm64 --mode=debug
+python3 build.py build --arch=arm64 --mode=debug
+python3 build.py build_dart --arch=arm64 --mode=debug
+python3 build.py build_impellerc --arch=arm64 --mode=debug
+python3 build.py build_const_finder --arch=arm64 --mode=debug
 ```
 
-### 3. 編譯
+### 3. Linux Release Engine
 ```bash
-python3 build.py build arch=arm64 mode=debug
+python3 build.py configure --arch=arm64 --mode=release
+python3 build.py build --arch=arm64 --mode=release
 ```
 
-### 4. 打包
+### 4. Linux Profile Engine
 ```bash
-python3 build.py debuild --arch=arm64
+python3 build.py configure --arch=arm64 --mode=profile
+python3 build.py build --arch=arm64 --mode=profile
 ```
 
-## 升級到新版本
+### 5. Android gen_snapshot
+```bash
+python3 build.py configure_android --arch=arm64 --mode=release
+python3 build.py build_android_gen_snapshot --arch=arm64 --mode=release
+```
 
-1. 修改 `build.toml` 中的 `tag = '新版本號'`
-2. 執行 `python3 build.py clone`
-3. 執行 `python3 build.py sync`
-4. 如果補丁失敗，需手動更新 `patches/*.patch`
-5. 執行完整構建流程
+### 6. 打包 .deb
+```bash
+python3 build.py debuild --arch=arm64
+```
 
-## 在 Termux 上安裝
+## 在 Termux 上安裝與驗證
 
-```bash
-# 推送到手機
-adb push flutter_*.deb /sdcard/Download/
+```powershell
+# 推送到手機 (PowerShell, 不要用 Git Bash)
+adb push flutter_3.41.5_aarch64.deb /data/local/tmp/
+```
 
+```bash
 # 在 Termux 中執行
-pkg update && pkg install x11-repo
-cp /sdcard/Download/flutter_*.deb ~/
-dpkg -i ~/flutter_*.deb
+dpkg -i /data/local/tmp/flutter_3.41.5_aarch64.deb
+apt-get install -f
+bash $PREFIX/share/flutter/post_install.sh
+source $PREFIX/etc/profile.d/flutter.sh
+
+# 驗證
 flutter --version
+flutter create test_app && cd test_app
+
+# Build Matrix 驗證 (6/6)
+flutter build linux --debug
+flutter build linux --release
+flutter build linux --profile
+flutter build apk --debug --target-platform android-arm64
+flutter build apk --release --target-platform android-arm64
+flutter build apk --profile --target-platform android-arm64
 ```
 
-## 關鍵補丁說明
-我們在 `build/config/termux/BUILD.gn` 中加入了 `-llog`, `-lm` 以解決 Android 日誌符號缺失問題。
+## ⚠️ 關鍵注意事項
+
+1. `utils.py __MODE__` 必須是 `('debug', 'release', 'profile')` — debug 在前！
+   - `Output.any` 取第一個存在的目錄
+   - 如果 release 在前，dart-sdk snapshots 會用 product mode → 整個 flutter CLI 壞掉
+
+2. `ninja flutter` **不會** build dart binary — 必須另外跑 `build_dart()`
+
+3. 只支援 ARM64 APK — android-arm/android-x64 gen_snapshot 無法交叉編譯
+
+## 升級到新版本
+
+1. 修改 `build.toml` 中的 `tag = '新版本號'`
+2. 執行 `python3 build.py clone`
+3. 執行 `python3 build.py sync`
+4. 如果補丁失敗，需手動更新 `patches/*.patch`
+5. 執行完整構建流程

AGENTS.md

@@ -13,7 +13,7 @@ Cross-compile Flutter SDK for Termux (Android/Bionic ARM64). Produces a `.deb` p
 python3 build.py build_all --arch=arm64
 
 # Individual steps
-python3 build.py clone                                    # Clone Flutter 3.35.0
+python3 build.py clone                                    # Clone Flutter 3.41.5
 python3 build.py sync                                     # gclient sync (~30GB)
 python3 build.py patch_engine && python3 build.py patch_dart && python3 build.py patch_skia
 python3 build.py sysroot --arch=arm64                     # Assemble Termux sysroot from apt
@@ -22,6 +22,10 @@ python3 build.py build --arch=arm64 --mode=debug          # ninja build
 python3 build.py build_dart --arch=arm64 --mode=debug     # dart binary (separate!)
 python3 build.py build_impellerc --arch=arm64 --mode=debug
 python3 build.py build_const_finder --arch=arm64 --mode=debug
+python3 build.py configure --arch=arm64 --mode=release    # Linux release engine
+python3 build.py build --arch=arm64 --mode=release
+python3 build.py configure --arch=arm64 --mode=profile    # Linux profile engine
+python3 build.py build --arch=arm64 --mode=profile
 python3 build.py configure_android --arch=arm64 --mode=release
 python3 build.py build_android_gen_snapshot --arch=arm64 --mode=release
 python3 build.py debuild --arch=arm64                     # Package .deb
@@ -47,6 +51,7 @@ python3 build.py debuild --arch=arm64                     # Package .deb
 4. **`package.yaml` uses `eval()`** for variable resolution — be careful with template strings.
 5. **`debuild()` auto-syncs** from Windows to WSL via `[sync]` config before packaging.
 6. **GN flag `is_termux=true`** activates custom BUILD.gn rules that add `-llog -lm` for Android logging symbols.
+7. **`utils.py __MODE__` must be `('debug', 'release', 'profile')`** — debug first! `Output.any` picks the first existing directory. If release comes first, `output.any` points to release (product mode) dart-sdk snapshots, breaking the entire Flutter CLI.
 
 ## Termux Runtime: post_install.sh Auto-Fixes
 
@@ -79,6 +84,8 @@ android {
 ```
 flutter/engine/src/out/
 ├── linux_debug_arm64/          # Main: dart-sdk, gen_snapshot, libflutter_linux_gtk.so
+├── linux_release_arm64/        # Release: gen_snapshot, libflutter_linux_gtk.so
+├── linux_profile_arm64/        # Profile: gen_snapshot, libflutter_linux_gtk.so
 ├── android_release_arm64/      # Android gen_snapshot (release APK)
 └── android_profile_arm64/      # Android gen_snapshot (profile APK)
 ```
@@ -87,6 +94,6 @@ flutter/engine/src/out/
 
 - Build: WSL2 Ubuntu on Windows, NDK r27d at `/opt/android-ndk-r27d`
 - WSL path: `/home/iml1s/projects/termux-flutter/`
-- Target: aarch64, Flutter 3.35.0
+- Target: aarch64, Flutter 3.41.5
 - Test device: `RFCNC0WNT9H`
 - Use PowerShell (not Git Bash) for `adb push` to avoid path mangling

CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.41.5-termux] - 2026-03-25
+
+### Added
+- Flutter version upgrade: 3.35.0 → 3.41.5 (Dart 3.11.3)
+- **Linux release/profile engine builds**: `build_all()` now compiles all three Linux modes (debug, release, profile)
+- Full build matrix verified on device (6/6): Linux debug/release/profile + APK debug/release/profile
+
+### Fixed
+- **`flutter build linux` (release/profile) failure**: `build_all()` was only building debug mode engine for Linux, leaving `linux_release_arm64/` and `linux_profile_arm64/` empty in the deb package
+- **`utils.py __MODE__` ordering bug**: Original order `('release', 'debug', 'profile')` caused `Output.any` to select release (product mode) dart-sdk snapshots when release directory exists, breaking the entire Flutter CLI. Fixed to `('debug', 'release', 'profile')`
+
+### Technical Details
+- Build output now includes 5 directories: `linux_debug_arm64/`, `linux_release_arm64/`, `linux_profile_arm64/`, `android_release_arm64/`, `android_profile_arm64/`
+- `build_all()` expanded from 8 to 12 steps to include Linux release/profile configure+build
+- Deb package size increased from ~541MB to ~662MB due to additional engine artifacts
+
+---
+
 ## [3.35.0-termux] - 2026-01-07
 
 ### Added

CLAUDE.md

@@ -23,6 +23,12 @@ python3 build.py sysroot --arch=arm64            # Build sysroot
 python3 build.py configure --arch=arm64 --mode=debug
 python3 build.py build --arch=arm64 --mode=debug
 python3 build.py build_dart --arch=arm64 --mode=debug
+python3 build.py build_impellerc --arch=arm64 --mode=debug
+python3 build.py build_const_finder --arch=arm64 --mode=debug
+python3 build.py configure --arch=arm64 --mode=release    # Linux release engine
+python3 build.py build --arch=arm64 --mode=release
+python3 build.py configure --arch=arm64 --mode=profile    # Linux profile engine
+python3 build.py build --arch=arm64 --mode=profile
 
 # Android gen_snapshot (for flutter build apk)
 python3 build.py configure_android --arch=arm64 --mode=release
@@ -44,6 +50,9 @@ python3 build.py debuild --arch=arm64
 | `utils.py` | Build utilities and path helpers |
 | `patches/{version}/*.patch` | Version-specific Engine/Dart/Skia patches |
 | `scripts/install/post_install.sh` | Post-installation setup for APK builds |
+| `scripts/build/` | Build helper scripts (profile, gen_snapshot, etc.) |
+| `scripts/setup/` | WSL/NDK/Gradle environment setup scripts |
+| `scripts/fix/` | Workaround scripts (aapt2, gradle, SSH) |
 | `install_flutter_complete.sh` | One-command Termux installation script |
 | `CHANGELOG.md` | Version history and release notes |
 | `BUILD_GUIDE.md` | Detailed build guide and troubleshooting |
@@ -56,7 +65,7 @@ flutter_termux/
 ├── build.toml                  # Build configuration
 ├── install_flutter_complete.sh # Termux installation script
 ├── patches/
-│   └── 3.35.0/                 # Version-specific patches
+│   └── 3.41.5/                 # Version-specific patches
 │       ├── engine.patch
 │       ├── dart.patch
 │       └── skia.patch
@@ -103,8 +112,14 @@ flutter_termux/
 flutter/engine/src/out/
 ├── linux_debug_arm64/
 │   ├── dart-sdk/bin/dart          # Dart binary
-│   ├── gen_snapshot               # Linux gen_snapshot
+│   ├── gen_snapshot               # Linux gen_snapshot (release mode VM)
 │   └── libflutter_linux_gtk.so    # Linux GTK library (~106MB)
+├── linux_release_arm64/
+│   ├── gen_snapshot               # Release gen_snapshot
+│   └── libflutter_linux_gtk.so    # Release GTK library
+├── linux_profile_arm64/
+│   ├── gen_snapshot               # Profile gen_snapshot
+│   └── libflutter_linux_gtk.so    # Profile GTK library
 ├── android_release_arm64/
 │   └── clang_arm64/gen_snapshot   # Android release gen_snapshot
 └── android_profile_arm64/
@@ -119,10 +134,17 @@ In `build.py` `build()` method:
 
 **Important**: `flutter_gtk` target must be enabled, otherwise `flutter build linux` fails.
 
+## Internal Patterns
+
+- **`@utils.record` / `@utils.recordm`**: Decorators that auto-log all method calls with args. Set `NO_RECORD=1` to disable.
+- **`Build.sync()`**: Detects Windows vs WSL via `platform.system()`. On Windows, wraps `cp` in `wsl -e bash -c`; on WSL, runs directly.
+- **`Package.__format__()`**: Uses `string.Template.safe_substitute()` for `$variable` expansion in `package.yaml`.
+- **`package.yaml` `define` blocks**: Use `eval()` with globals (`root`, `arch`, `output`, `version`) — never put untrusted strings here.
+
 ## Known Limitations
 
 1. **APK only supports ARM64**: android-arm and android-x64 gen_snapshot cannot be cross-compiled (BoringSSL 32-bit issues, sysroot incompatibility)
-2. Uses debug mode binaries due to sysroot conflicts (glibc vs bionic headers)
+2. **`utils.py __MODE__` must be `('debug', 'release', 'profile')`**: debug first! `Output.any` picks the first existing directory. If release comes first, product mode dart-sdk snapshots break the entire Flutter CLI.
 3. See `BUILD_GUIDE.md` for detailed troubleshooting
 
 ## Common Issues
@@ -181,11 +203,11 @@ chmod +x depot_tools/vpython3
 
 ```powershell
 # Transfer deb to device
-powershell -Command "adb push 'flutter_3.35.0_aarch64.deb' '/data/local/tmp/'"
+powershell -Command "adb push 'flutter_3.41.5_aarch64.deb' '/data/local/tmp/'"
 
 # Install in Termux
 pkg install x11-repo
-dpkg -i /data/local/tmp/flutter_3.35.0_aarch64.deb
+dpkg -i /data/local/tmp/flutter_3.41.5_aarch64.deb
 apt-get install -f
 bash $PREFIX/share/flutter/post_install.sh  # Required for APK builds!
 
@@ -202,16 +224,19 @@ flutter doctor -v
 
 ## Version Info
 
-- Flutter: 3.35.0
+- Flutter: 3.41.5
+- Dart SDK: 3.11.3
 - Target: aarch64 (ARM64)
 
-## Verified Feature Status (2026-01-07)
+## Verified Feature Status (2026-03-25)
 
 | Feature | Status | Requirements |
 |---------|--------|--------------|
 | `flutter doctor` | ✅ | deb install only |
 | `flutter create` | ✅ | deb install only |
-| `flutter build linux` | ✅ | gtk3, x11-repo |
+| `flutter build linux --debug` | ✅ | gtk3, x11-repo |
+| `flutter build linux --release` | ✅ | gtk3, x11-repo |
+| `flutter build linux --profile` | ✅ | gtk3, x11-repo |
 | `flutter build apk --debug` | ✅ | post_install.sh + project config |
 | `flutter build apk --profile` | ✅ | post_install.sh + project config |
 | `flutter build apk --release` | ✅ | post_install.sh + project config |

GEMINI.md

@@ -44,7 +44,7 @@ Windows (edit files)
     ├── package.py          ← Reads package.yaml, builds data.tar.xz + control.tar.xz → .deb
     ├── package.yaml        ← Declarative: maps build artifacts → deb install paths
     ├── utils.py            ← Arch mapping, output paths, Termux detection
-    └── patches/3.35.0/     ← Engine/Dart/Skia patches (version-specific)
+    └── patches/3.41.5/     ← Engine/Dart/Skia patches (version-specific)
     │
     ▼ (sync to WSL via [sync] config in build.toml)
 WSL Ubuntu (build)
@@ -53,8 +53,10 @@ WSL Ubuntu (build)
     │   └── engine/src/     ← Engine source (gclient managed)
     │       └── out/
     │           ├── linux_debug_arm64/     ← Main output (dart, gen_snapshot, libflutter_linux_gtk.so)
-    │           ├── android_release_arm64/ ← Android gen_snapshot (release)
-    │           └── android_profile_arm64/ ← Android gen_snapshot (profile)
+            ├── linux_release_arm64/   ← Release engine (gen_snapshot, libflutter_linux_gtk.so)
+            ├── linux_profile_arm64/   ← Profile engine (gen_snapshot, libflutter_linux_gtk.so)
+            ├── android_release_arm64/ ← Android gen_snapshot (release)
+            └── android_profile_arm64/ ← Android gen_snapshot (profile)
     │
     ▼ (adb push .deb → dpkg -i on device)
 Termux (runtime)
@@ -75,6 +77,8 @@ Termux (runtime)
 
 6. **Windows↔WSL sync**: `build.toml [sync]` section defines paths to copy from Windows mount to WSL native fs before `debuild`, preventing stale-file issues.
 
+7. **`utils.py __MODE__` must be `('debug', 'release', 'profile')`**: `Output.any` picks the first existing build directory. If `release` is first and `linux_release_arm64/` exists, `output.any` selects it — its `product` mode dart-sdk snapshots will break the entire Flutter CLI. Debug must always be first.
+
 ## Termux Runtime: post_install.sh Auto-Fixes
 
 `post_install.sh` automatically handles these ARM64 compatibility issues:
@@ -115,18 +119,18 @@ android {
 - Host: Windows + WSL2 Ubuntu, Ryzen 9950X3D (24 threads allocated)
 - NDK: r27d at `/opt/android-ndk-r27d`
 - WSL build dir: `/home/iml1s/projects/termux-flutter/`
-- Flutter: 3.35.0
+- Flutter: 3.41.5
 - Target: aarch64 (ARM64)
 - Test device: `RFCNC0WNT9H`
 
 ## Deployment
 
 ```powershell
 # From Windows (use PowerShell, NOT Git Bash — path mangling)
-adb push flutter_3.35.0_aarch64.deb /data/local/tmp/
+adb push flutter_3.41.5_aarch64.deb /data/local/tmp/
 
 # In Termux
-dpkg -i /data/local/tmp/flutter_3.35.0_aarch64.deb
+dpkg -i /data/local/tmp/flutter_3.41.5_aarch64.deb
 apt-get install -f
 bash $PREFIX/share/flutter/post_install.sh  # Required for APK builds
 source $PREFIX/etc/profile.d/flutter.sh