Building from Source

This guide explains how to build the Metaschema Java project from source code.

Ensure JAVA_HOME is set correctly:

# Linux/macOS
export JAVA_HOME=$(/usr/libexec/java_home -v 17)

# Windows
set JAVA_HOME=C:\Program Files\Java\jdk-17

Clone the repository with submodules:

git clone --recurse-submodules https://github.com/metaschema-framework/metaschema-java.git
cd metaschema-java

If you already cloned without submodules, initialize them:

git submodule update --init --recursive

Build and install to your local Maven repository:

mvn install

mvn test

# Run a single test class
mvn test -Dtest=MetaschemaModuleTest

# Run a single test method
mvn test -Dtest=MetaschemaModuleTest#testLoadModule

mvn install -DskipTests

Replicate the full CI/CD build (recommended before pushing):

mvn install -PCI -Prelease

This enables additional checks including:

• License header verification
• Checkstyle code style checks
• SpotBugs static analysis
• Full test suite

mvn license:check

mvn formatter:format

mvn checkstyle:check

Symptom: Build fails with missing Metaschema schema files.

Solution: Initialize submodules:

git submodule update --init --recursive

Symptom: Compilation errors or “unsupported class file version” errors.

Solution: Ensure you're using Java 17 or later for building:

java -version
mvn -version

Symptom: Build fails with plugin compatibility errors or enforcer rule failures.

Solution: Upgrade Maven to 3.9.0 or later:

mvn -version

Symptom: Build fails with OutOfMemoryError.

Solution: Increase Maven's heap size:

export MAVEN_OPTS="-Xmx2g"
mvn install

To build the project documentation site:

mvn site

The generated site appears in target/site/. For multi-module builds, each module's site is in its respective target/site/ directory.

For contribution guidelines, including code style requirements and the pull request process, see CONTRIBUTING.md.

• Installation - Add the library to your project
• Architecture - Understand the module structure