Developer Environment Setup

July 8, 2026 ยท View on GitHub

This document records environment requirements and constraints for building Simple Java Mail. It is intended for both human developers and coding agents starting new sessions.

For a catalogue of cross-cutting project mechanisms, see PROJECT_MECHANISMS_CATALOGUE.md. For issue, Dependabot, and release handling workflows, see MAINTAINER_WORKFLOW.md.

Java Version

Simple Java Mail must remain Java 8-compatible. Use JDK 8 for dependency bumps and compatibility validation.

The system-wide JAVA_HOME may point to a newer JDK, but Simple Java Mail is incompatible with Java 12+ for CLI metadata generation. Specifically:

  • The CLI module serialises java.lang.reflect.Method objects into cli.data using Kryo. On Java 12+, the Java module system and internal JVM changes break this serialisation.
  • The therapi-runtime-javadoc Javadoc scanning used by the CLI module encounters NPEs on synthetic/bridge methods exposed differently by newer JVM reflection APIs.

Before building, ensure a Java 8 JDK is active.

Use a local, gitignored .maintainer-env.ps1 file for machine-specific paths:

# .maintainer-env.ps1, not committed
$env:JAVA_HOME = "<absolute path to a Java 8 JDK>"
$env:PATH = "$env:JAVA_HOME\bin;$env:PATH"
$env:MAVEN_OPTS = "-Djavax.net.ssl.trustStoreType=WINDOWS-ROOT"
$env:SJM_GH = "<optional absolute path to gh when it is not on PATH>"

Then load it in the shell used for builds:

. .\.maintainer-env.ps1
java -version   # should report 1.8.x

Build

Standard full build (skipping tests and slow checks):

mvn verify -DskipTests -Dmaven.javadoc.skip=true

After any build that ran license:format, clean up auto-generated headers before committing:

mvn com.mycila:license-maven-plugin:3.0:remove

Known Build Constraints

  • ossindex (Sonatype vulnerability scan) has been removed from the build lifecycle. It is configured with <phase/> (empty phase) in the root pom.xml to unbind it.
  • junit-pioneer is pinned to 1.9.1 because the 2.x line ships Java 11 class files. JUnit artifacts may be updated only while preserving Java 8 bytecode compatibility.
  • cli-module uses log4j-slf4j2-impl (not log4j-slf4j-impl) because slf4j-api is at version 2.x which requires the SLF4J 2 bridge adapter.
  • cli.data (modules/cli-module/src/main/resources/cli.data) is a committed binary generated by the CLI module's Kryo serialisation. It must be regenerated whenever the CLI API changes. Do not regenerate it on Java 12+ - use JDK 8.