Java

The Java integration stages Eclipse Temurin 25 for Linux x64 and launches it through XerisOS's application ABI layer. The payload contains a JRE and its libraries, not a Linux kernel or Linux operating system. It does not include Minecraft or a Minecraft launcher.

Current status#

As of 2026-10-04:

• The official Temurin jdk-25.0.4.1+1 JRE and matching upstream source archive have been downloaded, verified against pinned SHA-256 checksums, and staged.
• The staging tool passes 17 host tests covering metadata selection, archive traversal, FAT name collisions, file/directory links, cycles, preservation of notices, source retention, manifest checksums, and installer path limits.
• XerisOS has a bounded java argument parser, a Java-specific USB installer, and a launcher targeting /JAVA25/bin/java.
• Experimental Java and Minecraft launch are now enabled in the normal build. java install, java verify, and java where install the separate runtime. The owner's private game has equivalent minecraft install|verify|where commands. See the Beelink transfer guide.
• The first QEMU JVM launch stopped at HotSpot's deliberate CPU-feature probe. The launcher passed -version correctly and loaded libjvm, libjimage, and libjava. HotSpot's AVX OS-state probe deliberately dereferenced a null pointer; XerisOS killed the thread instead of delivering its registered SIGSEGV handler, then hit a secondary kernel fault. No Java version text was produced. This failure is captured in build/java-qemu/default-version-serial.log; testing remains on an isolated QEMU image. A second run with -XX:UseAVX=0 failed at the same mandatory probe; disabling AVX does not bypass this startup step. build/java-qemu/results.json records both runs and their frozen kernel hash. The shared exception/IST changes were applied after explicit approval. QEMU now passes deliberate null faults, illegal instructions, register/vector restoration, alternate signal stacks and default fatal signal handling. The existing seccomp guest suite also passes on a fresh boot, without a kernel panic. A later same-boot run after the pointer probe failed one guard-stack assertion following mmap exhaustion with prior mappings retained; sequential application cleanup is still a separate limitation. The memory-permission patch was subsequently approved and applied. Kernel 4cc34b6a passes both expanded guard/fault probes and the fresh-boot seccomp regression: absent/backed guards, access restoration, fixed remaps, sparse 32 GiB ranges, guarded file population, and fatal main-thread recovery.
• The JVM now starts successfully in QEMU. Private test kernel a6817407 prints the unmodified Temurin 25.0.4.1 version and exits. The original RuntimeSmoke.jar passes all 13 checks: arguments, threads, timed waits, atomics, thread locals, hot methods, garbage collection, direct buffers, SHA-256, JNI and file write/rename/reopen in one session. Evidence is in build/java-qemu/java-version-a681-serial.log, java-smoke-a681-serial.log and java-guard-runtime-results.json.
• The Java graphics probe passes in QEMU. Selecting the Linux native ABI with a process-only -Dos.name=Linux property lets unmodified LWJGL load its supplied libraries. The probe displays a native Xeris window, verifies its framebuffer, and completes 1,287 swaps in 15 seconds with OpenGL 4.5 through Mesa llvmpipe. This is a simple probe, not Minecraft performance. Evidence is build/java-qemu/graphics-pass-a681-serial.log and its frozen snapshot.
• The unmodified Minecraft 26.1 client enters a single-player world in QEMU. Kernel 5e3f096b renders terrain, trees, clouds, hand and HUD. Held W changes player coordinates; E opens inventory and Escape opens/closes menus. The directory error that blocked world creation is fixed. Screenshots are in build/java-qemu/shots/, including minecraft-world-entered.png, minecraft-debug-before.png, minecraft-moved-camera.png and minecraft-inventory.png. minecraft-joined-5e3f.log records the world join. Performance was only 1-3 FPS with software rendering, not a Beelink result. Normal kernel c211e9fc also reaches the welcome/title UI without a private Java gate override. Long runs can still exhaust virtual-address space.
• Java subprocess I/O passes in the guest. Kernel 72f81b1a passes ProcessProbe: separate stdout/stderr, EOF, exit status 37, waitFor, and a missing executable producing IOException. Descriptor aliases survive the helper's ordinary descriptor-close loop. Evidence is in build/java-qemu/process-pass-72f8-serial.log and its snapshot. Game camera motion, authenticated login, Java networking, audible output, reboot-persistent saves and sustained performance remain unverified. Use disposable worlds. The newer bounded session-reset implementation passes Minecraft close → OBS → repeated Java launches in QEMU; it retains old address spaces and permits at most eight prepared sessions per boot. See the close/relaunch evidence and limits.

The development payload is at build/java-runtime/stage/. Its pinned artifacts are:

Runtime dependencies#

The Java package preserves the upstream JRE hierarchy, including bin, lib, conf, and legal. It does not contain XerisOS's shared glibc runtime. The current QEMU fixture supplies /LD.SO, glibc, and supporting libraries from the existing OBS/glibc runtime layers. A fresh XerisOS installation needs those compatible runtime files as well; copying only JAVA25/bin/java is insufficient.

The existing OBS payload installation is the current route for those shared dependencies. OBS does not need to be running. Close OBS, Chrome, and other ABI applications before replacing runtime files or launching Java: the current loader permits one application session at a time.

Make a USB payload on the development computer#

Run from the repository root using Python 3.10 or newer. For a FAT32 USB drive mounted as E:, with no existing E:/xeris-java/JAVA25:

python tools/java_runtime.py --out E:/xeris-java --with-source

The default lookup selects the latest general-availability Eclipse Temurin 25 Linux x64 HotSpot JRE from Adoptium's API. The output records the exact selected release, download URL, size, and checksum; a later invocation can select a newer release. Downloads are checksum-verified before extraction. The runtime cannot be staged over an existing JAVA25 directory or manifest; choose a fresh output directory when preparing an update.

To stage the already-downloaded development artifacts without another metadata lookup or download:

python tools/java_runtime.py --archive build/java-runtime/OpenJDK25U-jre_x64_linux_hotspot_25.0.4.1_1.tar.gz --sha256 1731a34baadec5479258ea0202e4d5d865d2efeee60cb0c7d7eb056fe96ca219 --metadata build/java-runtime/temurin25-metadata.json --with-source --source-archive build/java-runtime/OpenJDK25U-jdk-sources_25.0.4.1_1.tar.gz --source-sha256 cb9e50d2eb3de72ffd28466d7c511b4039b4bc4bd8f0d276d1e4cf81e30fdf09 --source-metadata build/java-runtime/temurin25-release-metadata.json --out E:/xeris-java

--archive, --sha256, and --out also support a minimal offline operation. Without official asset metadata, provenance explicitly identifies this as a user-supplied checksum verification rather than independently established upstream identity. --with-source in that mode needs --source-archive and --source-sha256; a URL or text file does not count as a source archive.

The payload layout is:

xeris-java/
  MANIFEST.TXT
  JAVA25/
    bin/java
    lib/...
    conf/...
    legal/...
    release
    XERIS-STAGING.json
    XERIS-SOURCES/OpenJDK25U-jdk-sources_25.0.4.1_1.tar.gz

Internal upstream symlinks and hard links become ordinary copies for FAT, including legal notices shared between modules. Escaping links, cycles, unsupported archive types, duplicate names, and case-colliding names are rejected. Every manifest entry stays beneath JAVA25/, and paths include room for the native installer's USB:/xeris-java/ prefix and terminating NUL.

If transferring an existing staged payload, copy both MANIFEST.TXT and the entire JAVA25 directory into the USB drive's xeris-java folder.

Install and verify on XerisOS#

Plug in the prepared USB drive. In XerisOS Terminal, run each command separately:

java where
java install
java verify

java where finds USB:/xeris-java/MANIFEST.TXT. Installation validates manifest paths before writing, copies files beneath /JAVA25/, and hashes the installed files. java verify uses the USB manifest to check the installed copy, so keep the USB drive attached until verification finishes. Proceed only when it reports every Java file matches the manifest. An error or cancellation must be resolved before treating the runtime as installed; it is not a package-wide rollback.

The installer refuses to replace files while an ABI application is running. This payload does not overwrite the shared files supplied by OBS or Chrome.

Launch commands#

These are the implemented command forms; guest execution remains subject to the smoke-test status above:

java -version
java -cp /APPS Hello
java -jar "/APPS/My App.jar"
java gui @/APPS/GRAPHICS.ARGS

Use absolute classpath and JAR paths. The JRE runs compiled classes or JARs; it does not provide javac. Compile a small test application on the development computer before copying it into /APPS.

Quotes preserve spaces, and empty quoted arguments are retained. Arguments are passed literally: shell variables, pipelines, and redirection are not expanded by this command. Up to 31 user arguments are accepted, within the terminal's existing input-length limit. The launcher copies arguments before reading the executable, so terminal edits cannot change an in-progress launch.

The gui prefix creates the native Wayland host window on the desktop CPU before Java runs. The prefix is removed before calling the JVM. This provides a window for a Wayland-enabled library; it does not add an X11 server for AWT. The JVM's @FILE argument form avoids the terminal's short input limit; the original probe in tools/java-smoke is prepared to validate argument files, threads, collection, JNI and temporary files in QEMU once the gate is enabled.

Java starts asynchronously. Java started means the loader handed it to the scheduler, not that the JVM or application completed successfully. Use dmesg and the QEMU serial log for JVM output and errors.

Game pointer input#

XerisOS now supports Wayland relative-pointer events, null-region pointer locks, and cursor hiding for a game camera. QEMU kernel 913ec passed an independent freestanding client: a 1200x680 surface displayed, six real mouse movements produced relative events, and no absolute-motion events occurred while locked. Unlock restored the cursor. Clicking the native X delivered the application's Wayland close event, and the probe exited successfully. These tests use no JVM or Minecraft files.

Frozen evidence is in build/java-qemu/pointer-913e-serial.log, pointer-913e-snapshot.json, and pointer-results.json. Successful process exit does not establish complete mapping reclamation or repeated application-session support; the separate same-boot seccomp limitation above remains.

Host tests also exercise focus loss, disconnect, object destruction, stale cursor serials, one-shot/persistent locks, and the actual PS/2/USB motion-decoder sections at screen edges. Run python tools/test_wayland_pointer.py with a host C compiler and NASM; tools/build_wayland_pointer_guest.ps1 builds the separate QEMU probe. The suite requires an x86-64 host to execute those assembly tests.

Explicit constraint regions and confinement requests currently remain inactive. Non-null client cursor surfaces restore the native cursor; custom cursor bitmap rendering is not implemented. This input milestone does not establish Java, LWJGL, or Minecraft compatibility by itself. The separate JVM/game results above establish startup and limited world interaction; camera integration, audio, networking, durable saves and sustained performance still need work.

Source and notices#

The staging tool preserves the JRE's complete upstream legal tree and records provenance in JAVA25/XERIS-STAGING.json. With --with-source, it retains an actual source archive for the exact runtime release under JAVA25/XERIS-SOURCES. When Adoptium's release metadata omits the source checksum, online staging reads the official .sha256.txt asset beside that pinned source URL; offline staging can use the explicitly supplied, independently verified checksum.

Keep these notices, provenance, and matching source with copies intended for distribution. Source retention is evidence for the release review, not a claim that every corresponding-source or other distribution obligation has been satisfied. The shared glibc/OBS runtime has its own notices and source requirements. Minecraft remains a separate application obtained under its own terms; this tool does not download or redistribute it.

Release gate for the reviewed runtime#

Both payload checkers now recognize the exact reviewed Temurin 25.0.4.1+1 package. They require every runtime and legal file to match hashes reconstructed from the verified official archive, the matching source archive to be retained, and provenance to identify those exact official artifacts. The release pin is tools/licenses/temurin25-25.0.4.1+1.json. Extra or modified files, missing notices/source, links, and mismatched provenance fail the gate. This is a reviewed-release allowance, not a blanket allowance for anything inside JAVA25.

For the development stage:

python tools/check_payload.py build/java-runtime/stage
python tools/gen_third_party_notices.py --payload build/java-runtime/stage --out build/java-runtime/TEMURIN_THIRD_PARTY_NOTICES.md --sbom build/java-runtime/temurin-sbom.cdx.json --strict

The generated notices include the exact packaged upstream legal texts, including the Classpath and Assembly exceptions and bundled-component notices. Identical texts are included once with all their retained paths listed. The strict check passed for 267 files: 266 inside JAVA25, plus the installer manifest. The older payload checker also passed. Fourteen focused host tests cover modifications, missing source/notices, unexpected binaries, invalid provenance, continued Minecraft rejection, and notice/SBOM output.

The default staging command may later select a newer Temurin release. That release will deliberately fail the existing release gate until its official metadata, archive checksums, materialized file hashes, matching source and legal texts have been reviewed and the pin updated. Use the pinned offline command above for this exact reviewed package. Gate success establishes package identity and retained evidence; it does not certify all final redistribution obligations or runtime compatibility.