Skip to main content
Version: 2.34 (dev)

coursier

A dependency resolver for the Maven ecosystem. (https://get-coursier.io/)

Backend: pants.backend.experimental.java.bsp

Config section: [coursier]

Basic options​

jvm_index​

--coursier-jvm-index=<str>
PANTS_COURSIER_JVM_INDEX
pants.toml
[coursier]
jvm_index = <str>
default:

The JVM index to be used by Coursier.

Possible values are:

  • cs: The default JVM index used and maintained by Coursier.
  • cs-maven: Fetches a JVM index from the io.get-coursier:jvm-index Maven repository.
  • <URL>: An arbitrary URL for a JVM index. Ex. https://url/of/your/index.json

repos​

--coursier-repos="['<str>', '<str>', ...]"
PANTS_COURSIER_REPOS
pants.toml
[coursier]
repos = [
  '<str>',
  '<str>',
  ...,
]
default: 
[
  "https://maven-central.storage-download.googleapis.com/maven2",
  "https://repo1.maven.org/maven2"
]

Maven style repositories to resolve artifacts from.

Coursier will resolve these repositories in the order in which they are specified, and re-ordering repositories will cause artifacts to be re-downloaded. This can result in artifacts in lockfiles becoming invalid.

Advanced options​

jvm_options​

--coursier-jvm-options="['<str>', '<str>', ...]"
PANTS_COURSIER_JVM_OPTIONS
pants.toml
[coursier]
jvm_options = [
  '<str>',
  '<str>',
  ...,
]
default: []

Extra JVM options to pass to Coursier.

Coursier is distributed as a GraalVM native image. It bundles its own trust store from build time and does not read the HTTP_PROXY/HTTPS_PROXY environment variables, so a custom CA or proxy must be supplied as JVM system properties on Coursier's own command line. Without this option there is no way to do that, and Coursier fails to fetch artifacts and JDKs in environments with a TLS-inspecting proxy or without direct internet access.

Each value is passed to Coursier prefixed with -J; the prefix is added automatically if you omit it. For example, both -Djavax.net.ssl.trustStore=/etc/pki/java/cacerts and -J-Djavax.net.ssl.trustStore=/etc/pki/java/cacerts are passed to Coursier as -J-Djavax.net.ssl.trustStore=/etc/pki/java/cacerts.

These options apply to every Coursier invocation, including JDK provisioning. They are unrelated to [jvm].global_options, which applies to the JVM processes Pants runs, not to Coursier itself.

See https://get-coursier.io/docs/other-proxy.

known_versions​

--coursier-known-versions="['<str>', '<str>', ...]"
PANTS_COURSIER_KNOWN_VERSIONS
pants.toml
[coursier]
known_versions = [
  '<str>',
  '<str>',
  ...,
]
default: 
[
  "v2.1.24|linux_arm64 |96b4c7580d253b6999a40e94413ca6c4a9bd2339ecce4754ac31a26d1a12fcbf|21534519|https://github.com/VirtusLab/coursier-m1/releases/download/v2.1.24/cs-aarch64-pc-linux.gz",
  "v2.1.24|linux_x86_64|d2c0572a17fb6146ea65349b59dd216b38beff60ae22bce6e549867c6ed2eda6|23366878",
  "v2.1.24|macos_arm64 |8f47594eb62dea25af913c8932d1f1d86a3a9c8e1262925b63852635390a3f43|21541383|https://github.com/VirtusLab/coursier-m1/releases/download/v2.1.24/cs-aarch64-apple-darwin.gz",
  "v2.1.24|macos_x86_64|33913cd6b61658035d9e6fe971e919cb0ef1f659aa7bff7deeded963a2d36385|22442034",
  "v2.1.6|linux_arm64 |33330ca433781c9db9458e15d2d32e5d795de3437771647e26835e8b1391af82|20899290|https://github.com/VirtusLab/coursier-m1/releases/download/v2.1.6/cs-aarch64-pc-linux.gz",
  "v2.1.6|linux_x86_64|af7234f8802107f5e1130307ef8a5cc90262d392f16ddff7dce27a4ed0ddd292|20681688",
  "v2.1.6|macos_arm64 |746b3e346fa2c0107fdbc8a627890d495cb09dee4f8dcc87146bdb45941088cf|20829782|https://github.com/VirtusLab/coursier-m1/releases/download/v2.1.6/cs-aarch64-apple-darwin.gz",
  "v2.1.6|macos_x86_64|36a5d42a0724be2ac39d0ebd8869b985e3d58ceb121bc60389ee2d6d7408dd56|20037412",
  "v2.1.0-M5-18-gfebf9838c|linux_arm64 |d4ad15ba711228041ad8a46d848c83c8fbc421d7b01c415d8022074dd609760f|19264005",
  "v2.1.0-M5-18-gfebf9838c|linux_x86_64|3e1a1ad1010d5582e9e43c5a26b273b0147baee5ebd27d3ac1ab61964041c90b|19551533",
  "v2.1.0-M5-18-gfebf9838c|macos_arm64 |d13812c5a5ef4c9b3e25cc046d18addd09bacd149f95b20a14e4d2a73e358ecf|18826510",
  "v2.1.0-M5-18-gfebf9838c|macos_x86_64|d13812c5a5ef4c9b3e25cc046d18addd09bacd149f95b20a14e4d2a73e358ecf|18826510",
  "v2.0.16-169-g194ebc55c|linux_arm64 |da38c97d55967505b8454c20a90370c518044829398b9bce8b637d194d79abb3|18114472",
  "v2.0.16-169-g194ebc55c|linux_x86_64|4c61a634c4bd2773b4543fe0fc32210afd343692891121cddb447204b48672e8|18486946",
  "v2.0.16-169-g194ebc55c|macos_arm64 |15bce235d223ef1d022da30b67b4c64e9228d236b876c834b64e029bbe824c6f|17957182",
  "v2.0.16-169-g194ebc55c|macos_x86_64|15bce235d223ef1d022da30b67b4c64e9228d236b876c834b64e029bbe824c6f|17957182"
]

Known versions to verify downloads against.

Each element is a pipe-separated string of version|platform|sha256|length or version|platform|sha256|length|url_override, where:

  • version is the version string
  • platform is one of [linux_arm64,linux_x86_64,macos_arm64,macos_x86_64]
  • sha256 is the 64-character hex representation of the expected sha256 digest of the download file, as emitted by shasum -a 256
  • length is the expected length of the download file in bytes, as emitted by wc -c
  • (Optional) url_override is a specific url to use instead of the normally generated url for this version

E.g., 3.1.2|macos_x86_64|6d0f18cd84b918c7b3edd0203e75569e0c7caecb1367bbbe409b44e28514f5be|42813. and 3.1.2|macos_arm64 |aca5c1da0192e2fd46b7b55ab290a92c5f07309e7b0ebf4e45ba95731ae98291|50926|https://example.mac.org/bin/v3.1.2/mac-aarch64-v3.1.2.tgz.

Values are space-stripped, so pipes can be indented for readability if necessary.

url_platform_mapping​

--coursier-url-platform-mapping="{'key1': val1, 'key2': val2, ...}"
PANTS_COURSIER_URL_PLATFORM_MAPPING
pants.toml
[coursier.url_platform_mapping]
key1 = val1
key2 = val2
...
default: 
{
  "linux_arm64": "aarch64-pc-linux",
  "linux_x86_64": "x86_64-pc-linux",
  "macos_arm64": "x86_64-apple-darwin",
  "macos_x86_64": "x86_64-apple-darwin"
}

A dictionary mapping platforms to strings to be used when generating the URL to download the tool.

In --url-template, anytime the {platform} string is used, Pants will determine the current platform, and substitute {platform} with the respective value from your dictionary.

For example, if you define {"macos_x86_64": "apple-darwin", "linux_x86_64": "unknown-linux"}, and run Pants on Linux with an intel architecture, then {platform} will be substituted in the --url-template option with unknown-linux.

url_template​

--coursier-url-template=<str>
PANTS_COURSIER_URL_TEMPLATE
pants.toml
[coursier]
url_template = <str>
default: https://github.com/coursier/coursier/releases/download/{version}/cs-{platform}.gz

URL to download the tool, either as a single binary file or a compressed file (e.g. zip file). You can change this to point to your own hosted file, e.g. to work with proxies or for access via the filesystem through a file:$abspath URL (e.g. file:/this/is/absolute, possibly by templating the buildroot in a config file).

Use {version} to have the value from --version substituted, and {platform} to have a value from --url-platform-mapping substituted in, depending on the current platform. For example, https://github.com/.../protoc-&#123;version&#125;-&#123;platform&#125;.zip.

use_unsupported_version​

--coursier-use-unsupported-version=<UnsupportedVersionUsage>
PANTS_COURSIER_USE_UNSUPPORTED_VERSION
pants.toml
[coursier]
use_unsupported_version = <UnsupportedVersionUsage>
one of: error, warning
default: error

What action to take in case the requested version of coursier is not supported.

Supported coursier versions: unspecified

version​

--coursier-version=<str>
PANTS_COURSIER_VERSION
pants.toml
[coursier]
version = <str>
default: v2.1.24

Use this version of coursier.

Deprecated options​

None

None