ADR: OmegaT Build System Improvement Using Modular Conventions

Status

Accepted – Fully Implemented Updated - 2026-05-31

Context

OmegaT’s previous build system relied on a single, monolithic build.gradle file containing more than 1,800 lines of code. This presented several challenges:

  • Maintainability: The sheer size and complexity of the build.gradle file made it difficult for developers to understand and update.

  • Redundancy: Repeated configuration logic across multiple module subprojects increased the risk of inconsistency.

  • Scalability: As OmegaT’s project gained more modules, the build system struggled to accommodate future growth in a manageable way.

Given OmegaT’s structure of 42 module subprojects, there was a need for a cleaner, more maintainable, and scalable approach using Gradle’s conventions plugin mechanism.

Decision

The development team decided to refactor the build system by modularizing the configurations through centralized, reusable Gradle convention plugins.

Updates

Key Architectural Changes

Modularization of Build Configurations

  • build-logic/ directory: A directory for Groovy-based convention plugins such as:

    • org.omegat.java-conventions.gradle

    • org.omegat.version-conventions.gradle

    • org.omegat.windows-conventions.gradle

  • Gradle plugin implementations with Groovy such as:

    • org.omegat.module.OmegatModulePlugin.groovy

    • org.omegat.documentation.DocumentationPlugin.groovy

  • Each plugin centralizes repetitive build logic (e.g., manifest setup, task definitions) and applies standardized configurations across module projects.

  • Gradle plugin implementations support complex builds without Docker container execution or complex convention hacks.

Plugin-Based Approach

  • Modules now apply the shared conventions using Gradle’s plugins block:

    plugins {
    id 'org.omegat.module'
}

  • Centralized configuration leads to consistency across module subprojects.

Removal of Redundancy

  • Redundant configurations (e.g., explicit jar task setups) were eliminated in favor of reusable conventions.

  • The utils.gradle file, previously housing miscellaneous build helper functions, was replaced by better-organized logic in build-logic/.

Simplification of build.gradle

  • The main build.gradle file was reduced from 1,881 lines to 723.

  • Many individual module build.gradle files were streamlined as redundant logic was removed.

Gradle Version Update

  • The project updated to Gradle version 8.12, benefiting from enhanced features and improved compatibility.

Centralized Properties

  • Project-specific variables such as the application name, description, and main class were moved to a unified gradle.properties file.

Implementation Details

Summary of Changes

  • Conventions Plugins:

    • Introduced reusable conventions stored under build-logic/.

  • Dependency Management:

    • Centralized dependency declarations to reduce duplication and align versions across modules.

  • Plugin Migration:

    • Consolidated plugin configurations (e.g., Spotbugs, Spotless) under conventions.

  • Documentation and Testing Support:

    • Updated build scripting for documentation and testing tasks.

  • FatJar Implementation:

    • Module builds now produce FatJar artifacts stored in build/modules, alongside normal JARs in subproject directories.

Metrics

  • Reduction in overall build script lines: Removed 2,258 lines and added 1,682 lines, resulting in a 33% reduction in complexity.

Consequences

Benefits

  1. Improved Maintainability:

    • Modular scripts are smaller and easier to read and maintain.

    • Developers can now focus on their respective modules without navigating a monolithic configuration file.

  2. Consistency Across Modules:

    • Convention plugins enforce consistent build logic, reducing errors and drifts between modules.

  3. Scalability:

    • The new architecture supports future expansion, making it easier to integrate new modules.

  4. Enhanced Performance:

    • Gradle pre-compiles convention plugins, improving build times.

  5. Developer Productivity:

    • Simplified build scripts and standardized configurations free developers from managing repetitive tasks.

Trade-Offs

  • Learning Curve:

    • Developers unfamiliar with Gradle conventions may require some time to understand the new structure.

  • Initial Effort:

    • Refactoring required significant effort in splitting and testing the modular configuration.

Testing and Verification

  • The refactored build system was tested across multiple environments.

  • The new structure successfully allows OmegaT to integrate module-subproject conventions while maintaining backward compatibility.

Migration Strategy

  1. Legacy patterns in the previous build system were deprecated but temporarily supported to ensure smooth migration.

  2. Documentation was updated to guide contributors on the use of conventions.

Future Considerations

  • Modular Expansion:

    • The conventions plugins provide a strong foundation for additional automation and functionality in the future.

  • Build Process Enhancements:

    • Gradual enhancement of build logic.

References

Date: 2025-01-17 Update: 2026-05-31 Author: Hiroshi Miura Reviewers: OmegaT Development Team