kuikly-multi-module-config

Kuikly マルチモジュールプロジェクト管理

目次

• マルチモジュールを使用するタイミング
• 対話型ワークフロー
• 設定の概要
• 重要なルール
• 詳細な設定リファレンス

マルチモジュールが必要な場合

サブモジュールに Kuikly ページ（@Page アノテーションを使用）がある場合にのみ、マルチモジュール設定が必要です。サブモジュールにページがない場合は通常の KMP モジュールであり、特別な設定は不要です。

マルチモジュールで解決する主な問題は、複数の独立した Kuikly モジュールによって KuiklyCoreEntry エントリークラスが競合することです。

対話型ワークフロー

ユーザーから Kuikly サブモジュールの作成を求められた場合は、次の手順に従ってください。

Step 1: 情報を収集する（⚠️ 必ず最初に行い、省略不可）

🚨 必須ルール：設定操作を実行する前に、必ずサブモジュール名をユーザーに尋ねてください。 ユーザーが「サブモジュールを作って」とだけ言った場合でも、必ずいったん作業を止めて、サブモジュールの名前を尋ねてください。名前を受け取ってから先に進んでください。 サブモジュール名を勝手に仮定したり、作り出したりしないでください。

以下の情報をユーザーに尋ねてください（提示されていない場合）：

🔴 必ず確認（1つでも欠けている場合、回答を得るまで後続の手順を実行してはいけません）：

1. サブモジュール名 — ユーザーに「サブモジュールの名前は何にしますか？」と尋ねます（英語。例：kuikly_business）
2. メインモジュール名 — settings.gradle.kts で確認できます。判断できない場合はユーザーに尋ねてください（通常は demo または shared）

名前を確認したら、次のチェックリストを提示してください：

Task Progress:
- [x] Step 1: 确认子模块名称 → ${用户提供的名称}
- [x] Step 2: 确认主模块名称 → ${确认的主模块名}
- [ ] Step 3: 创建子模块目录和 build.gradle.kts
- [ ] Step 4: 修改 settings.gradle.kts
- [ ] Step 5: 修改主模块 build.gradle.kts（依赖 + KSP 多模块参数）
- [ ] Step 6: 创建子模块 src 目录结构
- [ ] Step 7: 生成示例页面（@Page）
- [ ] Step 8: 检查是否有多套 Gradle 配置（如有则每套都需配置）

Step 2: 設定を実行する

次の設定を順番に行い、各手順が完了したらチェックリストにチェックを入れてください。

2.1 settings.gradle.kts

ルートディレクトリの settings.gradle.kts にサブモジュールの include を追加します：

include(":${子模块名}")
// 如果主模块有 buildFileName 配置，子模块也需要：
project(":${子模块名}").buildFileName = buildFileName

2.2 メインモジュールの build.gradle.kts

メインモジュールを変更し、2か所に設定を追加します：

// 1. commonMain 依赖中添加子模块
kotlin {
    sourceSets {
        val commonMain by getting {
            dependencies {
                implementation(project(":${子模块名}"))
            }
        }
    }
}

// 2. ksp 块中配置多模块参数
ksp {
    arg("moduleId", "${主模块名}")
    arg("isMainModule", "true")
    arg("subModules", "${子模块名}")      // 多个子模块用 & 分隔
    arg("enableMultiModule", "true")
}

すでに subModules がある場合：既存の値の後に &${子モジュール名} を追加します。例："sub1&sub2&${新しいサブモジュール}"

2.3 サブモジュールの build.gradle.kts

メインモジュールの build.gradle.kts をサブモジュールのディレクトリに直接コピーし、以下の差分のみを変更してください。それ以外の設定（plugins、targets、cocoapods など）はメインモジュールと完全に一致させてください。

変更が必要な差分：

// 差异 1：ksp 块 — 修改多模块参数
ksp {
    // 其余参数保持不变...
    arg("moduleId", "${子模块名}")       // ← 改为子模块自己的名称
    arg("isMainModule", "false")         // ← 关键：改为 false
    arg("enableMultiModule", "true")
    // ★ 删除 subModules 参数（子模块不需要）
}

// 差异 2：android.namespace — 改为子模块包名
android {
    namespace = "com.tencent.kuikly.${子模块名}"
}

// 差异 3：commonMain dependencies — 移除对其他子模块的依赖（保留 core、compose 等基础依赖）

差分の完全な一覧は SUBMODULE_CONFIG.md を参照してください。

2.4 サブモジュールのディレクトリ構成

${子模块名}/
├── build.gradle.kts
├── src/
│   ├── commonMain/
│   │   ├── kotlin/com/tencent/kuikly/${子模块名}/
│   │   │   └── pages/          # 放 @Page 页面
│   │   └── assets/             # 资源文件（可选）
│   ├── androidMain/            # 以下 *Main 目录根据主模块架构按需创建
│   │   ├── AndroidManifest.xml
│   │   └── kotlin/
│   ├── iosMain/
│   │   └── kotlin/
│   └── jsMain/
│       └── kotlin/

2.5 AndroidManifest.xml

<?xml version="1.0" encoding="utf-8"?>
<manifest package="com.tencent.kuikly.${子模块名}"/>

2.6 サンプルページを生成する

サブモジュールの pages ディレクトリにサンプルページファイルを作成し、設定が正しいかを確認できるよう、サブモジュールに少なくとも1つの @Page ページがあることを確認してください。

サンプルページのテンプレートは、SUBMODULE_CONFIG.md の「サンプルページのテンプレート」セクションを参照してください。

ページファイルのパス：${子モジュール名}/src/commonMain/kotlin/com/tencent/kuikly/${子モジュール名}/pages/SamplePage.kt

2.7 複数の Gradle 設定があるか確認する（存在する場合は、すべての設定で構成が必要）

プロジェクトによっては、異なるプラットフォーム向けに複数の Gradle 設定ファイルを管理している場合があります（例：鸿蒙で build.ohos.gradle.kts、settings.ohos.gradle.kts を個別に使用する場合）。その場合は、次の対応が必要です：

1. プロジェクトのルートディレクトリとメインモジュールのディレクトリを確認し、build.*.gradle.kts または settings.*.gradle.kts ファイルが複数存在するかを確かめます
2. 設定が複数ある場合は、上記の Step 3～5 で行うすべての変更（サブモジュールの build.gradle.kts、settings.gradle.kts、メインモジュールの KSP パラメーターなど）を各設定で繰り返し行う必要があります
3. サブモジュールにも対応する複数の build.gradle.kts（例：build.ohos.gradle.kts）を作成する必要があります。内容は、対応するメインモジュールの設定ファイルをコピーし、差分を変更して作成してください

💡 確認方法：settings.gradle.kts に buildFileName 関連の設定があるか、またはメインモジュールのディレクトリに build.*.gradle.kts ファイルが複数あるかを確認してください。

鸿蒙プラットフォームの具体的な適用方法については、MAIN_MODULE_CONFIG.md を参照してください。

設定早見表

設定項目	メインモジュール	サブモジュール
moduleId	メインモジュール名（例："shared"）	サブモジュール名（例："feature_chat"）
isMainModule	"true"	"false"
subModules	すべてのサブモジュール名を & で区切る	不要
enableMultiModule	"true"	"true"
commonMain の依存関係	implementation(project(":子モジュール"))	メインモジュールに依存しない

重要なルール

❌ サブモジュールは単独でコンパイルできません

サブモジュールはメインモジュールが生成する KuiklyCoreEntry に依存しており、単独では動作しません。必ずメインモジュール経由でコンパイルする必要があります。

❌ moduleId は一意である必要があります

各モジュールの moduleId は異なる値にする必要があります。同じ値にすると、KSP が生成するエントリークラスが競合します。

❌ subModules はメインモジュールでのみ設定します

サブモジュールの ksp ブロックには、subModules パラメーターを設定しないでください。

✅ iOS 側で追加設定は不要です

サブモジュールに cocoapods プラグインを設定すると、Gradle が podspec ファイルを自動生成するため、手動で作成する必要はありません。また、iOS の Podfile でサブモジュールを個別に pod として追加する必要もありません。サブモジュールはメインモジュールと一緒にコンパイルされ、1つの framework（shared.framework）が生成されるためです。

✅ それ以外の設定はメインモジュールに合わせることを推奨します

コンパイル時や実行時の問題につながる設定差異を避けるため、サブモジュールの plugins、kotlin targets、cocoapods、android ブロックなどの設定は、メインモジュールに合わせることを推奨します。メインモジュールの build.gradle.kts を直接コピーし、差分一覧に記載された項目のみを変更してください。

詳細ガイド

• サブモジュールの完全な設定テンプレート（build.gradle.kts ＋ ディレクトリ構成）：SUBMODULE_CONFIG.md
• メインモジュールの変更ガイド（依存関係、KSP 対応）：MAIN_MODULE_CONFIG.md