Building from Source

This guide explains how to build OSCAL Java Library 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/liboscal-java.git
cd liboscal-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=ExamplesTest

# Run a single test method
mvn test -Dtest=ExamplesTest#testExample

mvn install -DskipTests

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

mvn install -PCI -Prelease

This enables additional checks including:

• License header verification
• Code style checks
• Full test suite

mvn license:check

mvn formatter:format

mvn checkstyle:check

Symptom: Build fails with missing OSCAL 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 (required due to build plugin requirements):

java -version
mvn -version

Symptom: Build fails with plugin compatibility errors.

Solution: Upgrade Maven to 3.9.0 or later. Check your version:

mvn -version

Symptom: Build fails with OutOfMemoryError.

Solution: Increase Maven's heap size:

export MAVEN_OPTS="-Xmx2g"
mvn install

Symptom: Build fails during license:check phase.

Solution: Run the formatter to add missing headers:

mvn license:format

To build the project documentation site:

mvn install site -DskipTests

Note: The install and site goals must run together in a single Maven invocation. This is required because the Javadoc plugin needs access to the generated OSCAL model classes, which are only available after the install phase completes within the same Maven session.

Running mvn site alone will fail with Javadoc errors about missing model classes.

OSCAL model classes are generated during the build from Metaschema definitions in the oscal/ submodule. These generated classes appear in:

target/generated-sources/metaschema/

If you make changes to the OSCAL Metaschema modules, run a clean build:

mvn clean install

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

Once you've built the project, explore these resources to start using the library:

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