jenv-gradle-low-ram

name	jenv-gradle-low-ram
description	Align jenv with .java-version and run Gradle reliably on low-RAM machines. Use for Java mismatch errors, Gradle OOMs, daemon memory pressure, and selecting safe build flags.
argument-hint	Describe your target task and available RAM, for example: assembleDebug on 8GB RAM

Jenv + Gradle Low-RAM Workflow

What This Skill Produces

• A shell where java and Gradle use the Java version pinned by .java-version.
• A repeatable Gradle command profile tuned for constrained memory.
• Verification checks to confirm version alignment and build stability.

When To Use

• Any time when ./gradlew is about to be invoked in this repository.
• Especially important for low-RAM machines where daemon/worker pressure can destabilize builds.
• Required when verifying that Java from .java-version is the active runtime for Gradle.

Procedure

1. Detect the required Java version.

cat .java-version

2. Verify jenv is installed and initialized.

command -v jenv
jenv versions
jenv version

Decision point:

• If jenv is not found, install and initialize it in your shell startup.
• If jenv is found but jenv version does not match .java-version, continue to step 3.

3. Align local Java to the repository pin.

required_java="$(cat .java-version)"
jenv local "$required_java"

Decision point:

• If jenv local fails because the version is missing, install that JDK and run jenv add <jdk-path>, then retry.

4. Confirm runtime alignment before any Gradle task.

java -version
./gradlew -version

Quality check:

• Gradle JVM version in ./gradlew -version must match .java-version major version (21).

5. Run Gradle with low-memory-safe defaults.

Preferred one-off profile for a debug build:

./gradlew :markdown:assembleDebug \
  --no-daemon --max-workers=2 \
  -Dorg.gradle.jvmargs="-Xmx1536m -XX:MaxMetaspaceSize=512m -Dfile.encoding=UTF-8"

For unit tests:

./gradlew :markdown:test \
  --no-daemon --max-workers=2 \
  -Dorg.gradle.jvmargs="-Xmx1792m -XX:MaxMetaspaceSize=512m -Dfile.encoding=UTF-8"

6. If memory pressure continues, downgrade concurrency.

./gradlew :markdown:assembleDebug \
  --no-daemon --max-workers=1 -Dorg.gradle.parallel=false

7. If builds are stable and you want persistence, prefer user-local Gradle overrides (avoid committing repo-wide memory changes).

Suggested entries for ~/.gradle/gradle.properties:

org.gradle.daemon=false
org.gradle.parallel=false
org.gradle.workers.max=2
org.gradle.jvmargs=-Xmx1536m -XX:MaxMetaspaceSize=512m -Dfile.encoding=UTF-8

Troubleshooting Branches

• jenv version correct but java -version wrong: Ensure shell init runs eval "$(jenv init -)" and enable export plugin with jenv enable-plugin export.
• Gradle daemon disappeared unexpectedly: Retry with --no-daemon --max-workers=1 and lower -Xmx if the OS is reclaiming memory aggressively.
• Kotlin compile OOM: Keep workers low, disable parallel, and run module-targeted tasks (:markdown:assembleDebug) instead of full-project builds.
• app module not found during build: The :app module is excluded in CI (settings.gradle checks the CI env var). Run without CI=true locally or target :markdown explicitly.

Completion Checks

• .java-version and jenv version resolve to the same Java release.
• ./gradlew -version reports the expected JVM.
• Target Gradle task completes without OOM or daemon crash.
• Machine remains responsive during build (no prolonged swap thrash).

Fast Invocation Examples

• "Align my shell to .java-version and run a debug build with 8GB RAM settings"
• "I get class file major version errors; fix jenv and verify Gradle JVM"
• "Run unit tests with a low-memory Gradle profile and fallback if OOM occurs"