Replace JAVA_OPTS variable with JAVA_TOOL_OPTIONS (#13256)

JaroslavTulach · web-flow · commit a3bb3025e03a · 2025-06-16T17:52:22.000+02:00
diff --git a/.github/workflows/enso4igv.yml b/.github/workflows/enso4igv.yml
@@ -137,7 +137,7 @@ jobs:
           # Why do we subtract a number? Read versioning policy!
           # https://github.com/enso-org/enso/pull/7861#discussion_r1333133490
           echo "POM_VERSION=`mvn -q -DforceStdout help:evaluate -Dexpression=project.version | cut -f1 -d -`" >> "$GITHUB_ENV"
-          echo "MICRO_VERSION=`expr $GITHUB_RUN_NUMBER - 6930`" >> "$GITHUB_ENV"
+          echo "MICRO_VERSION=`expr $GITHUB_RUN_NUMBER - 8460`" >> "$GITHUB_ENV"
 
       - name: Update project version
         working-directory: tools/enso4igv
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -68,12 +68,14 @@
   [JavaScript](https://www.graalvm.org/javascript/) and
   [Python](https://www.graalvm.org/python/)) to version `24.2.0`.
 - [Upgrade GraalVM from JDK 21 to JDK 24][12855]
+- [Use JAVA_TOOL_OPTIONS env variable to alter JVM arguments][13256]
 
 [12500]: https://github.com/enso-org/enso/pull/12500
 [12976]: https://github.com/enso-org/enso/pull/12976
 [12855]: https://github.com/enso-org/enso/pull/12855
 [12905]: https://github.com/enso-org/enso/pull/12905
 [13225]: https://github.com/enso-org/enso/pull/13225
+[13256]: https://github.com/enso-org/enso/pull/13256
 
 # Enso 2025.1
 
diff --git a/build.sbt b/build.sbt
@@ -4322,7 +4322,8 @@ lazy val `os-environment` =
           val exeFile =
             (Test / target).value / ("test-os-env" + exeSuffix)
           val binPath = exeFile.getAbsolutePath
-          val res     = Process(Seq(binPath), None, "JAVA_OPTS" -> "") ! logger
+          val res =
+            Process(Seq(binPath), None, "JAVA_TOOL_OPTIONS" -> "") ! logger
           if (res != 0) {
             logger.error("Some test in os-environment failed")
             throw new TestsFailedException()
diff --git a/build_tools/build/src/enso.rs b/build_tools/build/src/enso.rs
@@ -37,7 +37,7 @@ impl From<bool> for Boolean {
 }
 
 ide_ci::define_env_var! {
-    JAVA_OPTS, String;
+    JAVA_TOOL_OPTIONS, String;
     ENSO_BENCHMARK_TEST_DRY_RUN, Boolean;
 }
 
@@ -131,7 +131,10 @@ impl BuiltEnso {
             .arg(test_path.as_ref())
             // This flag enables assertions in the JVM. Some of our stdlib tests had in the past
             // failed on Graal/Truffle assertions, so we want to have them triggered.
-            .set_env(JAVA_OPTS, &ide_ci::programs::java::Option::EnableAssertions.as_ref())?;
+            .set_env(
+                JAVA_TOOL_OPTIONS,
+                &ide_ci::programs::java::Option::EnableAssertions.as_ref(),
+            )?;
 
         for (k, v) in environment_overrides {
             command.env(k, &v);
diff --git a/distribution/bin/enso b/distribution/bin/enso
@@ -1,5 +1,4 @@
 COMP_PATH=$(dirname "$0")/../component
-
-JAVA_OPTS="--enable-native-access=org.graalvm.truffle --sun-misc-unsafe-memory-access=allow --add-opens=java.base/java.nio=ALL-UNNAMED $JAVA_OPTS"
+JAVA_OPTS="--enable-native-access=org.graalvm.truffle --sun-misc-unsafe-memory-access=allow --add-opens=java.base/java.nio=ALL-UNNAMED"
 exec java --module-path $COMP_PATH $JAVA_OPTS -m org.enso.runner/org.enso.runner.Main "$@"
 exit
diff --git a/distribution/bin/enso.bat b/distribution/bin/enso.bat
@@ -1,5 +1,5 @@
 @echo off
 set comp-dir=%~dp0\..\component
-set JAVA_OPTS=%JAVA_OPTS% --enable-native-access=org.graalvm.truffle --sun-misc-unsafe-memory-access=allow --add-opens=java.base/java.nio=ALL-UNNAMED
-java --module-path %comp-dir% -Dpolyglot.compiler.IterativePartialEscape=true %JAVA_OPTS% -m org.enso.runner/org.enso.runner.Main %*
+set java-opts=-Dpolyglot.compiler.IterativePartialEscape=true --enable-native-access=org.graalvm.truffle --sun-misc-unsafe-memory-access=allow --add-opens=java.base/java.nio=ALL-UNNAMED
+java --module-path %comp-dir%  %java-opts% -m org.enso.runner/org.enso.runner.Main %*
 exit /B %errorlevel%
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -493,7 +493,7 @@ To run with a debugger first start the debugger listening on 5005, add a
 breakpoint in a test then run with
 
 ```bash
-JAVA_OPTS='-agentlib:jdwp=transport=dt_socket,server=n,address=5005' enso --run test/Base_Tests/src/Data/Time/Duration_Spec.enso
+JAVA_TOOL_OPTIONS='-agentlib:jdwp=transport=dt_socket,server=n,address=5005' enso --run test/Base_Tests/src/Data/Time/Duration_Spec.enso
 ```
 
 The Database tests will by default only test the SQLite backend, to test other
@@ -510,7 +510,7 @@ LANG=C enso --run test/Base_Tests
 ```
 
 Note that JVM assertions are not enabled by default, one has to pass `-ea` via
-`JAVA_OPTS` environment variable. There are also Enso-specific assertions
+`JAVA_TOOL_OPTIONS` environment variable. There are also Enso-specific assertions
 (method `Runtime.assert`) that can be enabled when `ENSO_ENABLE_ASSERTIONS`
 environment variable is set to "true". If JVM assertions are enable, Enso
 assertions are enabled as well.
diff --git a/docs/debugger/chrome-devtools.md b/docs/debugger/chrome-devtools.md
@@ -36,6 +36,6 @@ the rest of the environment.
 
 ## Tips and tricks
 
-- Use `env JAVA_OPTS=-Dpolyglot.inspect.Path=enso_debug` to set the chrome to
-  use a fixed URL. In this case the URL is
+- Use `env JAVA_TOOL_OPTIONS=-Dpolyglot.inspect.Path=enso_debug` to set the
+  chrome to use a fixed URL. In this case the URL is
   `devtools://devtools/bundled/js_app.html?ws=127.0.0.1:9229/enso_debug`
diff --git a/docs/debugger/dap.md b/docs/debugger/dap.md
@@ -6,7 +6,7 @@ protocol for VSCode and as such, works only via VSCode. To start Enso with DAP
 server waiting for a client to attach, launch enso via:
 
 ```
-env JAVA_OPTS='-Dpolyglot.dap' ./built-distribution/enso-engine-*/enso-*/bin/enso --run *.enso
+env JAVA_TOOL_OPTIONS='-Dpolyglot.dap' ./built-distribution/enso-engine-*/enso-*/bin/enso --run *.enso
 ```
 
 Once DAP server is started and ready for a client to be attached, the following
diff --git a/docs/debugger/runtime-debugging.md b/docs/debugger/runtime-debugging.md
@@ -34,12 +34,12 @@ sbt:enso> runEngineDistribution --debug --run ./test/Base_Tests/src/Data/Numbers
 ```
 
 The second options gives one a complete control as it launches everything from a
-command line. By specifying `JAVA_OPTS` environment variable one influences the
-special JVM arguments when launching the `bin/enso` from the engine
-distribution:
+command line. By specifying `JAVA_TOOL_OPTIONS` environment variable one
+influences the special JVM arguments when launching the `bin/enso` from the
+engine distribution:
 
 ```bash
-enso$ JAVA_OPTS=-agentlib:jdwp=transport=dt_socket,server=n,address=5005 ./built-distribution/enso-engine-*/enso-*/bin/enso --run ./test/Base_Tests/src/Data/Numbers_Spec.enso
+enso$ JAVA_TOOL_OPTIONS=-agentlib:jdwp=transport=dt_socket,server=n,address=5005 ./built-distribution/enso-engine-*/enso-*/bin/enso --run ./test/Base_Tests/src/Data/Numbers_Spec.enso
 ```
 
 Both of the approaches launch the JVM in a _debug mode_. Once the JVM is
diff --git a/docs/infrastructure/native-image.md b/docs/infrastructure/native-image.md
@@ -117,7 +117,7 @@ Note that for convenience, you can run the launcher/engine runtime via
 `bin/enso`, e.g.
 
 ```bash
-env JAVA_OPTS="-agentlib:native-image-agent=config-merge-dir=./engine/runner/src/main/resources/META-INF/native-image/org/enso/runner" ./built-distribution/enso-engine-0.0.0-dev-linux-amd64/enso-0.0.0-dev/bin/enso --run tmp.enso
+env JAVA_TOOL_OPTIONS="-agentlib:native-image-agent=config-merge-dir=./engine/runner/src/main/resources/META-INF/native-image/org/enso/runner" ./built-distribution/enso-engine-0.0.0-dev-linux-amd64/enso-0.0.0-dev/bin/enso --run tmp.enso
 ```
 
 The command may need to be re-run with different arguments to ensure that all
@@ -293,10 +293,11 @@ $ ENSO_JAVA=espresso ./built-distribution/enso-engine-*/enso-*/bin/enso --run he
 Unless you see a warning containing _"No language for id java found."_ your code
 has just successfully been executed by
 [Espresso](https://www.graalvm.org/jdk17/reference-manual/java-on-truffle/)! To
-debug just add `JAVA_OPTS` environment variable set to your IDE favorite value:
+debug just add `JAVA_TOOL_OPTIONS` environment variable set to your IDE favorite
+value:
 
 ```bash
-$ JAVA_OPTS=-agentlib:jdwp=transport=dt_socket,address=5005 ENSO_JAVA=espresso enso --run hello.enso
+$ JAVA_TOOL_OPTIONS=-agentlib:jdwp=transport=dt_socket,address=5005 ENSO_JAVA=espresso enso --run hello.enso
 ```
 
 Espresso support works also with
diff --git a/docs/runtime-guide.md b/docs/runtime-guide.md
@@ -103,7 +103,7 @@ order: 7
     affect overall performance of your program. You can tell runner to generate
     compilation traces via additional options:
     ```
-    JAVA_OPTS="-Dpolygot.engine.TracePerformanceWarnings=all -Dpolyglot.engine.TraceTransferToInterpreter=true -Dpolyglot.engine.TraceDeoptimizeFrame=true -Dpolyglot.engine.TraceCompilation=true -Dpolyglot.engine.TraceCompilationDetails=true"
+    JAVA_TOOL_OPTIONS="-Dpolygot.engine.TracePerformanceWarnings=all -Dpolyglot.engine.TraceTransferToInterpreter=true -Dpolyglot.engine.TraceDeoptimizeFrame=true -Dpolyglot.engine.TraceCompilation=true -Dpolyglot.engine.TraceCompilationDetails=true"
     ```
     Make sure you print trace logs by using `--log-level TRACE`.
 11. Occasionally a piece of code runs slower than we anticipated. Analyzing
@@ -113,7 +113,7 @@ order: 7
     the performance. You can tell runner to generate inlining traces via
     additional options:
     ```
-    JAVA_OPTS="-Dpolyglot.engine.TraceInlining=true -Dpolyglot.engine.TraceInliningDetails=true"
+    JAVA_TOOL_OPTIONS="-Dpolyglot.engine.TraceInlining=true -Dpolyglot.engine.TraceInliningDetails=true"
     ```
     Make sure you print trace logs by using `--log-level TRACE`. See
     [documentation](https://www.graalvm.org/22.2/graalvm-as-a-platform/language-implementation-framework/Inlining/#call-tree-states)
diff --git a/docs/runtime/compiler-ir.md b/docs/runtime/compiler-ir.md
@@ -37,13 +37,13 @@ to how GraalVM graphs are dumped, which is documented in
 
 When using the `enso.compiler.dumpIr` property, one has to add
 `--add-exports jdk.graal.compiler/jdk.graal.compiler.graphio=org.enso.runtime.compiler.dump.igv`
-to the `JAVA_OPTS` env var, because the IGV dumper uses an internal package of
-GraalVM JDK's module which is not exported by default.
+to the `JAVA_TOOL_OPTIONS` env var, because the IGV dumper uses an internal
+package of GraalVM JDK's module which is not exported by default.
 
 Usage example:
 
 ```
-$ env JAVA_OPTS='--add-exports jdk.graal.compiler/jdk.graal.compiler.graphio=org.enso.runtime.compiler.dump.igv -Denso.compiler.dumpIr=Vector' ./built-distribution/*/bin/enso --no-ir-caches --run tmp.enso
+$ env JAVA_TOOL_OPTIONS='--add-exports jdk.graal.compiler/jdk.graal.compiler.graphio=org.enso.runtime.compiler.dump.igv -Denso.compiler.dumpIr=Vector' ./built-distribution/*/bin/enso --no-ir-caches --run tmp.enso
 ```
 
 The IR graphs are dumped directly to IGV, if it is running, or to the `ir-dumps`
diff --git a/docs/types/errors.md b/docs/types/errors.md
@@ -42,7 +42,7 @@ of their own creation - e.g. where `Error.throw` has happened. Shall that not be
 enough, one can run with `-ea` flag, like:
 
 ```bash
-enso$ JAVA_OPTS=-ea ./built-distribution/enso-engine-*/enso-*/bin/enso --run x.enso
+enso$ JAVA_TOOL_OPTIONS=-ea ./built-distribution/enso-engine-*/enso-*/bin/enso --run x.enso
 ```
 
 to get full stack where the _broken value_ has been created. Collecting such
diff --git a/engine/runner/src/main/java/org/enso/runner/Main.java b/engine/runner/src/main/java/org/enso/runner/Main.java
@@ -1433,21 +1433,19 @@ private boolean isJvmModeEnabled(CommandLine line) {
   }
 
   private void launchJvm(
-      CommandLine line, Map<String, String> props, File component, File javaExecutable)
+      String originalCwdOrNull,
+      CommandLine line,
+      Map<String, String> props,
+      File component,
+      File javaExecutable)
       throws IOException, InterruptedException {
     var useJNI = true;
     var commandAndArgs = new ArrayList<String>();
+    if (originalCwdOrNull != null) {
+      commandAndArgs.add("-Denso.user.dir=" + originalCwdOrNull);
+    }
     if (!useJNI) {
       commandAndArgs.add(javaExecutable.getPath());
-      var jvmOptions = System.getenv("JAVA_OPTS");
-      if (jvmOptions != null) {
-        for (var op : jvmOptions.split(" ")) {
-          if (op.isEmpty()) {
-            continue;
-          }
-          commandAndArgs.add(op);
-        }
-      }
     }
     var assertsOn = false;
     assert assertsOn = true;
@@ -1561,11 +1559,11 @@ private void launch(String[] args) throws IOException, InterruptedException, URI
               throw exitFail("Cannot find java executable");
             }
           } else {
-            launchJvm(line, props, component, javaExe);
+            launchJvm(originalCwdOrNull, line, props, component, javaExe);
           }
         } else {
           var javaExecutable = new File(new File(new File(jvm), "bin"), "java").getAbsoluteFile();
-          launchJvm(line, props, component, javaExecutable);
+          launchJvm(originalCwdOrNull, line, props, component, javaExecutable);
         }
       }
     }
diff --git a/engine/runner/src/main/java/org/enso/runner/Utils.java b/engine/runner/src/main/java/org/enso/runner/Utils.java
@@ -210,7 +210,7 @@ private static <S> void printFrame(
   static String adjustCwdToProject(String fileToRun) {
     assert fileToRun != null;
     if (!ImageInfo.inImageRuntimeCode()) {
-      return null;
+      return System.getProperty("enso.user.dir");
     }
     var nativeApi = WorkingDirectory.getInstance();
     var projectRoot = nativeApi.findProjectRoot(fileToRun);
diff --git a/lib/java/os-environment/src/main/java/org/enso/os/environment/jni/JVM.java b/lib/java/os-environment/src/main/java/org/enso/os/environment/jni/JVM.java
@@ -41,15 +41,6 @@ public static JVM create(File javaHome, String... options) {
     // java.home
     jvmArgs.add("-Djava.home=" + javaHome);
 
-    var jvmOptions = System.getenv("JAVA_OPTS");
-    if (jvmOptions != null) {
-      for (var op : jvmOptions.split(" ")) {
-        if (op.isEmpty()) {
-          continue;
-        }
-        jvmArgs.add(op);
-      }
-    }
     jvmArgs.addAll(Arrays.asList(options));
     return new JVM(createJvmFn, jvmArgs.toArray(new String[0]));
   }
diff --git a/project/DistributionPackage.scala b/project/DistributionPackage.scala
@@ -273,7 +273,7 @@ object DistributionPackage {
           val runningProcess = Process(
             command,
             Some(path.getAbsoluteFile.getParentFile),
-            "JAVA_OPTS" -> "-Dorg.jline.terminal.dumb=true"
+            "JAVA_TOOL_OPTIONS" -> "-Dorg.jline.terminal.dumb=true"
           ).run
           // Poor man's solution to stuck index generation
           val GENERATING_INDEX_TIMEOUT = 60 * 4 // 2 minutes
@@ -380,7 +380,7 @@ object DistributionPackage {
 
     all.add(enso.getAbsolutePath)
     all.addAll(args.asJava)
-    reduceArgs(all, "JAVA_OPTS", pb.environment)
+    reduceArgs(all, "JAVA_TOOL_OPTIONS", pb.environment)
     if (disablePrivateCheck) {
       all.add("--disable-private-check")
     }
diff --git a/test/Base_Tests/src/Runtime/Stack_Size_Spec.enso b/test/Base_Tests/src/Runtime/Stack_Size_Spec.enso
@@ -101,10 +101,10 @@ generate_code nesting_level:Integer -> Text =
    The thread stack size is also set to a sufficiently large value
    to ensure there is no StackOverflow.
 run_without_compiler enso_args:Vector -> Process_Result =
-    java_opts = "-Dpolyglot.engine.Compilation=false "
+    JAVA_TOOL_OPTIONS = "-Dpolyglot.engine.Compilation=false "
                 + "-XX:MaxJavaStackTraceDepth=18000 "
                 + "-Xms16M"
-    args = ["JAVA_OPTS="+java_opts, enso_bin.path] + enso_args
+    args = ["JAVA_TOOL_OPTIONS="+JAVA_TOOL_OPTIONS, enso_bin.path] + enso_args
     Process.run "env" (args + enso_args)
 
 
diff --git a/tools/ci/docker/engine/Dockerfile b/tools/ci/docker/engine/Dockerfile
@@ -7,7 +7,7 @@ ARG RPC_PORT=30001
 ARG DATA_PORT=30002
 ARG YDOC_PORT=1234
 ARG PRINT_VERSION=0
-ARG JAVA_OPTS="-XX:MaxRAMPercentage=90.0 -XX:InitialRAMPercentage=90.0"
+ARG JAVA_TOOL_OPTIONS="-XX:MaxRAMPercentage=90.0 -XX:InitialRAMPercentage=90.0"
 ARG PROFILING_FILENAME
 ARG PROFILING_TIME
 ARG ENSO_LAUNCHER
@@ -65,7 +65,7 @@ ENV DATA_PORT=${DATA_PORT}
 ENV YDOC_PORT=${YDOC_PORT}
 ENV LOG_LEVEL=${LOG_LEVEL}
 ENV PRINT_VERSION=${PRINT_VERSION}
-ENV JAVA_OPTS=${JAVA_OPTS}
+ENV JAVA_TOOL_OPTIONS=${JAVA_TOOL_OPTIONS}
 ENV ENSO_LAUNCHER=${ENSO_LAUNCHER}
 
 EXPOSE ${RPC_PORT}
diff --git a/tools/enso4igv/IGV.md b/tools/enso4igv/IGV.md
@@ -59,7 +59,7 @@ Build an instance of the Enso runtime engine (see
 it the following system properties:
 
 ```bash
-enso$ env JAVA_OPTS='-Dgraal.Dump=Truffle:2 -Dgraal.PrintGraph=File' ./built-distribution/enso-engine-0.0.0-dev-linux-amd64/enso-0.0.0-dev/bin/enso --run yourprogram.enso
+enso$ env JAVA_TOOL_OPTIONS='-Dgraal.Dump=Truffle:2 -Dgraal.PrintGraph=File' ./built-distribution/enso-engine-0.0.0-dev-linux-amd64/enso-0.0.0-dev/bin/enso --run yourprogram.enso
 ```
 
 See
@@ -80,7 +80,7 @@ which computes hundred thousand of prime numbers repeatedly and measures time of
 each round. Download the file and launch Enso with:
 
 ```bash
-enso$ env JAVA_OPTS='-Dgraal.Dump=Truffle:2 -Dgraal.PrintGraph=File' ./built-distribution/enso-engine-0.0.0-dev-linux-amd64/enso-0.0.0-dev/bin/enso --run yourprogram.enso
+enso$ env JAVA_TOOL_OPTIONS='-Dgraal.Dump=Truffle:2 -Dgraal.PrintGraph=File' ./built-distribution/enso-engine-0.0.0-dev-linux-amd64/enso-0.0.0-dev/bin/enso --run yourprogram.enso
 ```
 
 Bunch of files in `graal_dumps/*` subdirectory is going to be generated:
diff --git a/tools/enso4igv/pom.xml b/tools/enso4igv/pom.xml
@@ -5,7 +5,7 @@
     <artifactId>enso4igv</artifactId>
     <packaging>nbm</packaging>
     <name>Enso Language Support for NetBeans &amp; Ideal Graph Visualizer</name>
-    <version>1.42-SNAPSHOT</version>
+    <version>1.43-SNAPSHOT</version>
     <build>
         <plugins>
             <plugin>
diff --git a/tools/enso4igv/src/main/java/org/enso/tools/enso4igv/EnsoActionProvider.java b/tools/enso4igv/src/main/java/org/enso/tools/enso4igv/EnsoActionProvider.java
@@ -99,6 +99,7 @@ public void invokeAction(String action, Lookup lkp) throws IllegalArgumentExcept
                 if (isGraalVM && info.igvMode()) {
                     if (info.networkOn()) {
                         env.setVariable("JAVA_OPTS", info.toJavaOptions());
+                        env.setVariable("JAVA_TOOL_OPTIONS", info.toJavaOptions());
                     } else {
                         var icon = ImageUtilities.loadImageIcon("org/enso/tools/enso4igv/enso.svg", false);
                         var note = new Notification[1];
@@ -237,6 +238,7 @@ static final class DebugAndLaunch implements Callable<Process> {
         public Process call() throws Exception {
             var port = computeAddress.get();
             builder.getEnvironment().setVariable("JAVA_OPTS", "-agentlib:jdwp=transport=dt_socket,address=" + port);
+            builder.getEnvironment().setVariable("JAVA_TOOL_OPTIONS", "-agentlib:jdwp=transport=dt_socket,address=" + port);
             return builder.call();
         }
 
