本記事は GENDA Advent Calendar 2025 シリーズ2 - Day 22 の記事です。
はじめに
普段は Android アプリ開発をメインに行っていますが、Flutter を使った開発にも携わる機会があります。
Android アプリ開発者からすると、Flutter が Android 上でどのように動作しているのか、とりわけ FlutterActivity や FlutterEngine が裏側でどのように構成されているのか、非常に気になるところです。
幸い、Flutter はオープンソースであり、ソースコードが GitHub 上で公開されています。
コードを読むだけでも何となく理解は進みますが、「実際にビルドして動かす」 ことで、より理解が捗ると思います。
そこで本記事では、Flutter エンジンをソースコードからビルドする方法をご紹介します。
単にビルドするだけでなく、エンジン側のコードに変更を加え、それをビルドして実際に動作させることをゴールとします。
検証環境
- macOS Sequoia 15.6.1, Apple M4 Pro
※ 本記事は macOS 環境での手順を解説しています。Windows や Linux 環境では手順が異なる場合があります。
Flutter エンジンのビルドにはディスク容量が大量に必要です（数十 GB 以上）。またビルドに時間がかかるため、余裕のあるタイミングで行うのがおすすめです。
Engine Tool について
Flutter エンジンのビルドには Engine Tool（etコマンド）というツールも存在します。
しかし、Engine Tool を使用した際にエラーが発生し、ビルドを進めることができなかったため、今回は使用を見送りました。
事前準備
depot_tools のインストール
Flutter エンジンのビルドには、Google の depot_tools が必要です。
depot_tools とは？
depot_tools は、Google が開発したソースコード管理・ビルド支援ツール群です。
Chromium プロジェクトの開発のために作られましたが、現在は Flutter エンジンを含む多くの Google 関連プロジェクトで使用されています。
clone して、depot_tools のパスを通します。（後述する gclient ninja コマンドを使用するため）
git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git
export PATH=your/path/to/depot_tools:"$PATH"
ビルド手順
Flutter のソースコードの取得
Flutter エンジンのソースコードを取得します。
以前は Flutter エンジン用のリポジトリ（flutter/engine）がありましたが、現在は Flutter 本体のリポジトリ（flutter/flutter）に統合されています。
git clone git@github.com:flutter/flutter.git
今回は執筆時点での安定版リリース 3.38.5 で検証します。
git checkout 3.38.5
.gclient ファイルをコピーして作成します。
このファイルには、依存関係のあるリポジトリ情報が記載されています。
cp engine/scripts/standard.gclient .gclient
次に、ソースコードを同期します。
※ この処理にはかなり時間がかかります。
gclient sync
ビルド設定の生成
ソースコードの取得が完了したら、ビルド設定を生成します。
Android 向けのビルド設定を生成するには、flutter/tools にある gn コマンドを使用します。
gn とは？
gn（Generate Ninja）は、Google が開発したメタビルドシステムです。
ビルド設定ファイル（.gn ファイル）を読み込み、ninja 用のビルドファイルを生成します。
cd engine/src
./flutter/tools/gn --android --android-cpu=arm64 --unoptimized
-
--android-cpu: ターゲットアーキテクチャを指定します。実機で検証する場合はarm64を指定します。 -
--unoptimized: デバッグしやすいビルド設定（最適化なし）を生成します。
このコマンド自体はすぐに完了し、out/android_debug_unopt_arm64/ ディレクトリが生成されます。
ビルドの実行
ビルド設定が生成されたら、ninja を使ってビルドを実行します。
ninja とは？
ninja は、Google が開発した高速なビルドシステムです。
make の代替として設計されており、大規模プロジェクトのビルドを高速に実行できます。
ninja -C out/android_debug_unopt_arm64
初回ビルドは時間がかかります。
ビルドが完了すると、out/android_debug_unopt_arm64 ディレクトリにビルド成果物が生成されます。
ホスト用エンジンのビルド
Flutter アプリを実行する際には、Android 用だけでなく、ホスト（開発マシン）用のエンジンも必要です。
手順は Android 向けと同様です。
cd engine/src
./flutter/tools/gn --unoptimized
ninja -C out/host_debug_unopt/
Flutter アプリでカスタムエンジンを使用する
ビルドしたカスタムエンジンを Flutter アプリで使用してみます。
Flutter リポジトリにはサンプルアプリが含まれているため、これを使用してみます。
cd examples/hello_world
../../bin/flutter run --local-engine=android_debug_unopt_arm64 --local-engine-host=host_debug_unopt
問題が起きなければ、ビルドしたエンジンでアプリが起動します。
エンジンコードに変更を加えてみる
ビルド環境が整ったので、実際にエンジン側のコードに変更を加えてみます。
ケース 1: FlutterActivity に Toast を追加してみる
エンジン側への変更が視覚的に確認できるように、FlutterActivity に Toast を追加してみます。
- 対象ファイル: FlutterActivity.java
FlutterActivity の onCreate メソッドに以下の Toast を追加します。
@Override
protected void onCreate(@Nullable Bundle savedInstanceState) {
// ここに追加
Toast.makeText(this, "Hello from FlutterActivity", Toast.LENGTH_LONG).show();
// ... 以下略
}
変更を加えたら ninja を使ってビルドする必要があります。
ninja -C out/android_debug_unopt_arm64
2 回目以降は差分ビルドになるため、初回よりも短時間で完了します。
ビルド完了後、アプリを実行します。
../../bin/flutter run --local-engine=android_debug_unopt_arm64 --local-engine-host=host_debug_unopt
| Toast が表示される様子 |
|---|
 |
これで、自分で修正した Flutter エンジンが動作していることを確認できました！
ケース 2: リリースビルドでログを出力してみる
通常、Flutter の Android エンジンはデバッグビルド時のみログ出力を行いますが、トラブルシューティングのために「リリースビルドでもログが見たい」というケースがあるかもしれません。 そこで、リリースビルドでもログを出力するようにエンジンコードを変更してみます。
まず、デバッグビルドのみでログ出力を行っている制御（BuildConfig.DEBUG 等）をコメントアウトします。
- 対象ファイル: Log.java
public static void println(@NonNull int level, @NonNull String tag, @NonNull String message) {
// if (BuildConfig.DEBUG && logLevel <= level) {
android.util.Log.println(level, tag, message);
// }
}
// ... 他のログ出力メソッドも同様に調整
変更後、リリースビルド用の設定を生成してビルドします。（時間がかかります。）
手順はデバッグビルドと同様ですが、オプションに --runtime-mode=release を追加します。
cd engine/src
# Android用リリースビルド
./flutter/tools/gn --android --android-cpu=arm64 --runtime-mode=release
ninja -C out/android_release_arm64
# ホスト用リリースビルド
./flutter/tools/gn --runtime-mode=release
ninja -C out/host_release/
その後、Flutter アプリをリリースビルドで実行します。
--release オプションを追加する点に注意してください。
cd examples/hello_world
../../bin/flutter run --release --local-engine=android_release_arm64 --local-engine-host=host_release
アプリを起動すると、リリースビルドでもログが出力されていることを確認できました！
| 通常のリリースビルド | ログ出力版のリリースビルド |
|---|---|
 |
 |
まとめ
本記事では、Flutter エンジンをソースコードからビルドし、カスタマイズしたエンジンを Flutter アプリで動作させる方法を解説しました。
Flutter の内部実装を理解する上で、実際にビルドして動作を確認することは理解を深めるのに効果的です。いざという時に備えて、やり方を知っておくと安心ではないでしょうか。
この記事の内容が、どこかの誰かの役に立てば幸いです。