jvman

A small Java version manager written in C11. One native executable, no linked third-party runtime, NTFS junctions for switching (no admin, no Developer Mode).

Version: 0.2.1. Primary target: Windows 10 1903+. Linux/macOS core is portable but the persistent-activation path differs (see below).

Install

Pick one:

Setup bundle (Windows) — download jvman-setup.exe, run interactively or silently. Handles PATH, JAVA_HOME, ARP entry, uninstall.
Single binary — drop jvman.exe anywhere on PATH. First jvman install / jvman use will self-persist JAVA_HOME and Path (opt-out below). No admin required.
Portable — jvman-setup.exe /PORTABLE /DIR=<abs-path> extracts the binary only; no registry, no PATH, no JAVA_HOME.

Quick start

jvman install 21# download Temurin 21, persist JAVA_HOME/PATH
jvman use 21# switch (also persists if not yet)
jvman list # what's registered
jvman current # what's active
java -version # new terminals: works immediately

Existing terminal opened before install? Refresh once:

jvman init powershell |Invoke-Expression# PowerShellfor/f "delims="%L in ('jvman init cmd') do @%L # CMD

Switching version (jvman use 17) does not rewrite PATH or JAVA_HOME. It rewrites one directory junction (<data-home>\current); every already- initialized shell picks the new JDK on the next process spawn. Java/Maven/ Gradle daemons must restart.

Commands

jvman install <major> [--name <n>] [--sha256 <hex>] [--source <src>] [--no-persist]
jvman install <name> --archive <file> [--sha256 <hex>] [--no-persist]
jvman add <name> <jdk-home> register an existing JDK (no copy)
jvman use <name> [--no-persist] switch active JDK
jvman activate [--replace-java-home] write HKCU/rc; idempotent
jvman deactivate reverse activate
jvman list | ls
jvman current
jvman which [name]
jvman remove <name> unregister; external JDKs stay on disk
jvman uninstall [<name>] alias of remove; no arg → run installer
jvman exec <name> [--] <cmd> [args...] run with selected JDK, no global change
jvman init [powershell|cmd|sh] emit shell-specific env script
jvman discover [--register] scan system for JDKs
jvman doctor validate JAVA_HOME/PATH/tools
jvman update [--check] [--version <v>] [--source <name>|--source-list]
self-update; --source picks a mirror (auto/github/gitee)
jvman source [--list|--reset|<name>|add <n> <tmpl>|remove <n>]
jvman language [--list|en|zh-CN]
jvman home print data-home

Aliases: ls=list, default=use.

Persistent activation

install and use automatically persist so new terminals and reopened IDEs resolve java without further setup.

Platform	What's written
Windows	`HKCU\Environment`: `JAVA_HOME=<data-home>\current`, `Path` prepended with `<data-home>\current\bin`. `WM_SETTINGCHANGE` broadcast. State recorded under `HKCU\Software\jvman\Installer` (shared with the installer).
POSIX	`~/.bashrc` and `~/.zshrc` gain a marker-fenced block that runs `eval "$(jvman init sh)"`. State recorded in `<data-home>/rc.state`.

Controls:

--no-persist on install/use — skip for that invocation.
JVMAN_NO_PERSIST=1 — skip globally.
jvman activate / jvman deactivate — explicit control; idempotent.
--replace-java-home — required if another program's JAVA_HOME is present; without it, activate refuses to overwrite.

Because JAVA_HOME points at the junction (not a version-specific dir), jvman use <ver> never touches the registry/rc after the first activate.

Data layout

%LOCALAPPDATA%\jvman on Windows, ${XDG_DATA_HOME:-~/.local/share}/jvman on Unix. Override with JVMAN_HOME.

<data-home>/
jdks/ JDKs owned by jvman (deleted on remove <name>)
versions/*.conf name → JAVA_HOME registrations
cache/ transient downloads + vendor metadata
staging/ in-progress installs
sources/*.conf custom Adoptium-compatible sources
source.conf selected remote source mode (absent = auto)
current junction/symlink to the active JDK
current.version active registration name
state.lock cross-process mutation lock
rc.state (POSIX) list of shell rc files touched by activate

Managed JDK deletion is confined to jdks/<name> and never follows links. External registrations (jvman add, discover --register) never delete the target on remove.

Sources

Built-in: tsinghua (TUNA Adoptium mirror), huawei (BiSheng), aliyun (Dragonwell), adoptium, foojay. auto (default) benchmarks all reachable sources — resolves metadata, then samples a bounded 64 KiB range from the final archive URL — and downloads once from the fastest.

jvman source auto # default
jvman source tsinghua # pin
jvman install 17--source adoptium # override once
jvman source add corp 'https://jdk.example.com/v3/{major}?os={os}&arch={arch}'

Custom source contract: Adoptium-compatible JSON, HTTPS only, must include SHA-256. Template placeholders: {major} (required), {os}, {arch}, {archive}. Credentials in URLs are rejected.

All remote archives are SHA-256 verified against source metadata; --sha256 adds a second pin. This detects corruption/mismatch but is not release signature verification.

Build

MSYS2 UCRT64 (this repo's tested toolchain):

$env:Path='C:\msys64\ucrt64\bin;'+$env:Pathmingw32-make.exe# produces jvman.exe and jvman-setup.exe

Portable Make / CMake:

make && make test&& make integration-test
make installer-test # Windows only
cmake -S . -B build && cmake --build build && ctest --test-dir build

Cross-compiling to Windows: setup stub and packer still build; the final jvman-setup.exe bundle is skipped because the packer can't run on the host.

Windows installer

jvman-setup.exe. Per-user by default (no UAC); all-users starts an elevated machine install through UAC. Manifest is asInvoker.

	Current user	All users
Program files	`%LOCALAPPDATA%\Programs\jvman`	`%ProgramFiles%\jvman`
Runtime data	`%LOCALAPPDATA%\jvman` (or `JVMAN_HOME`)	Per invoking user
Installer state	`HKCU\Software\jvman\Installer`	`HKLM\Software\jvman\Installer`

Switches:

jvman-setup.exe /S [/LANG=en|zh-CN] [/DIR=<abs>] [/USER_PATH|/SYSTEM_PATH] [/NO_PATH]
jvman-setup.exe /CONFIGURE_JAVA [/REPLACE_JAVA_HOME]
jvman-setup.exe /DISCOVER
jvman-setup.exe /PORTABLE /DIR=<abs>
jvman-setup.exe /UNINSTALL [/S] [/REMOVE_DATA [/REMOVE_JDKS]]
jvman-setup.exe /UNINSTALL /MACHINE [/S]
jvman-setup.exe /HELP

/USER_PATH (default): HKCU Path gains program dir + <data-home>\current\bin.
/SYSTEM_PATH (also /MACHINE_PATH, /ALL_USERS_PATH): HKLM Path gains program dir only. Never adds a user-writable JDK dir to the machine PATH.
/CONFIGURE_JAVA: sets HKCU JAVA_HOME=<data-home>\current. Refuses to overwrite an existing different value unless /REPLACE_JAVA_HOME.
/NO_PATH / /NO_CONFIGURE_JAVA: on repeat install, also restore values previously owned by this installer.

Installer state is shared with the CLI: jvman-setup.exe /UNINSTALL rolls back entries the CLI added via install/use/activate. jvman deactivate does the equivalent from the CLI side.

Uninstall scopes (current-user only; /MACHINE cannot combine with either):

default — program files and env entries owned by this installer.
/REMOVE_DATA — plus JVMAN_HOME contents except the top-level jdks/ dir.
/REMOVE_DATA /REMOVE_JDKS — plus jdks/. Never traverses junctions or symlinks; externally-registered JDKs are never deleted.

Shell caveat: no process can modify its parent shell's environment. Terminals open at install time keep their old env until fully closed and reopened (this includes tabs on an existing Windows Terminal process — close the app, not just the tab). If a machine PATH Java still shadows the user PATH, put jvman init <shell> in the shell startup file: $PROFILE.CurrentUserAllHosts for PowerShell; a per-user CMD AutoRun with doubled percent signs (%%L). Preserve any existing AutoRun content.

Update

jvman update --check # verify, don't download
jvman update # latest stable, auto-pick fastest mirror
jvman update --version 0.4.0 # explicit, no downgrade
jvman update --source gitee # pin the mirror (github|gitee|auto)
jvman update --source-list # list mirrors

Version metadata always comes from api.github.com/repos/standtrain/jvman/releases/latest — that's the single source of truth for the "latest" tag.
Asset download (SHA256SUMS + the platform binary) can come from any configured mirror. Built-in mirrors:
- github → https://github.com/standtrain/jvman/releases/download
- gitee → https://gitee.com/zzpdhc/jvman/releases/download (China-friendly)
--source auto (default) probes both mirrors' asset URL with a bounded 64 KiB range request, then downloads once from the fastest. Failed probes are announced; download is not retried on a different mirror if the picked one later fails — same policy as install.
The Gitee mirror must have a Release tagged exactlyv<major.minor.patch> with the same asset filenames and matching SHA-256 as the GitHub release, otherwise the SHA-256 verification step in update will reject the binary.
HTTPS only; metadata and binary size capped.
Binary must match the release's SHA256SUMSand the PE/ELF/Mach-O architecture must match the host.
Linux/macOS require curl ≥ 7.20.2 in a fixed root-owned system path — a PATH-injected curl is deliberately ignored. macOS 11's system curl qualifies.
Windows: replacement runs in a restricted helper after the current process exits. Must run from a non-elevated terminal (the user-writable temp dir can't be a privilege boundary). If admin access is required, use the installer or replace the binary manually.
Only the running CLI is replaced. JVMAN_HOME, JDKs, PATH, JAVA_HOME, shell profiles, and installer state are not touched.
The checksum is published in the same GitHub Release: it detects corruption and mismatched assets but is not an independent signature.

Discovery

Status values:

new — registerable JDK not yet registered
registered:<name> — this home is already registered under <name>
jre — runtime is not a complete JDK
invalid — cannot be registered safely

Scanned locations (bounded — never a full-disk scan):

JAVA_HOME, every PATH entry (quotes/env vars/links/Windows Java shims resolved to real targets)
Windows: HKLM+HKCU JavaSoft keys (32-bit and 64-bit views), Program Files, Program Files (x86), LocalAppData Programs
User: ~/.jdks, SDKMAN, Jabba
Linux: /usr/java, /usr/lib*/jvm
macOS: JavaVirtualMachines, fixed Homebrew roots

jvman discover --register revalidates and registers only new entries. Must have java, javac, and a valid release file ≤ 64 KiB with Java ≥ 8. Name conflicts get -2, -3, … suffixes. Idempotent; never selects a current. All auto-registered entries use external semantics.

Design references

Not copied — read for prior art:

SDKMAN — install/use/current, stable candidate layout
jEnv — registering existing JDKs, which, doctor
Jabba — small cross-platform manager, shell env output
HMCL — bounded vendor / JavaSoft discovery
nvm-windows — stable-path switching over PATH rewrites

Scope and non-goals

0.2.1 supports:

Auto/pinned source benchmarking across global, TUNA, Huawei, Aliyun, custom
Remote install by Java major version
Local discovery of common JDK vendors

Deferred:

Multi-vendor selection at install time
Managed JREs, EA/GraalVM channels
Semver range install syntax
.java-version project files
Independent signed release manifests

Non-goals of the CLI:

Never adds a user-writable JDK dir to the machine PATH.
Never runs unknown external binaries during discovery.
Never scans an entire disk.
Never modifies files outside JVMAN_HOME except HKCU env entries (Windows) or ~/.bashrc and ~/.zshrc marker blocks (POSIX) it explicitly owns.

Security notes

All remote fetches are HTTPS. Redirects only across HTTPS.
Every remote archive must supply and match a SHA-256.
Junctions/symlinks are never traversed during removal.
.env and <data-home>/sources/*.conf are private-mode files.
jvman.exe starts with SafeSearchMode enabled and rewrites Windows command resolution to skip the empty PATH element (i.e. the current directory) — guards against binary planting during jvman exec and extractor invocations.
Self-update refuses to run elevated on Windows.

jvman

简体中文

A small Java version manager written in C11. One native executable, no linked third-party runtime, NTFS junctions for switching (no admin, no Developer Mode).

Version: 0.2.1. Primary target: Windows 10 1903+. Linux/macOS core is portable but the persistent-activation path differs (see below).

Install

Pick one:

Setup bundle (Windows) — download jvman-setup.exe, run interactively or silently. Handles PATH, JAVA_HOME, ARP entry, uninstall.
Single binary — drop jvman.exe anywhere on PATH. First jvman install / jvman use will self-persist JAVA_HOME and Path (opt-out below). No admin required.
Portable — jvman-setup.exe /PORTABLE /DIR=<abs-path> extracts the binary only; no registry, no PATH, no JAVA_HOME.

Quick start

jvman install 21# download Temurin 21, persist JAVA_HOME/PATH
jvman use 21# switch (also persists if not yet)
jvman list # what's registered
jvman current # what's active
java -version # new terminals: works immediately

Existing terminal opened before install? Refresh once:

jvman init powershell |Invoke-Expression# PowerShellfor/f "delims="%L in ('jvman init cmd') do @%L # CMD

Switching version (jvman use 17) does not rewrite PATH or JAVA_HOME. It rewrites one directory junction (<data-home>\current); every already- initialized shell picks the new JDK on the next process spawn. Java/Maven/ Gradle daemons must restart.

Commands

jvman install <major> [--name <n>] [--sha256 <hex>] [--source <src>] [--no-persist]
jvman install <name> --archive <file> [--sha256 <hex>] [--no-persist]
jvman add <name> <jdk-home> register an existing JDK (no copy)
jvman use <name> [--no-persist] switch active JDK
jvman activate [--replace-java-home] write HKCU/rc; idempotent
jvman deactivate reverse activate
jvman list | ls
jvman current
jvman which [name]
jvman remove <name> unregister; external JDKs stay on disk
jvman uninstall [<name>] alias of remove; no arg → run installer
jvman exec <name> [--] <cmd> [args...] run with selected JDK, no global change
jvman init [powershell|cmd|sh] emit shell-specific env script
jvman discover [--register] scan system for JDKs
jvman doctor validate JAVA_HOME/PATH/tools
jvman update [--check] [--version <v>] [--source <name>|--source-list]
self-update; --source picks a mirror (auto/github/gitee)
jvman source [--list|--reset|<name>|add <n> <tmpl>|remove <n>]
jvman language [--list|en|zh-CN]
jvman home print data-home

Aliases: ls=list, default=use.

Persistent activation

install and use automatically persist so new terminals and reopened IDEs resolve java without further setup.

Platform	What's written
Windows	`HKCU\Environment`: `JAVA_HOME=<data-home>\current`, `Path` prepended with `<data-home>\current\bin`. `WM_SETTINGCHANGE` broadcast. State recorded under `HKCU\Software\jvman\Installer` (shared with the installer).
POSIX	`~/.bashrc` and `~/.zshrc` gain a marker-fenced block that runs `eval "$(jvman init sh)"`. State recorded in `<data-home>/rc.state`.

Controls:

--no-persist on install/use — skip for that invocation.
JVMAN_NO_PERSIST=1 — skip globally.
jvman activate / jvman deactivate — explicit control; idempotent.
--replace-java-home — required if another program's JAVA_HOME is present; without it, activate refuses to overwrite.

Because JAVA_HOME points at the junction (not a version-specific dir), jvman use <ver> never touches the registry/rc after the first activate.

Data layout

%LOCALAPPDATA%\jvman on Windows, ${XDG_DATA_HOME:-~/.local/share}/jvman on Unix. Override with JVMAN_HOME.

<data-home>/
jdks/ JDKs owned by jvman (deleted on remove <name>)
versions/*.conf name → JAVA_HOME registrations
cache/ transient downloads + vendor metadata
staging/ in-progress installs
sources/*.conf custom Adoptium-compatible sources
source.conf selected remote source mode (absent = auto)
current junction/symlink to the active JDK
current.version active registration name
state.lock cross-process mutation lock
rc.state (POSIX) list of shell rc files touched by activate

Managed JDK deletion is confined to jdks/<name> and never follows links. External registrations (jvman add, discover --register) never delete the target on remove.

Sources

Built-in: tsinghua (TUNA Adoptium mirror), huawei (BiSheng), aliyun (Dragonwell), adoptium, foojay. auto (default) benchmarks all reachable sources — resolves metadata, then samples a bounded 64 KiB range from the final archive URL — and downloads once from the fastest.

jvman source auto # default
jvman source tsinghua # pin
jvman install 17--source adoptium # override once
jvman source add corp 'https://jdk.example.com/v3/{major}?os={os}&arch={arch}'

Custom source contract: Adoptium-compatible JSON, HTTPS only, must include SHA-256. Template placeholders: {major} (required), {os}, {arch}, {archive}. Credentials in URLs are rejected.

All remote archives are SHA-256 verified against source metadata; --sha256 adds a second pin. This detects corruption/mismatch but is not release signature verification.

Build

MSYS2 UCRT64 (this repo's tested toolchain):

$env:Path='C:\msys64\ucrt64\bin;'+$env:Pathmingw32-make.exe# produces jvman.exe and jvman-setup.exe

Portable Make / CMake:

make && make test&& make integration-test
make installer-test # Windows only
cmake -S . -B build && cmake --build build && ctest --test-dir build

Cross-compiling to Windows: setup stub and packer still build; the final jvman-setup.exe bundle is skipped because the packer can't run on the host.

Windows installer

jvman-setup.exe. Per-user by default (no UAC); all-users starts an elevated machine install through UAC. Manifest is asInvoker.

	Current user	All users
Program files	`%LOCALAPPDATA%\Programs\jvman`	`%ProgramFiles%\jvman`
Runtime data	`%LOCALAPPDATA%\jvman` (or `JVMAN_HOME`)	Per invoking user
Installer state	`HKCU\Software\jvman\Installer`	`HKLM\Software\jvman\Installer`

Switches:

jvman-setup.exe /S [/LANG=en|zh-CN] [/DIR=<abs>] [/USER_PATH|/SYSTEM_PATH] [/NO_PATH]
jvman-setup.exe /CONFIGURE_JAVA [/REPLACE_JAVA_HOME]
jvman-setup.exe /DISCOVER
jvman-setup.exe /PORTABLE /DIR=<abs>
jvman-setup.exe /UNINSTALL [/S] [/REMOVE_DATA [/REMOVE_JDKS]]
jvman-setup.exe /UNINSTALL /MACHINE [/S]
jvman-setup.exe /HELP

/USER_PATH (default): HKCU Path gains program dir + <data-home>\current\bin.
/SYSTEM_PATH (also /MACHINE_PATH, /ALL_USERS_PATH): HKLM Path gains program dir only. Never adds a user-writable JDK dir to the machine PATH.
/CONFIGURE_JAVA: sets HKCU JAVA_HOME=<data-home>\current. Refuses to overwrite an existing different value unless /REPLACE_JAVA_HOME.
/NO_PATH / /NO_CONFIGURE_JAVA: on repeat install, also restore values previously owned by this installer.

Installer state is shared with the CLI: jvman-setup.exe /UNINSTALL rolls back entries the CLI added via install/use/activate. jvman deactivate does the equivalent from the CLI side.

Uninstall scopes (current-user only; /MACHINE cannot combine with either):

default — program files and env entries owned by this installer.
/REMOVE_DATA — plus JVMAN_HOME contents except the top-level jdks/ dir.
/REMOVE_DATA /REMOVE_JDKS — plus jdks/. Never traverses junctions or symlinks; externally-registered JDKs are never deleted.

Shell caveat: no process can modify its parent shell's environment. Terminals open at install time keep their old env until fully closed and reopened (this includes tabs on an existing Windows Terminal process — close the app, not just the tab). If a machine PATH Java still shadows the user PATH, put jvman init <shell> in the shell startup file: $PROFILE.CurrentUserAllHosts for PowerShell; a per-user CMD AutoRun with doubled percent signs (%%L). Preserve any existing AutoRun content.

Update

jvman update --check # verify, don't download
jvman update # latest stable, auto-pick fastest mirror
jvman update --version 0.4.0 # explicit, no downgrade
jvman update --source gitee # pin the mirror (github|gitee|auto)
jvman update --source-list # list mirrors

Version metadata always comes from api.github.com/repos/standtrain/jvman/releases/latest — that's the single source of truth for the "latest" tag.
Asset download (SHA256SUMS + the platform binary) can come from any configured mirror. Built-in mirrors:
- github → https://github.com/standtrain/jvman/releases/download
- gitee → https://gitee.com/zzpdhc/jvman/releases/download (China-friendly)
--source auto (default) probes both mirrors' asset URL with a bounded 64 KiB range request, then downloads once from the fastest. Failed probes are announced; download is not retried on a different mirror if the picked one later fails — same policy as install.
The Gitee mirror must have a Release tagged exactlyv<major.minor.patch> with the same asset filenames and matching SHA-256 as the GitHub release, otherwise the SHA-256 verification step in update will reject the binary.
HTTPS only; metadata and binary size capped.
Binary must match the release's SHA256SUMSand the PE/ELF/Mach-O architecture must match the host.
Linux/macOS require curl ≥ 7.20.2 in a fixed root-owned system path — a PATH-injected curl is deliberately ignored. macOS 11's system curl qualifies.
Windows: replacement runs in a restricted helper after the current process exits. Must run from a non-elevated terminal (the user-writable temp dir can't be a privilege boundary). If admin access is required, use the installer or replace the binary manually.
Only the running CLI is replaced. JVMAN_HOME, JDKs, PATH, JAVA_HOME, shell profiles, and installer state are not touched.
The checksum is published in the same GitHub Release: it detects corruption and mismatched assets but is not an independent signature.

Discovery

Status values:

new — registerable JDK not yet registered
registered:<name> — this home is already registered under <name>
jre — runtime is not a complete JDK
invalid — cannot be registered safely

Scanned locations (bounded — never a full-disk scan):

JAVA_HOME, every PATH entry (quotes/env vars/links/Windows Java shims resolved to real targets)
Windows: HKLM+HKCU JavaSoft keys (32-bit and 64-bit views), Program Files, Program Files (x86), LocalAppData Programs
User: ~/.jdks, SDKMAN, Jabba
Linux: /usr/java, /usr/lib*/jvm
macOS: JavaVirtualMachines, fixed Homebrew roots

jvman discover --register revalidates and registers only new entries. Must have java, javac, and a valid release file ≤ 64 KiB with Java ≥ 8. Name conflicts get -2, -3, … suffixes. Idempotent; never selects a current. All auto-registered entries use external semantics.

Design references

Not copied — read for prior art:

SDKMAN — install/use/current, stable candidate layout
jEnv — registering existing JDKs, which, doctor
Jabba — small cross-platform manager, shell env output
HMCL — bounded vendor / JavaSoft discovery
nvm-windows — stable-path switching over PATH rewrites

Scope and non-goals

0.2.1 supports:

Auto/pinned source benchmarking across global, TUNA, Huawei, Aliyun, custom
Remote install by Java major version
Local discovery of common JDK vendors

Deferred:

Multi-vendor selection at install time
Managed JREs, EA/GraalVM channels
Semver range install syntax
.java-version project files
Independent signed release manifests

Non-goals of the CLI:

Never adds a user-writable JDK dir to the machine PATH.
Never runs unknown external binaries during discovery.
Never scans an entire disk.
Never modifies files outside JVMAN_HOME except HKCU env entries (Windows) or ~/.bashrc and ~/.zshrc marker blocks (POSIX) it explicitly owns.

Security notes

All remote fetches are HTTPS. Redirects only across HTTPS.
Every remote archive must supply and match a SHA-256.
Junctions/symlinks are never traversed during removal.
.env and <data-home>/sources/*.conf are private-mode files.
jvman.exe starts with SafeSearchMode enabled and rewrites Windows command resolution to skip the empty PATH element (i.e. the current directory) — guards against binary planting during jvman exec and extractor invocations.
Self-update refuses to run elevated on Windows.

jvman

简体中文

A small Java version manager written in C11. One native executable, no linked third-party runtime, NTFS junctions for switching (no admin, no Developer Mode).

Version: 0.2.1. Primary target: Windows 10 1903+. Linux/macOS core is portable but the persistent-activation path differs (see below).

Install

Pick one:

Setup bundle (Windows) — download jvman-setup.exe, run interactively or silently. Handles PATH, JAVA_HOME, ARP entry, uninstall.
Single binary — drop jvman.exe anywhere on PATH. First jvman install / jvman use will self-persist JAVA_HOME and Path (opt-out below). No admin required.
Portable — jvman-setup.exe /PORTABLE /DIR=<abs-path> extracts the binary only; no registry, no PATH, no JAVA_HOME.

Quick start

jvman install 21# download Temurin 21, persist JAVA_HOME/PATH
jvman use 21# switch (also persists if not yet)
jvman list # what's registered
jvman current # what's active
java -version # new terminals: works immediately

Existing terminal opened before install? Refresh once:

jvman init powershell |Invoke-Expression# PowerShellfor/f "delims="%L in ('jvman init cmd') do @%L # CMD

Switching version (jvman use 17) does not rewrite PATH or JAVA_HOME. It rewrites one directory junction (<data-home>\current); every already- initialized shell picks the new JDK on the next process spawn. Java/Maven/ Gradle daemons must restart.

Commands

jvman install <major> [--name <n>] [--sha256 <hex>] [--source <src>] [--no-persist]
jvman install <name> --archive <file> [--sha256 <hex>] [--no-persist]
jvman add <name> <jdk-home> register an existing JDK (no copy)
jvman use <name> [--no-persist] switch active JDK
jvman activate [--replace-java-home] write HKCU/rc; idempotent
jvman deactivate reverse activate
jvman list | ls
jvman current
jvman which [name]
jvman remove <name> unregister; external JDKs stay on disk
jvman uninstall [<name>] alias of remove; no arg → run installer
jvman exec <name> [--] <cmd> [args...] run with selected JDK, no global change
jvman init [powershell|cmd|sh] emit shell-specific env script
jvman discover [--register] scan system for JDKs
jvman doctor validate JAVA_HOME/PATH/tools
jvman update [--check] [--version <v>] [--source <name>|--source-list]
self-update; --source picks a mirror (auto/github/gitee)
jvman source [--list|--reset|<name>|add <n> <tmpl>|remove <n>]
jvman language [--list|en|zh-CN]
jvman home print data-home

Aliases: ls=list, default=use.

Persistent activation

install and use automatically persist so new terminals and reopened IDEs resolve java without further setup.

Platform	What's written
Windows	`HKCU\Environment`: `JAVA_HOME=<data-home>\current`, `Path` prepended with `<data-home>\current\bin`. `WM_SETTINGCHANGE` broadcast. State recorded under `HKCU\Software\jvman\Installer` (shared with the installer).
POSIX	`~/.bashrc` and `~/.zshrc` gain a marker-fenced block that runs `eval "$(jvman init sh)"`. State recorded in `<data-home>/rc.state`.

Controls:

--no-persist on install/use — skip for that invocation.
JVMAN_NO_PERSIST=1 — skip globally.
jvman activate / jvman deactivate — explicit control; idempotent.
--replace-java-home — required if another program's JAVA_HOME is present; without it, activate refuses to overwrite.

Because JAVA_HOME points at the junction (not a version-specific dir), jvman use <ver> never touches the registry/rc after the first activate.

Data layout

%LOCALAPPDATA%\jvman on Windows, ${XDG_DATA_HOME:-~/.local/share}/jvman on Unix. Override with JVMAN_HOME.

<data-home>/
jdks/ JDKs owned by jvman (deleted on remove <name>)
versions/*.conf name → JAVA_HOME registrations
cache/ transient downloads + vendor metadata
staging/ in-progress installs
sources/*.conf custom Adoptium-compatible sources
source.conf selected remote source mode (absent = auto)
current junction/symlink to the active JDK
current.version active registration name
state.lock cross-process mutation lock
rc.state (POSIX) list of shell rc files touched by activate

Managed JDK deletion is confined to jdks/<name> and never follows links. External registrations (jvman add, discover --register) never delete the target on remove.

Sources

Built-in: tsinghua (TUNA Adoptium mirror), huawei (BiSheng), aliyun (Dragonwell), adoptium, foojay. auto (default) benchmarks all reachable sources — resolves metadata, then samples a bounded 64 KiB range from the final archive URL — and downloads once from the fastest.

jvman source auto # default
jvman source tsinghua # pin
jvman install 17--source adoptium # override once
jvman source add corp 'https://jdk.example.com/v3/{major}?os={os}&arch={arch}'

Custom source contract: Adoptium-compatible JSON, HTTPS only, must include SHA-256. Template placeholders: {major} (required), {os}, {arch}, {archive}. Credentials in URLs are rejected.

All remote archives are SHA-256 verified against source metadata; --sha256 adds a second pin. This detects corruption/mismatch but is not release signature verification.

Build

MSYS2 UCRT64 (this repo's tested toolchain):

$env:Path='C:\msys64\ucrt64\bin;'+$env:Pathmingw32-make.exe# produces jvman.exe and jvman-setup.exe

Portable Make / CMake:

make && make test&& make integration-test
make installer-test # Windows only
cmake -S . -B build && cmake --build build && ctest --test-dir build

Cross-compiling to Windows: setup stub and packer still build; the final jvman-setup.exe bundle is skipped because the packer can't run on the host.

Windows installer

jvman-setup.exe. Per-user by default (no UAC); all-users starts an elevated machine install through UAC. Manifest is asInvoker.

	Current user	All users
Program files	`%LOCALAPPDATA%\Programs\jvman`	`%ProgramFiles%\jvman`
Runtime data	`%LOCALAPPDATA%\jvman` (or `JVMAN_HOME`)	Per invoking user
Installer state	`HKCU\Software\jvman\Installer`	`HKLM\Software\jvman\Installer`

Switches:

jvman-setup.exe /S [/LANG=en|zh-CN] [/DIR=<abs>] [/USER_PATH|/SYSTEM_PATH] [/NO_PATH]
jvman-setup.exe /CONFIGURE_JAVA [/REPLACE_JAVA_HOME]
jvman-setup.exe /DISCOVER
jvman-setup.exe /PORTABLE /DIR=<abs>
jvman-setup.exe /UNINSTALL [/S] [/REMOVE_DATA [/REMOVE_JDKS]]
jvman-setup.exe /UNINSTALL /MACHINE [/S]
jvman-setup.exe /HELP

/USER_PATH (default): HKCU Path gains program dir + <data-home>\current\bin.
/SYSTEM_PATH (also /MACHINE_PATH, /ALL_USERS_PATH): HKLM Path gains program dir only. Never adds a user-writable JDK dir to the machine PATH.
/CONFIGURE_JAVA: sets HKCU JAVA_HOME=<data-home>\current. Refuses to overwrite an existing different value unless /REPLACE_JAVA_HOME.
/NO_PATH / /NO_CONFIGURE_JAVA: on repeat install, also restore values previously owned by this installer.

Installer state is shared with the CLI: jvman-setup.exe /UNINSTALL rolls back entries the CLI added via install/use/activate. jvman deactivate does the equivalent from the CLI side.

Uninstall scopes (current-user only; /MACHINE cannot combine with either):

default — program files and env entries owned by this installer.
/REMOVE_DATA — plus JVMAN_HOME contents except the top-level jdks/ dir.
/REMOVE_DATA /REMOVE_JDKS — plus jdks/. Never traverses junctions or symlinks; externally-registered JDKs are never deleted.

Shell caveat: no process can modify its parent shell's environment. Terminals open at install time keep their old env until fully closed and reopened (this includes tabs on an existing Windows Terminal process — close the app, not just the tab). If a machine PATH Java still shadows the user PATH, put jvman init <shell> in the shell startup file: $PROFILE.CurrentUserAllHosts for PowerShell; a per-user CMD AutoRun with doubled percent signs (%%L). Preserve any existing AutoRun content.

Update

jvman update --check # verify, don't download
jvman update # latest stable, auto-pick fastest mirror
jvman update --version 0.4.0 # explicit, no downgrade
jvman update --source gitee # pin the mirror (github|gitee|auto)
jvman update --source-list # list mirrors

Version metadata always comes from api.github.com/repos/standtrain/jvman/releases/latest — that's the single source of truth for the "latest" tag.
Asset download (SHA256SUMS + the platform binary) can come from any configured mirror. Built-in mirrors:
- github → https://github.com/standtrain/jvman/releases/download
- gitee → https://gitee.com/zzpdhc/jvman/releases/download (China-friendly)
--source auto (default) probes both mirrors' asset URL with a bounded 64 KiB range request, then downloads once from the fastest. Failed probes are announced; download is not retried on a different mirror if the picked one later fails — same policy as install.
The Gitee mirror must have a Release tagged exactlyv<major.minor.patch> with the same asset filenames and matching SHA-256 as the GitHub release, otherwise the SHA-256 verification step in update will reject the binary.
HTTPS only; metadata and binary size capped.
Binary must match the release's SHA256SUMSand the PE/ELF/Mach-O architecture must match the host.
Linux/macOS require curl ≥ 7.20.2 in a fixed root-owned system path — a PATH-injected curl is deliberately ignored. macOS 11's system curl qualifies.
Windows: replacement runs in a restricted helper after the current process exits. Must run from a non-elevated terminal (the user-writable temp dir can't be a privilege boundary). If admin access is required, use the installer or replace the binary manually.
Only the running CLI is replaced. JVMAN_HOME, JDKs, PATH, JAVA_HOME, shell profiles, and installer state are not touched.
The checksum is published in the same GitHub Release: it detects corruption and mismatched assets but is not an independent signature.

Discovery

Status values:

new — registerable JDK not yet registered
registered:<name> — this home is already registered under <name>
jre — runtime is not a complete JDK
invalid — cannot be registered safely

Scanned locations (bounded — never a full-disk scan):

JAVA_HOME, every PATH entry (quotes/env vars/links/Windows Java shims resolved to real targets)
Windows: HKLM+HKCU JavaSoft keys (32-bit and 64-bit views), Program Files, Program Files (x86), LocalAppData Programs
User: ~/.jdks, SDKMAN, Jabba
Linux: /usr/java, /usr/lib*/jvm
macOS: JavaVirtualMachines, fixed Homebrew roots

jvman discover --register revalidates and registers only new entries. Must have java, javac, and a valid release file ≤ 64 KiB with Java ≥ 8. Name conflicts get -2, -3, … suffixes. Idempotent; never selects a current. All auto-registered entries use external semantics.

Design references

Not copied — read for prior art:

SDKMAN — install/use/current, stable candidate layout
jEnv — registering existing JDKs, which, doctor
Jabba — small cross-platform manager, shell env output
HMCL — bounded vendor / JavaSoft discovery
nvm-windows — stable-path switching over PATH rewrites

Scope and non-goals

0.2.1 supports:

Auto/pinned source benchmarking across global, TUNA, Huawei, Aliyun, custom
Remote install by Java major version
Local discovery of common JDK vendors

Deferred:

Multi-vendor selection at install time
Managed JREs, EA/GraalVM channels
Semver range install syntax
.java-version project files
Independent signed release manifests

Non-goals of the CLI:

Never adds a user-writable JDK dir to the machine PATH.
Never runs unknown external binaries during discovery.
Never scans an entire disk.
Never modifies files outside JVMAN_HOME except HKCU env entries (Windows) or ~/.bashrc and ~/.zshrc marker blocks (POSIX) it explicitly owns.

Security notes

All remote fetches are HTTPS. Redirects only across HTTPS.
Every remote archive must supply and match a SHA-256.
Junctions/symlinks are never traversed during removal.
.env and <data-home>/sources/*.conf are private-mode files.
jvman.exe starts with SafeSearchMode enabled and rewrites Windows command resolution to skip the empty PATH element (i.e. the current directory) — guards against binary planting during jvman exec and extractor invocations.
Self-update refuses to run elevated on Windows.

jvman

简体中文

A small Java version manager written in C11. One native executable, no linked third-party runtime, NTFS junctions for switching (no admin, no Developer Mode).

Version: 0.2.1. Primary target: Windows 10 1903+. Linux/macOS core is portable but the persistent-activation path differs (see below).

Install

Pick one:

Setup bundle (Windows) — download jvman-setup.exe, run interactively or silently. Handles PATH, JAVA_HOME, ARP entry, uninstall.
Single binary — drop jvman.exe anywhere on PATH. First jvman install / jvman use will self-persist JAVA_HOME and Path (opt-out below). No admin required.
Portable — jvman-setup.exe /PORTABLE /DIR=<abs-path> extracts the binary only; no registry, no PATH, no JAVA_HOME.

Quick start

jvman install 21# download Temurin 21, persist JAVA_HOME/PATH
jvman use 21# switch (also persists if not yet)
jvman list # what's registered
jvman current # what's active
java -version # new terminals: works immediately

Existing terminal opened before install? Refresh once:

jvman init powershell |Invoke-Expression# PowerShellfor/f "delims="%L in ('jvman init cmd') do @%L # CMD

Switching version (jvman use 17) does not rewrite PATH or JAVA_HOME. It rewrites one directory junction (<data-home>\current); every already- initialized shell picks the new JDK on the next process spawn. Java/Maven/ Gradle daemons must restart.

Commands

jvman install <major> [--name <n>] [--sha256 <hex>] [--source <src>] [--no-persist]
jvman install <name> --archive <file> [--sha256 <hex>] [--no-persist]
jvman add <name> <jdk-home> register an existing JDK (no copy)
jvman use <name> [--no-persist] switch active JDK
jvman activate [--replace-java-home] write HKCU/rc; idempotent
jvman deactivate reverse activate
jvman list | ls
jvman current
jvman which [name]
jvman remove <name> unregister; external JDKs stay on disk
jvman uninstall [<name>] alias of remove; no arg → run installer
jvman exec <name> [--] <cmd> [args...] run with selected JDK, no global change
jvman init [powershell|cmd|sh] emit shell-specific env script
jvman discover [--register] scan system for JDKs
jvman doctor validate JAVA_HOME/PATH/tools
jvman update [--check] [--version <v>] [--source <name>|--source-list]
self-update; --source picks a mirror (auto/github/gitee)
jvman source [--list|--reset|<name>|add <n> <tmpl>|remove <n>]
jvman language [--list|en|zh-CN]
jvman home print data-home

Aliases: ls=list, default=use.

Persistent activation

install and use automatically persist so new terminals and reopened IDEs resolve java without further setup.

Platform	What's written
Windows	`HKCU\Environment`: `JAVA_HOME=<data-home>\current`, `Path` prepended with `<data-home>\current\bin`. `WM_SETTINGCHANGE` broadcast. State recorded under `HKCU\Software\jvman\Installer` (shared with the installer).
POSIX	`~/.bashrc` and `~/.zshrc` gain a marker-fenced block that runs `eval "$(jvman init sh)"`. State recorded in `<data-home>/rc.state`.

Controls:

--no-persist on install/use — skip for that invocation.
JVMAN_NO_PERSIST=1 — skip globally.
jvman activate / jvman deactivate — explicit control; idempotent.
--replace-java-home — required if another program's JAVA_HOME is present; without it, activate refuses to overwrite.

Because JAVA_HOME points at the junction (not a version-specific dir), jvman use <ver> never touches the registry/rc after the first activate.

Data layout

%LOCALAPPDATA%\jvman on Windows, ${XDG_DATA_HOME:-~/.local/share}/jvman on Unix. Override with JVMAN_HOME.

<data-home>/
jdks/ JDKs owned by jvman (deleted on remove <name>)
versions/*.conf name → JAVA_HOME registrations
cache/ transient downloads + vendor metadata
staging/ in-progress installs
sources/*.conf custom Adoptium-compatible sources
source.conf selected remote source mode (absent = auto)
current junction/symlink to the active JDK
current.version active registration name
state.lock cross-process mutation lock
rc.state (POSIX) list of shell rc files touched by activate

Managed JDK deletion is confined to jdks/<name> and never follows links. External registrations (jvman add, discover --register) never delete the target on remove.

Sources

Built-in: tsinghua (TUNA Adoptium mirror), huawei (BiSheng), aliyun (Dragonwell), adoptium, foojay. auto (default) benchmarks all reachable sources — resolves metadata, then samples a bounded 64 KiB range from the final archive URL — and downloads once from the fastest.

jvman source auto # default
jvman source tsinghua # pin
jvman install 17--source adoptium # override once
jvman source add corp 'https://jdk.example.com/v3/{major}?os={os}&arch={arch}'

Custom source contract: Adoptium-compatible JSON, HTTPS only, must include SHA-256. Template placeholders: {major} (required), {os}, {arch}, {archive}. Credentials in URLs are rejected.

All remote archives are SHA-256 verified against source metadata; --sha256 adds a second pin. This detects corruption/mismatch but is not release signature verification.

Build

MSYS2 UCRT64 (this repo's tested toolchain):

$env:Path='C:\msys64\ucrt64\bin;'+$env:Pathmingw32-make.exe# produces jvman.exe and jvman-setup.exe

Portable Make / CMake:

make && make test&& make integration-test
make installer-test # Windows only
cmake -S . -B build && cmake --build build && ctest --test-dir build

Cross-compiling to Windows: setup stub and packer still build; the final jvman-setup.exe bundle is skipped because the packer can't run on the host.

Windows installer

jvman-setup.exe. Per-user by default (no UAC); all-users starts an elevated machine install through UAC. Manifest is asInvoker.

	Current user	All users
Program files	`%LOCALAPPDATA%\Programs\jvman`	`%ProgramFiles%\jvman`
Runtime data	`%LOCALAPPDATA%\jvman` (or `JVMAN_HOME`)	Per invoking user
Installer state	`HKCU\Software\jvman\Installer`	`HKLM\Software\jvman\Installer`

Switches:

jvman-setup.exe /S [/LANG=en|zh-CN] [/DIR=<abs>] [/USER_PATH|/SYSTEM_PATH] [/NO_PATH]
jvman-setup.exe /CONFIGURE_JAVA [/REPLACE_JAVA_HOME]
jvman-setup.exe /DISCOVER
jvman-setup.exe /PORTABLE /DIR=<abs>
jvman-setup.exe /UNINSTALL [/S] [/REMOVE_DATA [/REMOVE_JDKS]]
jvman-setup.exe /UNINSTALL /MACHINE [/S]
jvman-setup.exe /HELP

/USER_PATH (default): HKCU Path gains program dir + <data-home>\current\bin.
/SYSTEM_PATH (also /MACHINE_PATH, /ALL_USERS_PATH): HKLM Path gains program dir only. Never adds a user-writable JDK dir to the machine PATH.
/CONFIGURE_JAVA: sets HKCU JAVA_HOME=<data-home>\current. Refuses to overwrite an existing different value unless /REPLACE_JAVA_HOME.
/NO_PATH / /NO_CONFIGURE_JAVA: on repeat install, also restore values previously owned by this installer.

Installer state is shared with the CLI: jvman-setup.exe /UNINSTALL rolls back entries the CLI added via install/use/activate. jvman deactivate does the equivalent from the CLI side.

Uninstall scopes (current-user only; /MACHINE cannot combine with either):

default — program files and env entries owned by this installer.
/REMOVE_DATA — plus JVMAN_HOME contents except the top-level jdks/ dir.
/REMOVE_DATA /REMOVE_JDKS — plus jdks/. Never traverses junctions or symlinks; externally-registered JDKs are never deleted.

Shell caveat: no process can modify its parent shell's environment. Terminals open at install time keep their old env until fully closed and reopened (this includes tabs on an existing Windows Terminal process — close the app, not just the tab). If a machine PATH Java still shadows the user PATH, put jvman init <shell> in the shell startup file: $PROFILE.CurrentUserAllHosts for PowerShell; a per-user CMD AutoRun with doubled percent signs (%%L). Preserve any existing AutoRun content.

Update

jvman update --check # verify, don't download
jvman update # latest stable, auto-pick fastest mirror
jvman update --version 0.4.0 # explicit, no downgrade
jvman update --source gitee # pin the mirror (github|gitee|auto)
jvman update --source-list # list mirrors

Version metadata always comes from api.github.com/repos/standtrain/jvman/releases/latest — that's the single source of truth for the "latest" tag.
Asset download (SHA256SUMS + the platform binary) can come from any configured mirror. Built-in mirrors:
- github → https://github.com/standtrain/jvman/releases/download
- gitee → https://gitee.com/zzpdhc/jvman/releases/download (China-friendly)
--source auto (default) probes both mirrors' asset URL with a bounded 64 KiB range request, then downloads once from the fastest. Failed probes are announced; download is not retried on a different mirror if the picked one later fails — same policy as install.
The Gitee mirror must have a Release tagged exactlyv<major.minor.patch> with the same asset filenames and matching SHA-256 as the GitHub release, otherwise the SHA-256 verification step in update will reject the binary.
HTTPS only; metadata and binary size capped.
Binary must match the release's SHA256SUMSand the PE/ELF/Mach-O architecture must match the host.
Linux/macOS require curl ≥ 7.20.2 in a fixed root-owned system path — a PATH-injected curl is deliberately ignored. macOS 11's system curl qualifies.
Windows: replacement runs in a restricted helper after the current process exits. Must run from a non-elevated terminal (the user-writable temp dir can't be a privilege boundary). If admin access is required, use the installer or replace the binary manually.
Only the running CLI is replaced. JVMAN_HOME, JDKs, PATH, JAVA_HOME, shell profiles, and installer state are not touched.
The checksum is published in the same GitHub Release: it detects corruption and mismatched assets but is not an independent signature.

Discovery

Status values:

new — registerable JDK not yet registered
registered:<name> — this home is already registered under <name>
jre — runtime is not a complete JDK
invalid — cannot be registered safely

Scanned locations (bounded — never a full-disk scan):

JAVA_HOME, every PATH entry (quotes/env vars/links/Windows Java shims resolved to real targets)
Windows: HKLM+HKCU JavaSoft keys (32-bit and 64-bit views), Program Files, Program Files (x86), LocalAppData Programs
User: ~/.jdks, SDKMAN, Jabba
Linux: /usr/java, /usr/lib*/jvm
macOS: JavaVirtualMachines, fixed Homebrew roots

jvman discover --register revalidates and registers only new entries. Must have java, javac, and a valid release file ≤ 64 KiB with Java ≥ 8. Name conflicts get -2, -3, … suffixes. Idempotent; never selects a current. All auto-registered entries use external semantics.

Design references

Not copied — read for prior art:

SDKMAN — install/use/current, stable candidate layout
jEnv — registering existing JDKs, which, doctor
Jabba — small cross-platform manager, shell env output
HMCL — bounded vendor / JavaSoft discovery
nvm-windows — stable-path switching over PATH rewrites

Scope and non-goals

0.2.1 supports:

Auto/pinned source benchmarking across global, TUNA, Huawei, Aliyun, custom
Remote install by Java major version
Local discovery of common JDK vendors

Deferred:

Multi-vendor selection at install time
Managed JREs, EA/GraalVM channels
Semver range install syntax
.java-version project files
Independent signed release manifests

Non-goals of the CLI:

Never adds a user-writable JDK dir to the machine PATH.
Never runs unknown external binaries during discovery.
Never scans an entire disk.
Never modifies files outside JVMAN_HOME except HKCU env entries (Windows) or ~/.bashrc and ~/.zshrc marker blocks (POSIX) it explicitly owns.

Security notes

All remote fetches are HTTPS. Redirects only across HTTPS.
Every remote archive must supply and match a SHA-256.
Junctions/symlinks are never traversed during removal.
.env and <data-home>/sources/*.conf are private-mode files.
jvman.exe starts with SafeSearchMode enabled and rewrites Windows command resolution to skip the empty PATH element (i.e. the current directory) — guards against binary planting during jvman exec and extractor invocations.
Self-update refuses to run elevated on Windows.

jvman

简体中文

A small Java version manager written in C11. One native executable, no linked third-party runtime, NTFS junctions for switching (no admin, no Developer Mode).

Version: 0.2.1. Primary target: Windows 10 1903+. Linux/macOS core is portable but the persistent-activation path differs (see below).

Install

Pick one:

Setup bundle (Windows) — download jvman-setup.exe, run interactively or silently. Handles PATH, JAVA_HOME, ARP entry, uninstall.
Single binary — drop jvman.exe anywhere on PATH. First jvman install / jvman use will self-persist JAVA_HOME and Path (opt-out below). No admin required.
Portable — jvman-setup.exe /PORTABLE /DIR=<abs-path> extracts the binary only; no registry, no PATH, no JAVA_HOME.

Quick start

jvman install 21# download Temurin 21, persist JAVA_HOME/PATH
jvman use 21# switch (also persists if not yet)
jvman list # what's registered
jvman current # what's active
java -version # new terminals: works immediately

Existing terminal opened before install? Refresh once:

jvman init powershell |Invoke-Expression# PowerShellfor/f "delims="%L in ('jvman init cmd') do @%L # CMD

Switching version (jvman use 17) does not rewrite PATH or JAVA_HOME. It rewrites one directory junction (<data-home>\current); every already- initialized shell picks the new JDK on the next process spawn. Java/Maven/ Gradle daemons must restart.

Commands

jvman install <major> [--name <n>] [--sha256 <hex>] [--source <src>] [--no-persist]
jvman install <name> --archive <file> [--sha256 <hex>] [--no-persist]
jvman add <name> <jdk-home> register an existing JDK (no copy)
jvman use <name> [--no-persist] switch active JDK
jvman activate [--replace-java-home] write HKCU/rc; idempotent
jvman deactivate reverse activate
jvman list | ls
jvman current
jvman which [name]
jvman remove <name> unregister; external JDKs stay on disk
jvman uninstall [<name>] alias of remove; no arg → run installer
jvman exec <name> [--] <cmd> [args...] run with selected JDK, no global change
jvman init [powershell|cmd|sh] emit shell-specific env script
jvman discover [--register] scan system for JDKs
jvman doctor validate JAVA_HOME/PATH/tools
jvman update [--check] [--version <v>] [--source <name>|--source-list]
self-update; --source picks a mirror (auto/github/gitee)
jvman source [--list|--reset|<name>|add <n> <tmpl>|remove <n>]
jvman language [--list|en|zh-CN]
jvman home print data-home

Aliases: ls=list, default=use.

Persistent activation

install and use automatically persist so new terminals and reopened IDEs resolve java without further setup.

Platform	What's written
Windows	`HKCU\Environment`: `JAVA_HOME=<data-home>\current`, `Path` prepended with `<data-home>\current\bin`. `WM_SETTINGCHANGE` broadcast. State recorded under `HKCU\Software\jvman\Installer` (shared with the installer).
POSIX	`~/.bashrc` and `~/.zshrc` gain a marker-fenced block that runs `eval "$(jvman init sh)"`. State recorded in `<data-home>/rc.state`.

Controls:

--no-persist on install/use — skip for that invocation.
JVMAN_NO_PERSIST=1 — skip globally.
jvman activate / jvman deactivate — explicit control; idempotent.
--replace-java-home — required if another program's JAVA_HOME is present; without it, activate refuses to overwrite.

Because JAVA_HOME points at the junction (not a version-specific dir), jvman use <ver> never touches the registry/rc after the first activate.

Data layout

%LOCALAPPDATA%\jvman on Windows, ${XDG_DATA_HOME:-~/.local/share}/jvman on Unix. Override with JVMAN_HOME.

<data-home>/
jdks/ JDKs owned by jvman (deleted on remove <name>)
versions/*.conf name → JAVA_HOME registrations
cache/ transient downloads + vendor metadata
staging/ in-progress installs
sources/*.conf custom Adoptium-compatible sources
source.conf selected remote source mode (absent = auto)
current junction/symlink to the active JDK
current.version active registration name
state.lock cross-process mutation lock
rc.state (POSIX) list of shell rc files touched by activate

Managed JDK deletion is confined to jdks/<name> and never follows links. External registrations (jvman add, discover --register) never delete the target on remove.

Sources

Built-in: tsinghua (TUNA Adoptium mirror), huawei (BiSheng), aliyun (Dragonwell), adoptium, foojay. auto (default) benchmarks all reachable sources — resolves metadata, then samples a bounded 64 KiB range from the final archive URL — and downloads once from the fastest.

jvman source auto # default
jvman source tsinghua # pin
jvman install 17--source adoptium # override once
jvman source add corp 'https://jdk.example.com/v3/{major}?os={os}&arch={arch}'

Custom source contract: Adoptium-compatible JSON, HTTPS only, must include SHA-256. Template placeholders: {major} (required), {os}, {arch}, {archive}. Credentials in URLs are rejected.

All remote archives are SHA-256 verified against source metadata; --sha256 adds a second pin. This detects corruption/mismatch but is not release signature verification.

Build

MSYS2 UCRT64 (this repo's tested toolchain):

$env:Path='C:\msys64\ucrt64\bin;'+$env:Pathmingw32-make.exe# produces jvman.exe and jvman-setup.exe

Portable Make / CMake:

make && make test&& make integration-test
make installer-test # Windows only
cmake -S . -B build && cmake --build build && ctest --test-dir build

Cross-compiling to Windows: setup stub and packer still build; the final jvman-setup.exe bundle is skipped because the packer can't run on the host.

Windows installer

jvman-setup.exe. Per-user by default (no UAC); all-users starts an elevated machine install through UAC. Manifest is asInvoker.

	Current user	All users
Program files	`%LOCALAPPDATA%\Programs\jvman`	`%ProgramFiles%\jvman`
Runtime data	`%LOCALAPPDATA%\jvman` (or `JVMAN_HOME`)	Per invoking user
Installer state	`HKCU\Software\jvman\Installer`	`HKLM\Software\jvman\Installer`

Switches:

jvman-setup.exe /S [/LANG=en|zh-CN] [/DIR=<abs>] [/USER_PATH|/SYSTEM_PATH] [/NO_PATH]
jvman-setup.exe /CONFIGURE_JAVA [/REPLACE_JAVA_HOME]
jvman-setup.exe /DISCOVER
jvman-setup.exe /PORTABLE /DIR=<abs>
jvman-setup.exe /UNINSTALL [/S] [/REMOVE_DATA [/REMOVE_JDKS]]
jvman-setup.exe /UNINSTALL /MACHINE [/S]
jvman-setup.exe /HELP

/USER_PATH (default): HKCU Path gains program dir + <data-home>\current\bin.
/SYSTEM_PATH (also /MACHINE_PATH, /ALL_USERS_PATH): HKLM Path gains program dir only. Never adds a user-writable JDK dir to the machine PATH.
/CONFIGURE_JAVA: sets HKCU JAVA_HOME=<data-home>\current. Refuses to overwrite an existing different value unless /REPLACE_JAVA_HOME.
/NO_PATH / /NO_CONFIGURE_JAVA: on repeat install, also restore values previously owned by this installer.

Installer state is shared with the CLI: jvman-setup.exe /UNINSTALL rolls back entries the CLI added via install/use/activate. jvman deactivate does the equivalent from the CLI side.

Uninstall scopes (current-user only; /MACHINE cannot combine with either):

default — program files and env entries owned by this installer.
/REMOVE_DATA — plus JVMAN_HOME contents except the top-level jdks/ dir.
/REMOVE_DATA /REMOVE_JDKS — plus jdks/. Never traverses junctions or symlinks; externally-registered JDKs are never deleted.

Shell caveat: no process can modify its parent shell's environment. Terminals open at install time keep their old env until fully closed and reopened (this includes tabs on an existing Windows Terminal process — close the app, not just the tab). If a machine PATH Java still shadows the user PATH, put jvman init <shell> in the shell startup file: $PROFILE.CurrentUserAllHosts for PowerShell; a per-user CMD AutoRun with doubled percent signs (%%L). Preserve any existing AutoRun content.

Update

jvman update --check # verify, don't download
jvman update # latest stable, auto-pick fastest mirror
jvman update --version 0.4.0 # explicit, no downgrade
jvman update --source gitee # pin the mirror (github|gitee|auto)
jvman update --source-list # list mirrors

Version metadata always comes from api.github.com/repos/standtrain/jvman/releases/latest — that's the single source of truth for the "latest" tag.
Asset download (SHA256SUMS + the platform binary) can come from any configured mirror. Built-in mirrors:
- github → https://github.com/standtrain/jvman/releases/download
- gitee → https://gitee.com/zzpdhc/jvman/releases/download (China-friendly)
--source auto (default) probes both mirrors' asset URL with a bounded 64 KiB range request, then downloads once from the fastest. Failed probes are announced; download is not retried on a different mirror if the picked one later fails — same policy as install.
The Gitee mirror must have a Release tagged exactlyv<major.minor.patch> with the same asset filenames and matching SHA-256 as the GitHub release, otherwise the SHA-256 verification step in update will reject the binary.
HTTPS only; metadata and binary size capped.
Binary must match the release's SHA256SUMSand the PE/ELF/Mach-O architecture must match the host.
Linux/macOS require curl ≥ 7.20.2 in a fixed root-owned system path — a PATH-injected curl is deliberately ignored. macOS 11's system curl qualifies.
Windows: replacement runs in a restricted helper after the current process exits. Must run from a non-elevated terminal (the user-writable temp dir can't be a privilege boundary). If admin access is required, use the installer or replace the binary manually.
Only the running CLI is replaced. JVMAN_HOME, JDKs, PATH, JAVA_HOME, shell profiles, and installer state are not touched.
The checksum is published in the same GitHub Release: it detects corruption and mismatched assets but is not an independent signature.

Discovery

Status values:

new — registerable JDK not yet registered
registered:<name> — this home is already registered under <name>
jre — runtime is not a complete JDK
invalid — cannot be registered safely

Scanned locations (bounded — never a full-disk scan):

JAVA_HOME, every PATH entry (quotes/env vars/links/Windows Java shims resolved to real targets)
Windows: HKLM+HKCU JavaSoft keys (32-bit and 64-bit views), Program Files, Program Files (x86), LocalAppData Programs
User: ~/.jdks, SDKMAN, Jabba
Linux: /usr/java, /usr/lib*/jvm
macOS: JavaVirtualMachines, fixed Homebrew roots

jvman discover --register revalidates and registers only new entries. Must have java, javac, and a valid release file ≤ 64 KiB with Java ≥ 8. Name conflicts get -2, -3, … suffixes. Idempotent; never selects a current. All auto-registered entries use external semantics.

Design references

Not copied — read for prior art:

SDKMAN — install/use/current, stable candidate layout
jEnv — registering existing JDKs, which, doctor
Jabba — small cross-platform manager, shell env output
HMCL — bounded vendor / JavaSoft discovery
nvm-windows — stable-path switching over PATH rewrites

Scope and non-goals

0.2.1 supports:

Auto/pinned source benchmarking across global, TUNA, Huawei, Aliyun, custom
Remote install by Java major version
Local discovery of common JDK vendors

Deferred:

Multi-vendor selection at install time
Managed JREs, EA/GraalVM channels
Semver range install syntax
.java-version project files
Independent signed release manifests

Non-goals of the CLI:

Never adds a user-writable JDK dir to the machine PATH.
Never runs unknown external binaries during discovery.
Never scans an entire disk.
Never modifies files outside JVMAN_HOME except HKCU env entries (Windows) or ~/.bashrc and ~/.zshrc marker blocks (POSIX) it explicitly owns.

Security notes

All remote fetches are HTTPS. Redirects only across HTTPS.
Every remote archive must supply and match a SHA-256.
Junctions/symlinks are never traversed during removal.
.env and <data-home>/sources/*.conf are private-mode files.
jvman.exe starts with SafeSearchMode enabled and rewrites Windows command resolution to skip the empty PATH element (i.e. the current directory) — guards against binary planting during jvman exec and extractor invocations.
Self-update refuses to run elevated on Windows.

jvman

简体中文

A small Java version manager written in C11. One native executable, no linked third-party runtime, NTFS junctions for switching (no admin, no Developer Mode).

Version: 0.2.1. Primary target: Windows 10 1903+. Linux/macOS core is portable but the persistent-activation path differs (see below).

Install

Pick one:

Setup bundle (Windows) — download jvman-setup.exe, run interactively or silently. Handles PATH, JAVA_HOME, ARP entry, uninstall.
Single binary — drop jvman.exe anywhere on PATH. First jvman install / jvman use will self-persist JAVA_HOME and Path (opt-out below). No admin required.
Portable — jvman-setup.exe /PORTABLE /DIR=<abs-path> extracts the binary only; no registry, no PATH, no JAVA_HOME.

Quick start

jvman install 21# download Temurin 21, persist JAVA_HOME/PATH
jvman use 21# switch (also persists if not yet)
jvman list # what's registered
jvman current # what's active
java -version # new terminals: works immediately

Existing terminal opened before install? Refresh once:

jvman init powershell |Invoke-Expression# PowerShellfor/f "delims="%L in ('jvman init cmd') do @%L # CMD

Switching version (jvman use 17) does not rewrite PATH or JAVA_HOME. It rewrites one directory junction (<data-home>\current); every already- initialized shell picks the new JDK on the next process spawn. Java/Maven/ Gradle daemons must restart.

Commands

jvman install <major> [--name <n>] [--sha256 <hex>] [--source <src>] [--no-persist]
jvman install <name> --archive <file> [--sha256 <hex>] [--no-persist]
jvman add <name> <jdk-home> register an existing JDK (no copy)
jvman use <name> [--no-persist] switch active JDK
jvman activate [--replace-java-home] write HKCU/rc; idempotent
jvman deactivate reverse activate
jvman list | ls
jvman current
jvman which [name]
jvman remove <name> unregister; external JDKs stay on disk
jvman uninstall [<name>] alias of remove; no arg → run installer
jvman exec <name> [--] <cmd> [args...] run with selected JDK, no global change
jvman init [powershell|cmd|sh] emit shell-specific env script
jvman discover [--register] scan system for JDKs
jvman doctor validate JAVA_HOME/PATH/tools
jvman update [--check] [--version <v>] [--source <name>|--source-list]
self-update; --source picks a mirror (auto/github/gitee)
jvman source [--list|--reset|<name>|add <n> <tmpl>|remove <n>]
jvman language [--list|en|zh-CN]
jvman home print data-home

Aliases: ls=list, default=use.

Persistent activation

install and use automatically persist so new terminals and reopened IDEs resolve java without further setup.

Platform	What's written
Windows	`HKCU\Environment`: `JAVA_HOME=<data-home>\current`, `Path` prepended with `<data-home>\current\bin`. `WM_SETTINGCHANGE` broadcast. State recorded under `HKCU\Software\jvman\Installer` (shared with the installer).
POSIX	`~/.bashrc` and `~/.zshrc` gain a marker-fenced block that runs `eval "$(jvman init sh)"`. State recorded in `<data-home>/rc.state`.

Controls:

--no-persist on install/use — skip for that invocation.
JVMAN_NO_PERSIST=1 — skip globally.
jvman activate / jvman deactivate — explicit control; idempotent.
--replace-java-home — required if another program's JAVA_HOME is present; without it, activate refuses to overwrite.

Because JAVA_HOME points at the junction (not a version-specific dir), jvman use <ver> never touches the registry/rc after the first activate.

Data layout

%LOCALAPPDATA%\jvman on Windows, ${XDG_DATA_HOME:-~/.local/share}/jvman on Unix. Override with JVMAN_HOME.

<data-home>/
jdks/ JDKs owned by jvman (deleted on remove <name>)
versions/*.conf name → JAVA_HOME registrations
cache/ transient downloads + vendor metadata
staging/ in-progress installs
sources/*.conf custom Adoptium-compatible sources
source.conf selected remote source mode (absent = auto)
current junction/symlink to the active JDK
current.version active registration name
state.lock cross-process mutation lock
rc.state (POSIX) list of shell rc files touched by activate

Managed JDK deletion is confined to jdks/<name> and never follows links. External registrations (jvman add, discover --register) never delete the target on remove.

Sources

Built-in: tsinghua (TUNA Adoptium mirror), huawei (BiSheng), aliyun (Dragonwell), adoptium, foojay. auto (default) benchmarks all reachable sources — resolves metadata, then samples a bounded 64 KiB range from the final archive URL — and downloads once from the fastest.

jvman source auto # default
jvman source tsinghua # pin
jvman install 17--source adoptium # override once
jvman source add corp 'https://jdk.example.com/v3/{major}?os={os}&arch={arch}'

Custom source contract: Adoptium-compatible JSON, HTTPS only, must include SHA-256. Template placeholders: {major} (required), {os}, {arch}, {archive}. Credentials in URLs are rejected.

All remote archives are SHA-256 verified against source metadata; --sha256 adds a second pin. This detects corruption/mismatch but is not release signature verification.

Build

MSYS2 UCRT64 (this repo's tested toolchain):

$env:Path='C:\msys64\ucrt64\bin;'+$env:Pathmingw32-make.exe# produces jvman.exe and jvman-setup.exe

Portable Make / CMake:

make && make test&& make integration-test
make installer-test # Windows only
cmake -S . -B build && cmake --build build && ctest --test-dir build

Cross-compiling to Windows: setup stub and packer still build; the final jvman-setup.exe bundle is skipped because the packer can't run on the host.

Windows installer

jvman-setup.exe. Per-user by default (no UAC); all-users starts an elevated machine install through UAC. Manifest is asInvoker.

	Current user	All users
Program files	`%LOCALAPPDATA%\Programs\jvman`	`%ProgramFiles%\jvman`
Runtime data	`%LOCALAPPDATA%\jvman` (or `JVMAN_HOME`)	Per invoking user
Installer state	`HKCU\Software\jvman\Installer`	`HKLM\Software\jvman\Installer`

Switches:

jvman-setup.exe /S [/LANG=en|zh-CN] [/DIR=<abs>] [/USER_PATH|/SYSTEM_PATH] [/NO_PATH]
jvman-setup.exe /CONFIGURE_JAVA [/REPLACE_JAVA_HOME]
jvman-setup.exe /DISCOVER
jvman-setup.exe /PORTABLE /DIR=<abs>
jvman-setup.exe /UNINSTALL [/S] [/REMOVE_DATA [/REMOVE_JDKS]]
jvman-setup.exe /UNINSTALL /MACHINE [/S]
jvman-setup.exe /HELP

/USER_PATH (default): HKCU Path gains program dir + <data-home>\current\bin.
/SYSTEM_PATH (also /MACHINE_PATH, /ALL_USERS_PATH): HKLM Path gains program dir only. Never adds a user-writable JDK dir to the machine PATH.
/CONFIGURE_JAVA: sets HKCU JAVA_HOME=<data-home>\current. Refuses to overwrite an existing different value unless /REPLACE_JAVA_HOME.
/NO_PATH / /NO_CONFIGURE_JAVA: on repeat install, also restore values previously owned by this installer.

Installer state is shared with the CLI: jvman-setup.exe /UNINSTALL rolls back entries the CLI added via install/use/activate. jvman deactivate does the equivalent from the CLI side.

Uninstall scopes (current-user only; /MACHINE cannot combine with either):

default — program files and env entries owned by this installer.
/REMOVE_DATA — plus JVMAN_HOME contents except the top-level jdks/ dir.
/REMOVE_DATA /REMOVE_JDKS — plus jdks/. Never traverses junctions or symlinks; externally-registered JDKs are never deleted.

Shell caveat: no process can modify its parent shell's environment. Terminals open at install time keep their old env until fully closed and reopened (this includes tabs on an existing Windows Terminal process — close the app, not just the tab). If a machine PATH Java still shadows the user PATH, put jvman init <shell> in the shell startup file: $PROFILE.CurrentUserAllHosts for PowerShell; a per-user CMD AutoRun with doubled percent signs (%%L). Preserve any existing AutoRun content.

Update

jvman update --check # verify, don't download
jvman update # latest stable, auto-pick fastest mirror
jvman update --version 0.4.0 # explicit, no downgrade
jvman update --source gitee # pin the mirror (github|gitee|auto)
jvman update --source-list # list mirrors

Version metadata always comes from api.github.com/repos/standtrain/jvman/releases/latest — that's the single source of truth for the "latest" tag.
Asset download (SHA256SUMS + the platform binary) can come from any configured mirror. Built-in mirrors:
- github → https://github.com/standtrain/jvman/releases/download
- gitee → https://gitee.com/zzpdhc/jvman/releases/download (China-friendly)
--source auto (default) probes both mirrors' asset URL with a bounded 64 KiB range request, then downloads once from the fastest. Failed probes are announced; download is not retried on a different mirror if the picked one later fails — same policy as install.
The Gitee mirror must have a Release tagged exactlyv<major.minor.patch> with the same asset filenames and matching SHA-256 as the GitHub release, otherwise the SHA-256 verification step in update will reject the binary.
HTTPS only; metadata and binary size capped.
Binary must match the release's SHA256SUMSand the PE/ELF/Mach-O architecture must match the host.
Linux/macOS require curl ≥ 7.20.2 in a fixed root-owned system path — a PATH-injected curl is deliberately ignored. macOS 11's system curl qualifies.
Windows: replacement runs in a restricted helper after the current process exits. Must run from a non-elevated terminal (the user-writable temp dir can't be a privilege boundary). If admin access is required, use the installer or replace the binary manually.
Only the running CLI is replaced. JVMAN_HOME, JDKs, PATH, JAVA_HOME, shell profiles, and installer state are not touched.
The checksum is published in the same GitHub Release: it detects corruption and mismatched assets but is not an independent signature.

Discovery

Status values:

new — registerable JDK not yet registered
registered:<name> — this home is already registered under <name>
jre — runtime is not a complete JDK
invalid — cannot be registered safely

Scanned locations (bounded — never a full-disk scan):

JAVA_HOME, every PATH entry (quotes/env vars/links/Windows Java shims resolved to real targets)
Windows: HKLM+HKCU JavaSoft keys (32-bit and 64-bit views), Program Files, Program Files (x86), LocalAppData Programs
User: ~/.jdks, SDKMAN, Jabba
Linux: /usr/java, /usr/lib*/jvm
macOS: JavaVirtualMachines, fixed Homebrew roots

jvman discover --register revalidates and registers only new entries. Must have java, javac, and a valid release file ≤ 64 KiB with Java ≥ 8. Name conflicts get -2, -3, … suffixes. Idempotent; never selects a current. All auto-registered entries use external semantics.

Design references

Not copied — read for prior art:

SDKMAN — install/use/current, stable candidate layout
jEnv — registering existing JDKs, which, doctor
Jabba — small cross-platform manager, shell env output
HMCL — bounded vendor / JavaSoft discovery
nvm-windows — stable-path switching over PATH rewrites

Scope and non-goals

0.2.1 supports:

Auto/pinned source benchmarking across global, TUNA, Huawei, Aliyun, custom
Remote install by Java major version
Local discovery of common JDK vendors

Deferred:

Multi-vendor selection at install time
Managed JREs, EA/GraalVM channels
Semver range install syntax
.java-version project files
Independent signed release manifests

Non-goals of the CLI:

Never adds a user-writable JDK dir to the machine PATH.
Never runs unknown external binaries during discovery.
Never scans an entire disk.
Never modifies files outside JVMAN_HOME except HKCU env entries (Windows) or ~/.bashrc and ~/.zshrc marker blocks (POSIX) it explicitly owns.

Security notes

All remote fetches are HTTPS. Redirects only across HTTPS.
Every remote archive must supply and match a SHA-256.
Junctions/symlinks are never traversed during removal.
.env and <data-home>/sources/*.conf are private-mode files.
jvman.exe starts with SafeSearchMode enabled and rewrites Windows command resolution to skip the empty PATH element (i.e. the current directory) — guards against binary planting during jvman exec and extractor invocations.
Self-update refuses to run elevated on Windows.

jvman

简体中文

A small Java version manager written in C11. One native executable, no linked third-party runtime, NTFS junctions for switching (no admin, no Developer Mode).

Version: 0.2.1. Primary target: Windows 10 1903+. Linux/macOS core is portable but the persistent-activation path differs (see below).

Install

Pick one:

Setup bundle (Windows) — download jvman-setup.exe, run interactively or silently. Handles PATH, JAVA_HOME, ARP entry, uninstall.
Single binary — drop jvman.exe anywhere on PATH. First jvman install / jvman use will self-persist JAVA_HOME and Path (opt-out below). No admin required.
Portable — jvman-setup.exe /PORTABLE /DIR=<abs-path> extracts the binary only; no registry, no PATH, no JAVA_HOME.

Quick start

jvman install 21# download Temurin 21, persist JAVA_HOME/PATH
jvman use 21# switch (also persists if not yet)
jvman list # what's registered
jvman current # what's active
java -version # new terminals: works immediately

Existing terminal opened before install? Refresh once:

jvman init powershell |Invoke-Expression# PowerShellfor/f "delims="%L in ('jvman init cmd') do @%L # CMD

Switching version (jvman use 17) does not rewrite PATH or JAVA_HOME. It rewrites one directory junction (<data-home>\current); every already- initialized shell picks the new JDK on the next process spawn. Java/Maven/ Gradle daemons must restart.

Commands

jvman install <major> [--name <n>] [--sha256 <hex>] [--source <src>] [--no-persist]
jvman install <name> --archive <file> [--sha256 <hex>] [--no-persist]
jvman add <name> <jdk-home> register an existing JDK (no copy)
jvman use <name> [--no-persist] switch active JDK
jvman activate [--replace-java-home] write HKCU/rc; idempotent
jvman deactivate reverse activate
jvman list | ls
jvman current
jvman which [name]
jvman remove <name> unregister; external JDKs stay on disk
jvman uninstall [<name>] alias of remove; no arg → run installer
jvman exec <name> [--] <cmd> [args...] run with selected JDK, no global change
jvman init [powershell|cmd|sh] emit shell-specific env script
jvman discover [--register] scan system for JDKs
jvman doctor validate JAVA_HOME/PATH/tools
jvman update [--check] [--version <v>] [--source <name>|--source-list]
self-update; --source picks a mirror (auto/github/gitee)
jvman source [--list|--reset|<name>|add <n> <tmpl>|remove <n>]
jvman language [--list|en|zh-CN]
jvman home print data-home

Aliases: ls=list, default=use.

Persistent activation

install and use automatically persist so new terminals and reopened IDEs resolve java without further setup.

Platform	What's written
Windows	`HKCU\Environment`: `JAVA_HOME=<data-home>\current`, `Path` prepended with `<data-home>\current\bin`. `WM_SETTINGCHANGE` broadcast. State recorded under `HKCU\Software\jvman\Installer` (shared with the installer).
POSIX	`~/.bashrc` and `~/.zshrc` gain a marker-fenced block that runs `eval "$(jvman init sh)"`. State recorded in `<data-home>/rc.state`.

Controls:

--no-persist on install/use — skip for that invocation.
JVMAN_NO_PERSIST=1 — skip globally.
jvman activate / jvman deactivate — explicit control; idempotent.
--replace-java-home — required if another program's JAVA_HOME is present; without it, activate refuses to overwrite.

Because JAVA_HOME points at the junction (not a version-specific dir), jvman use <ver> never touches the registry/rc after the first activate.

Data layout

%LOCALAPPDATA%\jvman on Windows, ${XDG_DATA_HOME:-~/.local/share}/jvman on Unix. Override with JVMAN_HOME.

<data-home>/
jdks/ JDKs owned by jvman (deleted on remove <name>)
versions/*.conf name → JAVA_HOME registrations
cache/ transient downloads + vendor metadata
staging/ in-progress installs
sources/*.conf custom Adoptium-compatible sources
source.conf selected remote source mode (absent = auto)
current junction/symlink to the active JDK
current.version active registration name
state.lock cross-process mutation lock
rc.state (POSIX) list of shell rc files touched by activate

Managed JDK deletion is confined to jdks/<name> and never follows links. External registrations (jvman add, discover --register) never delete the target on remove.

Sources

Built-in: tsinghua (TUNA Adoptium mirror), huawei (BiSheng), aliyun (Dragonwell), adoptium, foojay. auto (default) benchmarks all reachable sources — resolves metadata, then samples a bounded 64 KiB range from the final archive URL — and downloads once from the fastest.

jvman source auto # default
jvman source tsinghua # pin
jvman install 17--source adoptium # override once
jvman source add corp 'https://jdk.example.com/v3/{major}?os={os}&arch={arch}'

Custom source contract: Adoptium-compatible JSON, HTTPS only, must include SHA-256. Template placeholders: {major} (required), {os}, {arch}, {archive}. Credentials in URLs are rejected.

All remote archives are SHA-256 verified against source metadata; --sha256 adds a second pin. This detects corruption/mismatch but is not release signature verification.

Build

MSYS2 UCRT64 (this repo's tested toolchain):

$env:Path='C:\msys64\ucrt64\bin;'+$env:Pathmingw32-make.exe# produces jvman.exe and jvman-setup.exe

Portable Make / CMake:

make && make test&& make integration-test
make installer-test # Windows only
cmake -S . -B build && cmake --build build && ctest --test-dir build

Cross-compiling to Windows: setup stub and packer still build; the final jvman-setup.exe bundle is skipped because the packer can't run on the host.

Windows installer

jvman-setup.exe. Per-user by default (no UAC); all-users starts an elevated machine install through UAC. Manifest is asInvoker.

	Current user	All users
Program files	`%LOCALAPPDATA%\Programs\jvman`	`%ProgramFiles%\jvman`
Runtime data	`%LOCALAPPDATA%\jvman` (or `JVMAN_HOME`)	Per invoking user
Installer state	`HKCU\Software\jvman\Installer`	`HKLM\Software\jvman\Installer`

Switches:

jvman-setup.exe /S [/LANG=en|zh-CN] [/DIR=<abs>] [/USER_PATH|/SYSTEM_PATH] [/NO_PATH]
jvman-setup.exe /CONFIGURE_JAVA [/REPLACE_JAVA_HOME]
jvman-setup.exe /DISCOVER
jvman-setup.exe /PORTABLE /DIR=<abs>
jvman-setup.exe /UNINSTALL [/S] [/REMOVE_DATA [/REMOVE_JDKS]]
jvman-setup.exe /UNINSTALL /MACHINE [/S]
jvman-setup.exe /HELP

/USER_PATH (default): HKCU Path gains program dir + <data-home>\current\bin.
/SYSTEM_PATH (also /MACHINE_PATH, /ALL_USERS_PATH): HKLM Path gains program dir only. Never adds a user-writable JDK dir to the machine PATH.
/CONFIGURE_JAVA: sets HKCU JAVA_HOME=<data-home>\current. Refuses to overwrite an existing different value unless /REPLACE_JAVA_HOME.
/NO_PATH / /NO_CONFIGURE_JAVA: on repeat install, also restore values previously owned by this installer.

Installer state is shared with the CLI: jvman-setup.exe /UNINSTALL rolls back entries the CLI added via install/use/activate. jvman deactivate does the equivalent from the CLI side.

Uninstall scopes (current-user only; /MACHINE cannot combine with either):

default — program files and env entries owned by this installer.
/REMOVE_DATA — plus JVMAN_HOME contents except the top-level jdks/ dir.
/REMOVE_DATA /REMOVE_JDKS — plus jdks/. Never traverses junctions or symlinks; externally-registered JDKs are never deleted.

Shell caveat: no process can modify its parent shell's environment. Terminals open at install time keep their old env until fully closed and reopened (this includes tabs on an existing Windows Terminal process — close the app, not just the tab). If a machine PATH Java still shadows the user PATH, put jvman init <shell> in the shell startup file: $PROFILE.CurrentUserAllHosts for PowerShell; a per-user CMD AutoRun with doubled percent signs (%%L). Preserve any existing AutoRun content.

Update

jvman update --check # verify, don't download
jvman update # latest stable, auto-pick fastest mirror
jvman update --version 0.4.0 # explicit, no downgrade
jvman update --source gitee # pin the mirror (github|gitee|auto)
jvman update --source-list # list mirrors

Version metadata always comes from api.github.com/repos/standtrain/jvman/releases/latest — that's the single source of truth for the "latest" tag.
Asset download (SHA256SUMS + the platform binary) can come from any configured mirror. Built-in mirrors:
- github → https://github.com/standtrain/jvman/releases/download
- gitee → https://gitee.com/zzpdhc/jvman/releases/download (China-friendly)
--source auto (default) probes both mirrors' asset URL with a bounded 64 KiB range request, then downloads once from the fastest. Failed probes are announced; download is not retried on a different mirror if the picked one later fails — same policy as install.
The Gitee mirror must have a Release tagged exactlyv<major.minor.patch> with the same asset filenames and matching SHA-256 as the GitHub release, otherwise the SHA-256 verification step in update will reject the binary.
HTTPS only; metadata and binary size capped.
Binary must match the release's SHA256SUMSand the PE/ELF/Mach-O architecture must match the host.
Linux/macOS require curl ≥ 7.20.2 in a fixed root-owned system path — a PATH-injected curl is deliberately ignored. macOS 11's system curl qualifies.
Windows: replacement runs in a restricted helper after the current process exits. Must run from a non-elevated terminal (the user-writable temp dir can't be a privilege boundary). If admin access is required, use the installer or replace the binary manually.
Only the running CLI is replaced. JVMAN_HOME, JDKs, PATH, JAVA_HOME, shell profiles, and installer state are not touched.
The checksum is published in the same GitHub Release: it detects corruption and mismatched assets but is not an independent signature.

Discovery

Status values:

new — registerable JDK not yet registered
registered:<name> — this home is already registered under <name>
jre — runtime is not a complete JDK
invalid — cannot be registered safely

Scanned locations (bounded — never a full-disk scan):

JAVA_HOME, every PATH entry (quotes/env vars/links/Windows Java shims resolved to real targets)
Windows: HKLM+HKCU JavaSoft keys (32-bit and 64-bit views), Program Files, Program Files (x86), LocalAppData Programs
User: ~/.jdks, SDKMAN, Jabba
Linux: /usr/java, /usr/lib*/jvm
macOS: JavaVirtualMachines, fixed Homebrew roots

jvman discover --register revalidates and registers only new entries. Must have java, javac, and a valid release file ≤ 64 KiB with Java ≥ 8. Name conflicts get -2, -3, … suffixes. Idempotent; never selects a current. All auto-registered entries use external semantics.

Design references

Not copied — read for prior art:

SDKMAN — install/use/current, stable candidate layout
jEnv — registering existing JDKs, which, doctor
Jabba — small cross-platform manager, shell env output
HMCL — bounded vendor / JavaSoft discovery
nvm-windows — stable-path switching over PATH rewrites

Scope and non-goals

0.2.1 supports:

Auto/pinned source benchmarking across global, TUNA, Huawei, Aliyun, custom
Remote install by Java major version
Local discovery of common JDK vendors

Deferred:

Multi-vendor selection at install time
Managed JREs, EA/GraalVM channels
Semver range install syntax
.java-version project files
Independent signed release manifests

Non-goals of the CLI:

Never adds a user-writable JDK dir to the machine PATH.
Never runs unknown external binaries during discovery.
Never scans an entire disk.
Never modifies files outside JVMAN_HOME except HKCU env entries (Windows) or ~/.bashrc and ~/.zshrc marker blocks (POSIX) it explicitly owns.

Security notes

All remote fetches are HTTPS. Redirects only across HTTPS.
Every remote archive must supply and match a SHA-256.
Junctions/symlinks are never traversed during removal.
.env and <data-home>/sources/*.conf are private-mode files.
jvman.exe starts with SafeSearchMode enabled and rewrites Windows command resolution to skip the empty PATH element (i.e. the current directory) — guards against binary planting during jvman exec and extractor invocations.
Self-update refuses to run elevated on Windows.

jvman

简体中文

A small Java version manager written in C11. One native executable, no linked third-party runtime, NTFS junctions for switching (no admin, no Developer Mode).

Version: 0.2.1. Primary target: Windows 10 1903+. Linux/macOS core is portable but the persistent-activation path differs (see below).

Install

Pick one:

Setup bundle (Windows) — download jvman-setup.exe, run interactively or silently. Handles PATH, JAVA_HOME, ARP entry, uninstall.
Single binary — drop jvman.exe anywhere on PATH. First jvman install / jvman use will self-persist JAVA_HOME and Path (opt-out below). No admin required.
Portable — jvman-setup.exe /PORTABLE /DIR=<abs-path> extracts the binary only; no registry, no PATH, no JAVA_HOME.

Quick start

jvman install 21# download Temurin 21, persist JAVA_HOME/PATH
jvman use 21# switch (also persists if not yet)
jvman list # what's registered
jvman current # what's active
java -version # new terminals: works immediately

Existing terminal opened before install? Refresh once:

jvman init powershell |Invoke-Expression# PowerShellfor/f "delims="%L in ('jvman init cmd') do @%L # CMD

Switching version (jvman use 17) does not rewrite PATH or JAVA_HOME. It rewrites one directory junction (<data-home>\current); every already- initialized shell picks the new JDK on the next process spawn. Java/Maven/ Gradle daemons must restart.

Commands

jvman install <major> [--name <n>] [--sha256 <hex>] [--source <src>] [--no-persist]
jvman install <name> --archive <file> [--sha256 <hex>] [--no-persist]
jvman add <name> <jdk-home> register an existing JDK (no copy)
jvman use <name> [--no-persist] switch active JDK
jvman activate [--replace-java-home] write HKCU/rc; idempotent
jvman deactivate reverse activate
jvman list | ls
jvman current
jvman which [name]
jvman remove <name> unregister; external JDKs stay on disk
jvman uninstall [<name>] alias of remove; no arg → run installer
jvman exec <name> [--] <cmd> [args...] run with selected JDK, no global change
jvman init [powershell|cmd|sh] emit shell-specific env script
jvman discover [--register] scan system for JDKs
jvman doctor validate JAVA_HOME/PATH/tools
jvman update [--check] [--version <v>] [--source <name>|--source-list]
self-update; --source picks a mirror (auto/github/gitee)
jvman source [--list|--reset|<name>|add <n> <tmpl>|remove <n>]
jvman language [--list|en|zh-CN]
jvman home print data-home

Aliases: ls=list, default=use.

Persistent activation

install and use automatically persist so new terminals and reopened IDEs resolve java without further setup.

Platform	What's written
Windows	`HKCU\Environment`: `JAVA_HOME=<data-home>\current`, `Path` prepended with `<data-home>\current\bin`. `WM_SETTINGCHANGE` broadcast. State recorded under `HKCU\Software\jvman\Installer` (shared with the installer).
POSIX	`~/.bashrc` and `~/.zshrc` gain a marker-fenced block that runs `eval "$(jvman init sh)"`. State recorded in `<data-home>/rc.state`.

Controls:

--no-persist on install/use — skip for that invocation.
JVMAN_NO_PERSIST=1 — skip globally.
jvman activate / jvman deactivate — explicit control; idempotent.
--replace-java-home — required if another program's JAVA_HOME is present; without it, activate refuses to overwrite.

Because JAVA_HOME points at the junction (not a version-specific dir), jvman use <ver> never touches the registry/rc after the first activate.

Data layout

%LOCALAPPDATA%\jvman on Windows, ${XDG_DATA_HOME:-~/.local/share}/jvman on Unix. Override with JVMAN_HOME.

<data-home>/
jdks/ JDKs owned by jvman (deleted on remove <name>)
versions/*.conf name → JAVA_HOME registrations
cache/ transient downloads + vendor metadata
staging/ in-progress installs
sources/*.conf custom Adoptium-compatible sources
source.conf selected remote source mode (absent = auto)
current junction/symlink to the active JDK
current.version active registration name
state.lock cross-process mutation lock
rc.state (POSIX) list of shell rc files touched by activate

Managed JDK deletion is confined to jdks/<name> and never follows links. External registrations (jvman add, discover --register) never delete the target on remove.

Sources

Built-in: tsinghua (TUNA Adoptium mirror), huawei (BiSheng), aliyun (Dragonwell), adoptium, foojay. auto (default) benchmarks all reachable sources — resolves metadata, then samples a bounded 64 KiB range from the final archive URL — and downloads once from the fastest.

jvman source auto # default
jvman source tsinghua # pin
jvman install 17--source adoptium # override once
jvman source add corp 'https://jdk.example.com/v3/{major}?os={os}&arch={arch}'

Custom source contract: Adoptium-compatible JSON, HTTPS only, must include SHA-256. Template placeholders: {major} (required), {os}, {arch}, {archive}. Credentials in URLs are rejected.

All remote archives are SHA-256 verified against source metadata; --sha256 adds a second pin. This detects corruption/mismatch but is not release signature verification.

Build

MSYS2 UCRT64 (this repo's tested toolchain):

$env:Path='C:\msys64\ucrt64\bin;'+$env:Pathmingw32-make.exe# produces jvman.exe and jvman-setup.exe

Portable Make / CMake:

make && make test&& make integration-test
make installer-test # Windows only
cmake -S . -B build && cmake --build build && ctest --test-dir build

Cross-compiling to Windows: setup stub and packer still build; the final jvman-setup.exe bundle is skipped because the packer can't run on the host.

Windows installer

jvman-setup.exe. Per-user by default (no UAC); all-users starts an elevated machine install through UAC. Manifest is asInvoker.

	Current user	All users
Program files	`%LOCALAPPDATA%\Programs\jvman`	`%ProgramFiles%\jvman`
Runtime data	`%LOCALAPPDATA%\jvman` (or `JVMAN_HOME`)	Per invoking user
Installer state	`HKCU\Software\jvman\Installer`	`HKLM\Software\jvman\Installer`

Switches:

jvman-setup.exe /S [/LANG=en|zh-CN] [/DIR=<abs>] [/USER_PATH|/SYSTEM_PATH] [/NO_PATH]
jvman-setup.exe /CONFIGURE_JAVA [/REPLACE_JAVA_HOME]
jvman-setup.exe /DISCOVER
jvman-setup.exe /PORTABLE /DIR=<abs>
jvman-setup.exe /UNINSTALL [/S] [/REMOVE_DATA [/REMOVE_JDKS]]
jvman-setup.exe /UNINSTALL /MACHINE [/S]
jvman-setup.exe /HELP

/USER_PATH (default): HKCU Path gains program dir + <data-home>\current\bin.
/SYSTEM_PATH (also /MACHINE_PATH, /ALL_USERS_PATH): HKLM Path gains program dir only. Never adds a user-writable JDK dir to the machine PATH.
/CONFIGURE_JAVA: sets HKCU JAVA_HOME=<data-home>\current. Refuses to overwrite an existing different value unless /REPLACE_JAVA_HOME.
/NO_PATH / /NO_CONFIGURE_JAVA: on repeat install, also restore values previously owned by this installer.

Installer state is shared with the CLI: jvman-setup.exe /UNINSTALL rolls back entries the CLI added via install/use/activate. jvman deactivate does the equivalent from the CLI side.

Uninstall scopes (current-user only; /MACHINE cannot combine with either):

default — program files and env entries owned by this installer.
/REMOVE_DATA — plus JVMAN_HOME contents except the top-level jdks/ dir.
/REMOVE_DATA /REMOVE_JDKS — plus jdks/. Never traverses junctions or symlinks; externally-registered JDKs are never deleted.

Shell caveat: no process can modify its parent shell's environment. Terminals open at install time keep their old env until fully closed and reopened (this includes tabs on an existing Windows Terminal process — close the app, not just the tab). If a machine PATH Java still shadows the user PATH, put jvman init <shell> in the shell startup file: $PROFILE.CurrentUserAllHosts for PowerShell; a per-user CMD AutoRun with doubled percent signs (%%L). Preserve any existing AutoRun content.

Update

jvman update --check # verify, don't download
jvman update # latest stable, auto-pick fastest mirror
jvman update --version 0.4.0 # explicit, no downgrade
jvman update --source gitee # pin the mirror (github|gitee|auto)
jvman update --source-list # list mirrors

Version metadata always comes from api.github.com/repos/standtrain/jvman/releases/latest — that's the single source of truth for the "latest" tag.
Asset download (SHA256SUMS + the platform binary) can come from any configured mirror. Built-in mirrors:
- github → https://github.com/standtrain/jvman/releases/download
- gitee → https://gitee.com/zzpdhc/jvman/releases/download (China-friendly)
--source auto (default) probes both mirrors' asset URL with a bounded 64 KiB range request, then downloads once from the fastest. Failed probes are announced; download is not retried on a different mirror if the picked one later fails — same policy as install.
The Gitee mirror must have a Release tagged exactlyv<major.minor.patch> with the same asset filenames and matching SHA-256 as the GitHub release, otherwise the SHA-256 verification step in update will reject the binary.
HTTPS only; metadata and binary size capped.
Binary must match the release's SHA256SUMSand the PE/ELF/Mach-O architecture must match the host.
Linux/macOS require curl ≥ 7.20.2 in a fixed root-owned system path — a PATH-injected curl is deliberately ignored. macOS 11's system curl qualifies.
Windows: replacement runs in a restricted helper after the current process exits. Must run from a non-elevated terminal (the user-writable temp dir can't be a privilege boundary). If admin access is required, use the installer or replace the binary manually.
Only the running CLI is replaced. JVMAN_HOME, JDKs, PATH, JAVA_HOME, shell profiles, and installer state are not touched.
The checksum is published in the same GitHub Release: it detects corruption and mismatched assets but is not an independent signature.

Discovery

Status values:

new — registerable JDK not yet registered
registered:<name> — this home is already registered under <name>
jre — runtime is not a complete JDK
invalid — cannot be registered safely

Scanned locations (bounded — never a full-disk scan):

JAVA_HOME, every PATH entry (quotes/env vars/links/Windows Java shims resolved to real targets)
Windows: HKLM+HKCU JavaSoft keys (32-bit and 64-bit views), Program Files, Program Files (x86), LocalAppData Programs
User: ~/.jdks, SDKMAN, Jabba
Linux: /usr/java, /usr/lib*/jvm
macOS: JavaVirtualMachines, fixed Homebrew roots

jvman discover --register revalidates and registers only new entries. Must have java, javac, and a valid release file ≤ 64 KiB with Java ≥ 8. Name conflicts get -2, -3, … suffixes. Idempotent; never selects a current. All auto-registered entries use external semantics.

Design references

Not copied — read for prior art:

SDKMAN — install/use/current, stable candidate layout
jEnv — registering existing JDKs, which, doctor
Jabba — small cross-platform manager, shell env output
HMCL — bounded vendor / JavaSoft discovery
nvm-windows — stable-path switching over PATH rewrites

Scope and non-goals

0.2.1 supports:

Auto/pinned source benchmarking across global, TUNA, Huawei, Aliyun, custom
Remote install by Java major version
Local discovery of common JDK vendors

Deferred:

Multi-vendor selection at install time
Managed JREs, EA/GraalVM channels
Semver range install syntax
.java-version project files
Independent signed release manifests

Non-goals of the CLI:

Never adds a user-writable JDK dir to the machine PATH.
Never runs unknown external binaries during discovery.
Never scans an entire disk.
Never modifies files outside JVMAN_HOME except HKCU env entries (Windows) or ~/.bashrc and ~/.zshrc marker blocks (POSIX) it explicitly owns.

Security notes

All remote fetches are HTTPS. Redirects only across HTTPS.
Every remote archive must supply and match a SHA-256.
Junctions/symlinks are never traversed during removal.
.env and <data-home>/sources/*.conf are private-mode files.
jvman.exe starts with SafeSearchMode enabled and rewrites Windows command resolution to skip the empty PATH element (i.e. the current directory) — guards against binary planting during jvman exec and extractor invocations.
Self-update refuses to run elevated on Windows.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
installer		installer
resources		resources
src		src
tests		tests
.gitignore		.gitignore
CMakeLists.txt		CMakeLists.txt
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
README.zh-CN.md		README.zh-CN.md

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
installer		installer
resources		resources
src		src
tests		tests
.gitignore		.gitignore
CMakeLists.txt		CMakeLists.txt
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
README.zh-CN.md		README.zh-CN.md

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
installer		installer
resources		resources
src		src
tests		tests
.gitignore		.gitignore
CMakeLists.txt		CMakeLists.txt
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
README.zh-CN.md		README.zh-CN.md

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
installer		installer
resources		resources
src		src
tests		tests
.gitignore		.gitignore
CMakeLists.txt		CMakeLists.txt
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
README.zh-CN.md		README.zh-CN.md

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
installer		installer
resources		resources
src		src
tests		tests
.gitignore		.gitignore
CMakeLists.txt		CMakeLists.txt
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
README.zh-CN.md		README.zh-CN.md

Latest commit

History

Folders and files

Repository files navigation

jvman

Install

Quick start

Commands

Persistent activation

Data layout

Sources

Build

Windows installer

Update

Discovery

Design references

Scope and non-goals

Security notes

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

jvman

Install

Quick start

Commands

Persistent activation

Data layout

Sources

Build

Windows installer

Update

Discovery

Design references

Scope and non-goals

Security notes

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

jvman

Install

Quick start

Commands

Persistent activation

Data layout

Sources

Build

Windows installer

Update

Discovery

Design references

Scope and non-goals

Security notes

About

Topics

Resources

Stars

Watchers

Forks