Ivy 教程 (7)：在多專案環境中使用 Ivy

場景：相互依賴的多模組應用

本教程模擬一個由六個模組組成的應用，模組間存在複雜的依賴關係（如圖所示）。每個模組都依賴其他模組的「最新整合版本」，展示 Ivy 在持續整合環境下的強大能力。

黃色節點為本教程模組，藍色節點為外部第三方依賴。專案原始碼位於 Ivy 發行包的 src/example/multi-project。

專案結構

multi-project/
├── build.xml                 # 根建構檔，按依賴順序協調各模組
├── common/
│   ├── common.xml            # 所有模組共用的建構邏輯
│   └── build.properties      # 共用屬性
└── projects/                 # 各模組目錄
    ├── version/
    ├── list/
    ├── size/
    ├── find/
    ├── sizewhere/
    └── console/              # 入口應用
        ├── ivy.xml           # 模組描述（依賴、配置、發布制品）
        ├── build.xml         # 僅導入 common.xml 與模組專屬屬性
        ├── build.properties  # 模組專屬屬性
        └── src/              # Java 原始碼

核心：通用建構檔 common.xml

所有模組的 build.xml 僅導入 common.xml，真正邏輯集中於此，包含以下關鍵 target：

1. Ivy 設定

<property name="ivy.local.default.root" value="${repository.dir}/local"/>
<property name="ivy.shared.default.root" value="${repository.dir}/shared"/>

分別指向本地（開發者私有）與共享（團隊共用）儲存庫。若需更複雜設定，可改用自訂 ivysettings.xml。

2. 解析依賴

<target name="resolve" depends="clean-lib, load-ivy">
  <mkdir dir="${lib.dir}"/>
  <ivy:resolve file="${ivy.file}"/>
  <ivy:retrieve pattern="${lib.dir}/[artifact].[ext]" />
</target>

顯式呼叫 resolve 再 retrieve，將解析到的制品複製到專案 lib 目錄（不含版本號），方便 IDE 設定固定類別路徑。

3. 自動產生版本號

<target name="ivy-new-version" depends="load-ivy" unless="ivy.new.revision">
  <property name="module.version.prefix" value="${module.version.target}-dev-b"/>
  <ivy:info file="${ivy.file}"/>
  <ivy:buildnumber organisation="${ivy.organisation}" module="${ivy.module}"
                   revision="${module.version.prefix}" defaultBuildNumber="1" revSep=""/>
</target>

利用 ivy:buildnumber 掃描儲存庫，依前綴產生下一個可用版本號（如 1.0-dev-b1、1.0-dev-b2...）。模組可透過覆寫 module.version.target 或 module.version.prefix 自訂版本策略。

4. 發布到共享儲存庫

<target name="publish" depends="clean-build, jar">
  <ivy:publish artifactspattern="${build.dir}/[artifact].[ext]"
               resolver="shared" pubrevision="${version}" status="release"/>
  <echo message="project ${ant.project.name} released with version ${version}"/>
</target>

釋出正式版本供團隊使用，狀態標記為 release。

5. 發布到本地儲存庫

<target name="publish-local" depends="local-version, jar">
  <ivy:publish artifactspattern="${build.dir}/[artifact].[ext]"
               resolver="local" pubrevision="${version}" pubdate="${now}"
               status="integration" forcedeliver="true"/>
  <echo message="project ${ant.project.name} published locally with version ${version}"/>
</target>

開發階段發布 integration 版本，僅影響本機環境。修改模組後執行此 target，其他依賴此模組的專案下次建構即可自動獲取最新變更。

6. 清理本地版本

<target name="clean-local">
  <delete dir="${ivy.local.default.root}/${ant.project.name}"/>
</target>

當正式版本發布至共享儲存庫，或決定放棄本地修改時使用。

7. 依賴報告與圖形化

<target name="report" depends="resolve">
  <ivy:report todir="${build.dir}"/>
</target>

生成 HTML 報表與 GraphML 圖形檔，執行 ant report 後可在 projects/console/build/ 找到圖形檔，配合 GraphML 檢視器即可視覺化整個應用的依賴拓撲。

實戰操作

在 src/example/multi-project 執行 ant publish-all，Ivy 會依依賴順序依次編譯、打包、發布所有模組。嘗試修改某模組原始碼（如變更方法名稱）並同步調整呼叫端，再次執行 publish-all 觀察自動化流程。

進入單一模組目錄（如 projects/find）執行 ant -p 可見完整 target 列表。透過調整 ivy.xml 中的版本約束（如從 latest.integration 改為固定穩定版本），即可輕鬆控制傳遞依賴帶來的風險。

結語

多專案環境是 Ivy 展現價值的最佳舞臺。透過集中化的建構邏輯、自動版本管理、本地/共享儲存庫分離與依賴視覺化，團隊能輕鬆掌控龐大模組圖譜。這只是起點，請深入參考文件、加入郵件列表、貢獻原始碼，共同推動 Ivy 成為最佳依賴管理工具！