Gradleマルチプロジェクトの基本設定とIDE連携をわかりやすく解説

Gradleマルチプロジェクトとは？基本構造と設定ファイルの役割

Gradleのマルチプロジェクトビルドとは、1つのルートプロジェクトと1つ以上のサブプロジェクトで構成されるビルド方式です。モジュール化によってコードの再利用性を高め、ビルドの並列実行や依存関係の明確化を実現できます。

マルチプロジェクトの基本構造

マルチプロジェクトは、ルートディレクトリ直下にサブプロジェクトのフォルダを配置するのが基本的な構成です。例えば、アプリ本体、共通コアロジック、ユーティリティという3つのモジュールに分割する場合、次のようなディレクトリ構造になります。

• ルートプロジェクト：全体を束ねる最上位のプロジェクト
• サブプロジェクト：app、core、utilなどの単位で分割されたモジュール
• 各プロジェクトのbuild.gradle.kts：それぞれのビルド設定を記述

この構造によって、変更の影響範囲をモジュール単位に限定しやすくなります。（出典：Gradle「Multi-Project Builds」）

設定ファイルの役割

マルチプロジェクトで中心となる設定ファイルはsettings.gradle（またはsettings.gradle.kts）です。このファイルでルートプロジェクト名とサブプロジェクトを宣言します。各サブプロジェクト固有のビルド設定は、それぞれのbuild.gradle.ktsに記述します。

• settings.gradle.kts：プロジェクト構成の宣言（rootProject.name、include）
• build.gradle.kts：プラグイン適用、依存関係、タスク設定
• gradle/libs.versions.toml：依存バージョンの一元管理（任意）

サブプロジェクトを追加するにはsettingsファイルにinclude("app", "core")のように明示的に宣言する必要があります。

サブプロジェクトの宣言と注意点

サブプロジェクトはinclude()で明示的に宣言しない限り認識されません。ディレクトリにフォルダがあるだけで自動的にサブプロジェクトとして扱われることはないため、追加時はsettingsファイルの更新が必須です。

また、Gradle 9.0以降では、includeしたサブプロジェクトのディレクトリが存在しない場合や読み取り専用の場合、ビルドが失敗するようになりました。宣言と実体の整合性を保つことが重要です。

要点：マルチプロジェクトはルート＋サブプロジェクトで構成し、settings.gradle.ktsのinclude()で明示的に宣言する。ディレクトリの存在も必須。

Gradleのマルチプロジェクト構成を設定する方法（settings.gradleの書き方）

マルチプロジェクトを設定するには、settings.gradle.ktsにルートプロジェクト名とサブプロジェクトを宣言します。ここでの記述がプロジェクト全体の構成を決定し、IDEでの表示名にも影響します。

基本的なsettings.gradle.ktsの書き方

最もシンプルな設定は、ルートプロジェクト名とサブプロジェクトを列挙する形です。

1. ルートディレクトリにsettings.gradle.ktsを作成する
2. rootProject.name = "my-project"でルート名を設定する
3. include("app", "core", "util")でサブプロジェクトを宣言する
4. 各サブプロジェクトのディレクトリにbuild.gradle.ktsを配置する

rootProject.nameはIDEのプロジェクト表示名に強く影響するため、プロジェクトの正式名称を設定してください。

プロジェクトパスとディレクトリの対応

include()の引数はプロジェクトパスを表し、コロン（:）を区切り文字として使用します。例えばinclude("services:api")と宣言すると、デフォルトで./services/apiディレクトリに対応します。

ただし、深い階層をそのままincludeすると、中間に「services」や「services:api」のような想定外の仮想プロジェクトが生成される場合があります。これを避けるには、projectDirを明示的に指定します。

この表のように、シンプルな構成ではinclude()のみ、複雑なディレクトリ構成ではprojectDirの指定が有効です。（出典：Gradle「Multi-Project Builds」）

クロスプロジェクト依存の設定

サブプロジェクト間で依存関係を設定するには、各サブプロジェクトのbuild.gradle.ktsでimplementation(project(":core"))のように宣言します。これにより、appプロジェクトをビルドすると、依存先のcoreプロジェクトも自動的にビルドされます。

サブプロジェクト間の依存関係を適切に設定することで、ビルド順序もGradleが自動解決します。循環依存が発生しないよう、依存の方向には注意が必要です。なお、このproject()の引数に指定するプロジェクト名がsettings.gradle.ktsで宣言した名前と異なると解決できないため、整合性を保つことが重要です。

要点：settings.gradle.ktsでinclude()を使ってサブプロジェクトを宣言し、プロジェクト間の依存はproject()表記で設定する。

GradleとIDEを連携する際の注意点（IntelliJ IDEA・Eclipse・VS Code）

GradleプロジェクトをIDEで扱う際は、Gradle設定を「単一の信頼できる情報源」として扱うことが基本です。IDEはGradleの設定ファイルを読み込んでプロジェクトを構成します。

IntelliJ IDEAでの連携

IntelliJ IDEAはGradleをネイティブ統合しており、追加プラグインなしでプロジェクトをインポートできます。Gradleツールウィンドウから同期、タスク実行、Composite Buildの設定が可能です。

• Gradleプロジェクトを開くと自動で同期される
• ビルドスクリプトの外部変更を検出して自動リロード可能
• 「Sync Gradle Project」で手動同期もできる

重要な注意点として、IDEAのプロジェクト構成ダイアログで依存関係を手動追加しても、次回の再インポート時に削除されます。依存関係は必ずGradle側のbuild.gradle.ktsに記述してください。（出典：JetBrains「Gradle Projects」）

Eclipseでの連携（Buildship）

EclipseではBuildshipプラグインを使用してGradleプロジェクトをインポートします。Buildshipは主要なEclipseディストリビューションにデフォルトで含まれています。

1. 「File → Import → Gradle → Existing Gradle Projects」を選択
2. ルートプロジェクトのディレクトリを指定
3. プレビューで構成を確認して「Finish」

ビルド設定を変更した後は、プロジェクトノードから「Gradle → Refresh Gradle Project」を実行して同期します。Buildship 2.0以降ではComposite Buildのインポートもサポートされていますが、included builds内のタスク実行はサポートされていない制限があります。（出典：Eclipse Buildship「Overview」）

VS Codeでの連携とIDE共通の注意点

VS CodeではGradle拡張機能を通じてプロジェクトを扱いますが、公式に詳細なマルチプロジェクト設定手順は確認できませんでした。利用する場合は拡張機能のドキュメントを確認してください。

IDE共通の注意点として、Gradle Wrapperがリポジトリルートにのみある場合、IDEで個別プロジェクトをインポートするとwrapperを見つけられず、独自のGradleバージョンを生成することがあります。その場合はGradleインストールを手動で設定する必要があります。

要点：IDEではGradle設定が正であり、依存関係は必ずGradle側で記述する。wrapperの配置場所にも注意。

Gradleのインストール場所や環境変数（GRADLE_HOME・GRADLE_USER_HOME）を整理

Gradleの環境変数は、インストール場所を示すGRADLE_HOMEと、ユーザー固有の設定やキャッシュを管理するGRADLE_USER_HOMEの2つが重要です。これらを正しく理解することで、環境構築のトラブルを防げます。

GRADLE_HOMEとは

GRADLE_HOMEは、Gradle本体がインストールされているディレクトリを指す環境変数です。手動でGradleをインストールした場合に設定されることがあります。

• Gradleの実行ファイル（bin/gradle）が含まれるディレクトリ
• システム全体でGradleの場所を明示するために使用
• Gradle Wrapperを使用する場合は必ずしも設定不要

ただし、Gradle公式はプロジェクトごとにバージョンを固定できるGradle Wrapperの利用を推奨しています。Wrapperがあるプロジェクトでは、システムにインストールしたGradleではなくwrapperが使用されます。（出典：Gradle「Wrapper Basics」）

GRADLE_USER_HOMEとは

GRADLE_USER_HOMEは、Gradleがユーザー固有のデータを保存するディレクトリです。デフォルトではユーザーホーム直下の.gradleフォルダが使用されます。

• ダウンロードしたGradleディストリビューションのキャッシュ
• 依存ライブラリのキャッシュ
• ビルドキャッシュや設定ファイル

このディレクトリはビルドを繰り返すと大きくなるため、ディスク容量が限られている場合は場所の変更を検討できます。設定は環境変数またはgradle.propertiesで行います。

JavaとGradleのバージョン関係

Gradleを実行するにはJDK 17以上が必要です。また、GradleのバージョンとJavaのバージョンには互換性があります。

これはGradle自体を実行するためのJavaバージョンであり、プロジェクトのコンパイル対象Javaバージョンとは別です。Java Toolchainsを使えば両者を分離できます。（出典：Gradle「Compatibility Matrix」）

要点：GRADLE_HOMEは本体の場所、GRADLE_USER_HOMEはキャッシュや設定の保存場所。通常はWrapperを使えばGRADLE_HOMEの設定は不要。

Gradleビルドを効率化する手法（Version CatalogとbuildSrcの使い分け）

マルチプロジェクトでビルド設定を効率化するには、依存バージョンの一元管理にはVersion Catalog、共通ビルドロジックの共有にはbuildSrcを使い分けるのが公式推奨です。

Version Catalogの基本

Version Catalogは、gradle/libs.versions.tomlに依存関係とバージョンを一元管理する仕組みです。全サブプロジェクトで同じバージョンを参照でき、タイプセーフなアクセサ（libs.xxx）が生成されます。

• [versions]：バージョン番号の宣言
• [libraries]：使用ライブラリの定義
• [bundles]：関連ライブラリのグループ化
• [plugins]：プラグインの定義

このファイルはプロジェクトのgradleディレクトリに配置し、ソース管理にコミットします。ビルドスクリプトではimplementation(libs.junit.jupiter)のように参照します。（出典：Gradle「Dependency Management Basics」）

buildSrcとConvention Plugin

buildSrcは、Gradleが自動的にコンパイルする特別なディレクトリです。ここに共通のビルド設定をカプセル化したConvention Pluginを配置することで、全サブプロジェクトに統一した設定を適用できます。

ルートのbuild.gradle.ktsでallprojectsやsubprojectsを使う古い方法よりも、buildSrcによるConvention Pluginの方がスケーラブルです。ただし、buildSrc内のコードでlibs.versions.tomlを参照するには、Version Catalogから生成されるlibsアクセサがbuildSrcのクラスパスに自動では含まれないため、そのままでは利用できません。そのため、buildSrc内のバージョンとlibs.versions.tomlを手動で同期する必要があります。

Version CatalogとbuildSrcの使い分け

2つの手法は競合するものではなく、役割が異なります。以下の表で比較します。

依存関係のバージョン管理はVersion Catalogに任せ、共通のJava設定やテスト設定などのビルドロジックはbuildSrcのConvention Pluginで共有するのが効果的です。（出典：Gradle「Best Practices for Dependencies」）

要点：依存バージョンはVersion Catalog、共通ビルドロジックはbuildSrc。buildSrcからVersion Catalogは直接参照できないため同期が必要。