Building OmegaT

OmegaT is built with Gradle. Run gradlew tasks from the top level to see the available tasks. Run gradlew build to build all possible distfiles and run the main tests. Tasks skipped due to missing requirements will be noted in the output.

OmegaT will run on the latest Java, but is required to be compatible with Java 11.

Eclipse and NetBeans are recommended IDEs for working with OmegaT source code. NetBeans is required to modify *.form-based GUI layouts (install the Gradle Support plugin to open the OmegaT project in NetBeans.)

Check the other files in this directory for documentation. You can produce Javadoc by running gradlew javadoc, or browse online:

https://omegat.sourceforge.io/javadoc-latest/

Prerequisite

As of Dec. 2023, here are the requirements to build OmegaT binaries;

  1. Java Development kit 11 or later. When you want to build a Linux deb/rpm package, JDK 17 or later is required.

  2. Requires docker or nerdctl command to launch containerized processes. Build process for windows packages will be skipped when neither docker nor nerdctl command is not found.

  3. JDK 21 has not been supported yet to launch Gradle build tool, but it works well as an OmegaT runtime.

Configuring Build Tasks

Some build tasks, such as signed installers, require additional configuration via a local.properties file placed at the root of the source tree. See local.properties.example.

Build Assets

Some build tasks require the user to supply additional files not included in the OmegaT source. These files should be placed in the assets directory, which by default is .., i.e. one level up from the OmegaT source root. You can specify a different directory by supplying the argument -PassetDir=/path/to/wherever.

In particular, with-JRE builds require a JRE tarball for the appropriate platform, e.g. OpenJDK11U-jre-*-macosx-x64.tar.gz.

Containerized Tasks

Some build tasks require additional software to be installed:

Working with Dependencies

OmegaT uses Gradle to manage and fetch dependencies automatically. To add, change, or remove a dependency, see the dependencies block in build.gradle.

Dependency JARs are provided in the “source” distribution of OmegaT under /lib/provided, as insurance in case any dependencies should become unavailable online. When /lib/provided is present, compile-time dependencies will be resolved locally, minimizing network access (network access is still required for initializing the Gradle wrapper, fetching Gradle plugins, and fetching test dependencies).

Source Distribution

The OmegaT source distribution (OmegaT_*_Source.zip) is a self-contained archive that guarantees users can build OmegaT using only the bundled dependencies, without requiring external internet access to download third-party libraries.

Purpose and Concept

The source distribution serves as a long-term archive of OmegaT that remains buildable even if upstream dependency projects cease maintenance or remove their published artifacts from repositories. This ensures that OmegaT releases can always be rebuilt from source in the future, regardless of external project lifecycles.

Contents and Structure

The source distribution includes:

  • Core source code: Complete Java source files, build configuration, and related resources

  • Bundled dependencies: All required JAR files stored in two directories:

    • lib/provided/core - Core dependencies required for the main application

    • lib/provided/modules - Dependencies for bundled plugin modules

  • Build scripts: Gradle wrapper and build configuration files

  • Documentation: Source documentation and configuration files

  • Tests: All test source files and test data

Build Mechanism

The OmegaT build system automatically detects when it is building from a source distribution through the presence of the lib/provided/core directory. When detected, the build system uses the bundled JARs instead of downloading dependencies from remote repositories.

The detection is performed in build.gradle using:

if (providedCoreLibsDir.directory) {
    // Use bundled dependencies from lib/provided/core and lib/provided/modules
} else {
    // Download dependencies from configured repositories (Maven Central, etc.)
}

This mechanism ensures that:

  1. Building from the source distribution requires no external network access for dependencies

  2. The exact same dependency versions are always used for reproducible builds

  3. Users can build OmegaT even if dependency projects have been abandoned or removed

Building from Source Distribution

To build OmegaT from the source distribution:

  1. Extract the OmegaT_*_Source.zip archive

  2. Navigate to the extracted directory

  3. Run the standard build command:

./gradlew build

  1. The build system automatically detects and uses the bundled dependencies in lib/provided

Note for enterprise / offline builds: The source distribution bundles all runtime and module dependencies in lib/provided/core and lib/provided/modules, but the build-logic Gradle plugins (e.g. SpotBugs, Spotless, ErrorProne) are not included. Enterprise administrators must separately populate lib/build-logic with the required JARs before running ./gradlew --offline. See Offline Build for step-by-step instructions.

Testing and Validation

The continuous integration workflow includes a dedicated test (source-distribution-test.yml) that verifies the source distribution’s completeness:

  1. Builds the source distribution archive

  2. Extracts it in a clean environment

  3. Builds OmegaT from the extracted source using only bundled dependencies

  4. Validates that no duplicate dependencies are included

This testing ensures that every release can be successfully built from source with all required dependencies included.

Customized Dependencies

OmegaT uses unmodified packages as much as possible, but when modifications are required and the upstream project is abandoned or unresponsive, custom-patched libraries are also used.

Patched forks can be found on GitHub: https://github.com/omegat-org

In some cases (especially defunct projects) OmegaT forks are also published for general use on Maven Central: https://search.maven.org/search?q=g:org.omegat*

Dependencies not available for consumption via Maven/Gradle are committed to /lib/manual.

Basic build tasks

You can see defined tasks by running ./gradlew tasks at the root of the project. If you use IDEs that support Gradle, such as Eclipse, Apache NetBeans or Jetbrains IntelliJ, they will show you the list of available tasks.

------------------------------------------------------------
Tasks runnable from root project 'OmegaT'
------------------------------------------------------------

Application tasks
-----------------
run - Runs this project as a JVM application
runDebugger - Runs application for debugging.
runOnJava11 - Runs application on Java 11.
runOnJava21 - Runs application on Java 21.

Build tasks
-----------
assemble - Assembles the outputs of this project.
build - Assembles and tests this project.
buildDependents - Assembles and tests this project and all projects that depend on it.
buildNeeded - Assembles and tests this project and all projects it depends on.
classes - Assembles main classes.
clean - Deletes the build directory.
jar - Assembles a jar archive containing the classes of the 'main' feature.
javadocJar - Assembles a jar archive containing the main javadoc.
sourcesJar - Assembles a jar archive containing the main sources.
testAcceptanceClasses - Assembles test acceptance classes.
testClasses - Assembles test classes.
testFixturesClasses - Assembles test fixtures classes.
testFixturesJar - Assembles a jar archive containing the classes of the 'testFixtures' feature.
testIntegrationClasses - Assembles test integration classes.

Build Setup tasks
-----------------
init - Initializes a new Gradle build.
spotlessInstallGitPrePushHook - Installs Spotless Git pre-push hook.
updateDaemonJvm - Generates or updates the Gradle Daemon JVM criteria.
wrapper - Generates Gradle wrapper files.

Develocity tasks
----------------
buildScanPublishPrevious - Publishes the data captured by the last build.
provisionDevelocityAccessKey - Provisions a new access key for this build environment.

Distribution tasks
------------------
assembleDist - Assembles the main distributions
assembleSourceDist - Assembles the source distributions
distTar - Bundles the project as a distribution.
distZip - Bundles the project as a distribution.
installDist - Installs the project as a distribution as-is.
installLinux64Dist - Creates a linux installDist for linux64.
installLinuxArm64Dist - Creates a linux installDist for linuxArm64.
installMacArmDist - Builds the macOS distribution.
installMacArmSignedDist - Builds the signed macOS distribution. Requires an Apple Developer Account.
installMacX64Dist - Builds the macOS distribution.
installMacX64SignedDist - Builds the signed macOS distribution. Requires an Apple Developer Account.
installSourceDist - Installs the project as a distribution as-is.
linux - Builds the Linux distributions.
linux64DistTarBz - Creates a Linux distribution for linux64.
linuxArm64DistTarBz - Creates a Linux distribution for linuxArm64.
linuxDistDeb
linuxDistRpm
mac - Builds the Mac distributions.
sourceDistTar - Bundles the project as a distribution.
sourceDistZip - Bundles the project as a distribution.
win - Builds the Windows distributions.
winArm64JRE - Creates a Windows installer for winArm64JRE distro. Requires Inno Setup (http://www.jrsoftware.org/isinfo.php).
winJRE64 - Creates a Windows installer for winJRE64 distro. Requires Inno Setup (http://www.jrsoftware.org/isinfo.php).
winNoJRE - Creates a Windows installer for winNoJRE distro. Requires Inno Setup (http://www.jrsoftware.org/isinfo.php).

Documentation tasks
-------------------
firstSteps - Builds the introductory page for all languages at src/docs/greetings/.
javadoc - Generates Javadoc API documentation for the 'main' feature.
manualCa - Builds the whc contents.
manualEn - Builds the whc contents.
manualFr - Builds the whc contents.
manualHtmls - Builds and zips the HTML manuals for all languages.
manualIt - Builds the whc contents.
manualJa - Builds the whc contents.
manualNl - Builds the whc contents.
testFixturesJavadoc - Generates Javadoc API documentation for the 'testFixtures' feature.
tipsHtmls - Copy tips html/css contents into build folder

Help tasks
----------
artifactTransforms - Displays the Artifact Transforms that can be executed in root project 'OmegaT'.
buildEnvironment - Displays all buildscript dependencies declared in root project 'OmegaT'.
dependencies - Displays all dependencies declared in root project 'OmegaT'.
dependencyInsight - Displays the insight into a specific dependency in root project 'OmegaT'.
help - Displays a help message.
javaToolchains - Displays the detected java toolchains.
outgoingVariants - Displays the outgoing variants of root project 'OmegaT'.
projects - Displays the sub-projects of root project 'OmegaT'.
properties - Displays the properties of root project 'OmegaT'.
resolvableConfigurations - Displays the configurations that can be resolved in root project 'OmegaT'.
tasks - Displays the tasks runnable from root project 'OmegaT' (some of the displayed tasks may belong to subprojects).

IDE tasks
---------
cleanEclipse - Cleans all Eclipse files.
eclipse - Generates all Eclipse files.

Jaxb tasks
----------
genFilters
genJAXB - Generate classes for loading and manipulating XML formats
genProject
genSegmentation
genTbx

Launch4j tasks
--------------
createAllExecutables - Runs all tasks that implement DefaultLaunch4jTask
createExe - Runs the launch4j jar to generate an .exe file

Publishing tasks
----------------
closeAndReleaseSonatypeStagingRepository - Closes and releases open staging repository in 'sonatype' Nexus instance.
closeAndReleaseStagingRepositories - Closes and releases open staging repositories in the following Nexus instance: 'sonatype'
closeSonatypeStagingRepository - Closes open staging repository in 'sonatype' Nexus instance.
closeStagingRepositories - Closes open staging repositories in the following Nexus instance: 'sonatype'
findSonatypeStagingRepository - Finds the staging repository for sonatype
generateMetadataFileForManualCaPublication - Generates the Gradle metadata file for publication 'manualCa'.
generateMetadataFileForManualEnPublication - Generates the Gradle metadata file for publication 'manualEn'.
generateMetadataFileForManualFrPublication - Generates the Gradle metadata file for publication 'manualFr'.
generateMetadataFileForManualItPublication - Generates the Gradle metadata file for publication 'manualIt'.
generateMetadataFileForManualJaPublication - Generates the Gradle metadata file for publication 'manualJa'.
generateMetadataFileForManualNlPublication - Generates the Gradle metadata file for publication 'manualNl'.
generateMetadataFileForMavenJavaPublication - Generates the Gradle metadata file for publication 'mavenJava'.
generatePomFileForManualCaPublication - Generates the Maven POM file for publication 'manualCa'.
generatePomFileForManualEnPublication - Generates the Maven POM file for publication 'manualEn'.
generatePomFileForManualFrPublication - Generates the Maven POM file for publication 'manualFr'.
generatePomFileForManualItPublication - Generates the Maven POM file for publication 'manualIt'.
generatePomFileForManualJaPublication - Generates the Maven POM file for publication 'manualJa'.
generatePomFileForManualNlPublication - Generates the Maven POM file for publication 'manualNl'.
generatePomFileForMavenJavaPublication - Generates the Maven POM file for publication 'mavenJava'.
initializeSonatypeStagingRepository - Initializes the staging repository in 'sonatype' Nexus instance.
publish - Publishes all publications produced by this project.
publishAllPublicationsToSonatypeRepository - Publishes all Maven publications produced by this project to the sonatype repository.
publishManualCaPublicationToMavenLocal - Publishes Maven publication 'manualCa' to the local Maven repository.
publishManualCaPublicationToSonatypeRepository - Publishes Maven publication 'manualCa' to Maven repository 'sonatype'.
publishManualEnPublicationToMavenLocal - Publishes Maven publication 'manualEn' to the local Maven repository.
publishManualEnPublicationToSonatypeRepository - Publishes Maven publication 'manualEn' to Maven repository 'sonatype'.
publishManualFrPublicationToMavenLocal - Publishes Maven publication 'manualFr' to the local Maven repository.
publishManualFrPublicationToSonatypeRepository - Publishes Maven publication 'manualFr' to Maven repository 'sonatype'.
publishManualItPublicationToMavenLocal - Publishes Maven publication 'manualIt' to the local Maven repository.
publishManualItPublicationToSonatypeRepository - Publishes Maven publication 'manualIt' to Maven repository 'sonatype'.
publishManualJaPublicationToMavenLocal - Publishes Maven publication 'manualJa' to the local Maven repository.
publishManualJaPublicationToSonatypeRepository - Publishes Maven publication 'manualJa' to Maven repository 'sonatype'.
publishManualNlPublicationToMavenLocal - Publishes Maven publication 'manualNl' to the local Maven repository.
publishManualNlPublicationToSonatypeRepository - Publishes Maven publication 'manualNl' to Maven repository 'sonatype'.
publishMavenJavaPublicationToMavenLocal - Publishes Maven publication 'mavenJava' to the local Maven repository.
publishMavenJavaPublicationToSonatypeRepository - Publishes Maven publication 'mavenJava' to Maven repository 'sonatype'.
publishToMavenLocal - Publishes all Maven publications produced by this project to the local Maven cache.
publishToSonatype - Publishes all Maven/Ivy publications produced by this project to the 'sonatype' Nexus repository.
publishVersion - Updates the version considered current by the version check.
releaseSonatypeStagingRepository - Releases closed staging repository in 'sonatype' Nexus instance.
releaseStagingRepositories - Releases open staging repositories in the following Nexus instance: 'sonatype'
retrieveSonatypeStagingProfile - Gets and displays a staging profile id for a given repository and package group. This is a diagnostic task to get the value and put it into the NexusRepository configuration closure as stagingProfileId.                                                                                                                                                                                                                       

Verification tasks
------------------
check - Runs all checks.
jacocoAcceptanceReport
jacocoIntegrationReport
jacocoTestCoverageVerification - Verifies code coverage metrics based on specified rules for the test task.
jacocoTestReport - Generates code coverage report for the test task.
spotbugsMain - Run SpotBugs analysis for the source set 'main'
spotbugsReport
spotbugsTest - Run SpotBugs analysis for the source set 'test'
spotbugsTestAcceptance - Run SpotBugs analysis for the source set 'testAcceptance'
spotbugsTestFixtures - Run SpotBugs analysis for the source set 'testFixtures'
spotbugsTestIntegration - Run SpotBugs analysis for the source set 'testIntegration'
spotlessApply - Applies code formatting steps to sourcecode in-place.
spotlessChangedApply - Applies code formatting to files that have been changed on the current branch.
spotlessCheck - Checks that sourcecode satisfies formatting steps.
spotlessDiagnose
spotlessJava
spotlessJavaApply
spotlessJavaCheck
spotlessJavaDiagnose
test - Runs the test suite.
testAcceptance - Runs acceptance GUI test.
testCodeCoverageReport - Generates aggregated code coverage report.
testIntegration - Runs integration tests. Pass repo URL as -Domegat.test.repo=<repo>.
validateModuleMetadata - Validate OmegaT module metadata (e.g., org.omegat.module.category).

Rules
-----
Pattern: clean<TaskName>: Cleans the output files of a task.
Pattern: build<ConfigurationName>: Assembles the artifacts of a configuration.

Most tasks are accompanied by an explanatory sentence.

I want to run OmegaT with some modification

There are two major ways to build and execute OmegaT from source.

  1. use application tasks

The tasks are run, runOnJava17 and runOnJava21. They will compile the core of OmegaT, all the modules, the First Steps documents, place module jars in the build/modules folder and launch the main function from source. You can add command line arguments to the Gradle command with --args="argument value".

Example:

./gradlew run --args="-Xmx4096M --add-opens java.desktop/sun.awt.X11=ALL-UNNAMED  -Duser.language=ja -Duser.country=JP"

  1. use installDist task

When running installDist task, the OmegaT build system compiles the core of OmegaT, all the modules, the first step pages, all the bundled manuals, and copies the files with installed structure in build/install/OmegaT/. #What is “with installed structure”? You can open a terminal in the folder, and launch OmegaT from there.

Example:

./gradlew installDist

cd build/install/OmegaT/
./OmegaT

I want to build a specific module

You can use the module::task syntax to build the jar file for a specific module.

Example:

./gradlew aligner:jar

When the build is finished, the aligner-omegat.jar file will be found in build/modules/.

I want to build HTML manual in my language

There are manualHtmlXX tasks, here XX is a 2-letter language code such as En, Ca, Fr. When you want to build html manuals in all supported languages, use manualHtlms instead.

Quick OmegaT project building

We provide several ways and technics to speed up the build-and-try cycles.

Smart task execution

The OmegaT build system is configured to use Gradle task smart build features. Once you run a build task, such as making a jar, the HTML manuals, and then modified some code, Gradle will skip all the unchanged parts of the project, and only compile and generate the required jar. You will see explanatory labels in a build log. These labels are based show if a task has actions to execute, if it should execute those actions, if it did execute those actions and if those actions made any changes.

  • (no label) or EXECUTED

    Task executed its actions.

  • UP-TO-DATE

    Task’s outputs did not change.

  • FROM-CACHE

    Task’s outputs could be found from a previous execution.

  • SKIPPED

    Task did not execute its actions.

  • NO-SOURCE

    Task did not need to execute its actions.

Modular architecture

The OmegaT project source tree is configured as a multi-project format. When building OmegaT, the Gradle build system runs compilation and other tasks concurrently among the subprojects. OmegaT has several modules which are bundled plugins, that are handled in a parallel way. Gradle will use as many cores as the computer has.

Customizing Logging for Debugging

OmegaT uses a configuration file (logger.properties) to set up application logging via Java Util Logging (JUL). You can customize logging behavior for development or debugging by providing your own configuration file and specifying it at launch.

Default Logging Configuration

By default, OmegaT’s logger.properties defines logging as follows:

  • Handlers: Both console and file logging are enabled:

handlers = java.util.logging.ConsoleHandler, org.omegat.util.logging.OmegaTFileHandler

- **Log Levels:** The root logger level is set to `INFO`. Most OmegaT and third-party components are set to `INFO` or `SEVERE`:

.level = INFO org.omegat.level = ALL org.omegat.core.data.level = INFO cz.vutbr.web.level = SEVERE

- **Custom Formatter:** A special formatter controls log message layout (timestamp, thread, level, etc.).

- **File Logging Options:** Log files are automatically rotated by size and have retention policies:

org.omegat.util.logging.OmegaTFileHandler.size=1048576 org.omegat.util.logging.OmegaTFileHandler.count=30 org.omegat.util.logging.OmegaTFileHandler.retention=1020000


### Changing the Log Level

You can increase the amount of detail in the logs by changing log levels in your custom `logger.properties`:

- To show debug messages for everything, set:

.level = FINE org.omegat.level = ALL java.util.logging.ConsoleHandler.level = FINE org.omegat.util.logging.OmegaTFileHandler.level = FINE

- To focus on a single component (e.g. `org.omegat.core.data`), set:

org.omegat.core.data.level = FINE


### Customizing Handlers and Output

- **Disable File Logging:** Remove the file handler from the handlers list:

handlers = java.util.logging.ConsoleHandler

- **Change the Console Log Format:** Adjust the formatter mask:

org.omegat.util.logging.OmegaTLogFormatter.mask=\(time: \)level: \(text \)key

(You can uncomment and experiment with other mask options shown in the file.)

### Using Your Custom Configuration

1. **Save your changes to a file** (for example, `my-logger.properties`).
2. **Start OmegaT with your file:**

java -Pjava.util.logging.config.file=/path/to/my-logger.properties -jar OmegaT.jar


### Advanced: Filtering Third-Party Logs

You can use the same file to suppress logs from other libraries used by OmegaT:

cz.vutbr.web.level = SEVERE org.fit.net.level = SEVERE

### Tips

- Use `ALL` for maximum output, `SEVERE` for errors only.
- Logging for individual classes is possible—uncomment and adjust lines like:

#org.omegat.core.data.SaveThread.level = FINEST

- For full reference on syntax and log levels, see the [Java Logging Configuration documentation](https://docs.oracle.com/en/java/javase/11/docs/api/java.logging/java/util/logging/package-summary.html).

---

By customizing `logger.properties` and launching with the `-Pjava.util.logging.config.file` option,
you can tailor OmegaT’s logging to fit your debugging or development needs.