Skip to main content
Version: 2.22

jvm

Options for general JVM functionality.

JDK strings will be passed directly to Coursier's --jvm parameter. Run cs java --available to see a list of available JVM versions on your platform.

If the string 'system' is passed, Coursier's --system-jvm option will be used instead, but note that this can lead to inconsistent behavior since the JVM version will be whatever happens to be found first on the system's PATH.

Backend: pants.backend.experimental.java

Config section: [jvm]

Basic options​

debug_args​

--jvm-debug-args="['<str>', '<str>', ...]"
PANTS_JVM_DEBUG_ARGS
pants.toml
[jvm]
debug_args = [
    '<str>',
    '<str>',
    ...,
]
default: []

Extra JVM arguments to use when running tests in debug mode.

For example, if you want to attach a remote debugger, use something like ['-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005'].

default_resolve​

--jvm-default-resolve=<str>
PANTS_JVM_DEFAULT_RESOLVE
pants.toml
[jvm]
default_resolve = <str>
default: jvm-default

The default value used for the resolve and compatible_resolves fields.

The name must be defined as a resolve in [jvm].resolves.

deploy_jar_exclude_files​

--jvm-deploy-jar-exclude-files="['<str>', '<str>', ...]"
PANTS_JVM_DEPLOY_JAR_EXCLUDE_FILES
pants.toml
[jvm]
deploy_jar_exclude_files = [
    '<str>',
    '<str>',
    ...,
]
default: 
[
  "^META-INF/[^/]+\.SF$",
  "^META-INF/[^/]+\.DSA$",
  "^META-INF/[^/]+\.RSA$",
  "META-INF/INDEX.LIST$"
]

A list of patterns to exclude from all deploy jars. An individual deploy_jar target can also exclude other files, in addition to these, by setting its exclude_files field.

resolves​

--jvm-resolves="{'key1': val1, 'key2': val2, ...}"
PANTS_JVM_RESOLVES
pants.toml
[jvm.resolves]
key1 = val1
key2 = val2
...
default: 
{
  "jvm-default": "3rdparty/jvm/default.lock"
}

A dictionary mapping resolve names to the path of their lockfile.

Advanced options​

global_options​

--jvm-global-options="['<str>', '<str>', ...]"
PANTS_JVM_GLOBAL_OPTIONS
pants.toml
[jvm]
global_options = [
    '<str>',
    '<str>',
    ...,
]
default: []

List of JVM options to pass to all JVM processes.

Options set here will be used by any JVM processes required by Pants, with the exception of heap memory settings like -Xmx, which need to be set using [GLOBAL].process_total_child_memory_usage and [GLOBAL].process_per_child_memory_usage.

Can be overriden by fieldjvm_global_options on local_environment, docker_environment, or remote_environmenttargets.

jdk​

--jvm-jdk=<str>
PANTS_JVM_JDK
pants.toml
[jvm]
jdk = <str>
default: temurin:1.11

The JDK to use.

This string will be passed directly to Coursier's --jvm parameter. Run cs java --available to see a list of available JVM versions on your platform.

If the string 'system' is passed, Coursier's --system-jvm option will be used instead, but note that this can lead to inconsistent behavior since the JVM version will be whatever happens to be found first on the system's PATH.

nailgun_remote_cache_speculation_delay​

--jvm-nailgun-remote-cache-speculation-delay=<int>
PANTS_JVM_NAILGUN_REMOTE_CACHE_SPECULATION_DELAY
pants.toml
[jvm]
nailgun_remote_cache_speculation_delay = <int>
default: 1000

The time in milliseconds to delay speculation of nailgun processes while reading from the remote cache.

When speculating, a remote cache hit will cancel the local copy of a process. But because nailgun does not natively support cancellation, that requires killing a nailgun server, which will mean that future processes take longer to warm up.

This setting allows for trading off waiting for potentially slow cache entries against potentially having to warm up a new nailgun server.

reproducible_jars​

--[no-]jvm-reproducible-jars
PANTS_JVM_REPRODUCIBLE_JARS
pants.toml
[jvm]
reproducible_jars = <bool>
default: False

When enabled, JAR files produced by JVM tools will have timestamps stripped.

Because some compilers do not support this step as a native operation, it can have a performance cost, and is not enabled by default.

tool_jdk​

--jvm-tool-jdk=<str>
PANTS_JVM_TOOL_JDK
pants.toml
[jvm]
tool_jdk = <str>
default: temurin:1.11

The JDK to use when building and running Pants' internal JVM support code and other non-compiler tools. See jvm help for supported values.

Deprecated options​

None

None