Artifacts, Globs, FileSets

Artifacts are at the heart of a release; they define files that may be:

added to a Git release.
added to assemblers.
prepared, packaged, and published using a packager.

Artifacts refer to a specific file as they have a single path property. Globs on the other hand refer to a collection of files. Files resolved by Artifact and Glob types do not preserve directory structure but FileSets do.

Artifacts

Artifacts have the following properties:

active. Enable or disable this file. Supported values are [NEVER, ALWAYS, RELEASE, SNAPSHOT]. Defaults to ALWAYS. This property is optional.
path. Defines the location of the file. Path may be relative or absolute. We recommend defining paths that are relative to the basedir as much as possible, as that simplifies the setup on CI. Its value may use Name Templates. This property is required.
transform. Sometimes the source path does not have the exact name you’re looking for. You may apply a name transformation using this property. Its value may use Name Templates. This property is optional.
extraProperties. Defines key/value pairs of metadata that’s related to the artifact.
platform. Defines the OS specific platform for this file. Some assemblers and packagers require that artifacts define a platform.

The value of platform is dictated by the normalized values detected by os-maven-plugin. You may use the plain platform value or append a arch classifier. The following values are currently recognized:

platform: aix, hpux, os400, linux, linux_musl, osx, freebsd, openbsd, netbsd, sunos, windows, zos.
arch: x86_64, x86_32, itanium_64, itanium_32, sparc_32, sparc_64, arm_32, aarch_64, mips_32, mipsel_32, mips_64, mipsel_64, ppc_32, ppcle_32, ppc_64, ppcle_64, s390_32, s390_64, riscv

Examples:

osx
osx-aarch_64
windows
linux
linux-x86_64

Use linux_musl for artifacts that target Alpine Linux.

Platform detection may be overridden by defining an environment variable or a System property named JRELEASER_PLATFORM_OVERRIDE.

Optional

There may be times when artifacts are not be available for various reasons yet the release should continue without them. You may set an extra property named optional whose value resolves to true or false. Optional artifacts will be automatically skipped. You may use name templates with this property, for example

environment:
  properties:
    # default value if property is not explicitly set
    versionOpt: false

files:
  artifacts:
    - path: 'target/resources/version.txt'
      extraProperties:
        optional: '{{versionOpt}}'

You may then execute a release and skip the given file by running the following command:

$ jreleaser release -PversionOpt=true

Globs

Globs have the following properties:

active. Enable or disable this file. Supported values are [NEVER, ALWAYS, RELEASE, SNAPSHOT]. Defaults to ALWAYS. This property is optional.
pattern. Defines pattern used to match artifacts. Accepts glob or regex patterns by using glob: and regex: prefixes accordingly. If no prefix is specified then glob: will be used. This property is required.
directory. Defines the starting point when searching for files. Defaults to the context’s basedir. This property is optional.
extraProperties. Defines key/value pairs of metadata that’s related to the resolved artifacts.
platform. Defines the OS specific platform for all matching files. Some assemblers and packagers require that globs define a platform.

platform: aix, hpux, os400, linux, linux_musl, osx, freebsd, openbsd, netbsd, sunos, windows, zos.
arch: x86_64, x86_32, itanium_64, itanium_32, sparc_32, sparc_64, arm_32, aarch_64, mips_32, mipsel_32, mips_64, mipsel_64, ppc_32, ppcle_32, ppc_64, ppcle_64, s390_32, s390_64, riscv

Examples:

osx
osx-aarch_64
windows
linux
linux-x86_64

Use linux_musl for artifacts that target Alpine Linux.

Platform detection may be overridden by defining an environment variable or a System property named JRELEASER_PLATFORM_OVERRIDE.

FileSets

FileSets have the following properties:

active. Enable or disable this file. Supported values are [NEVER, ALWAYS, RELEASE, SNAPSHOT]. Defaults to ALWAYS. This property is optional.
input. Defines the input path to search for files. Its value may use Name Templates. This property is required.
output. Defines the path where matching files will be copied to. Its value may use Name Templates. This property is optional.
failOnMissingInput. Fail if the given input does not exist. Defaults to true. This property is optional.
includes. A set of names or globs to match filenames. Matches will be included in the resulting set. Values may use Name Templates.
excludes. A set of names or globs to match filenames. Matches will be excluded from the resulting set. Values may use Name Templates.
extraProperties. Defines key/value pairs of metadata that’s related to the resolved paths.
platform. Defines the OS specific platform for all matching files. Some assemblers and packagers require that fileSets define a platform.

platform: aix, hpux, os400, linux, linux_musl, osx, freebsd, openbsd, netbsd, sunos, windows, zos.
arch: x86_64, x86_32, itanium_64, itanium_32, sparc_32, sparc_64, arm_32, aarch_64, mips_32, mipsel_32, mips_64, mipsel_64, ppc_32, ppcle_32, ppc_64, ppcle_64, s390_32, s390_64, riscv

Examples:

osx
osx-aarch_64
windows
linux
linux-x86_64

Use linux_musl for artifacts that target Alpine Linux.

Platform detection may be overridden by defining an environment variable or a System property named JRELEASER_PLATFORM_OVERRIDE.

Examples

Platform

Generating cross-platform Jlink images require that each target JDK define a value for its corresponding platform. Target JDKs are of type artifact.

YAML
TOML
JSON
Maven
Gradle

assemble:
  jlink:
    app:
      active: ALWAYS
      jdk:
        path: '{{oracleJdks}}/jdk-16_osx-x64/Contents/Home'
        platform: osx
      targetJdks:
        - path: '{{oracleJdks}}/jdk-16_osx-x64/Contents/Home'
          platform: osx
        - path: '{{oracleJdks}}/jdk-16_linux-x64'
          platform: linux
        - path: '{{oracleJdks}}/jdk-16_windows-x64'
          platform: windows
      mainJar:
        path: 'target/{{distributionName}}-{{projectVersion}}.jar'

[assemble.jlink.app]
  active = "ALWAYS"
  mainJar = { path = "target/{{distributionName}}-{{projectVersion}}.jar" }
  jdk = { path = "{{oracleJdks}}/jdk-16_osx-x64/Contents/Home", platform = "osx" }
  [[assemble.jlink.app.targetJdks]]
    path = "{{oracleJdks}}/jdk-16_osx-x64/Contents/Home"
    platform = "osx"
  [[assemble.jlink.app.targetJdks]]
    path = "{{oracleJdks}}/jdk-16_linux-x64"
    platform = "linux"
  [[assemble.jlink.app.targetJdks]]
    path = "{{oracleJdks}}/jdk-16_windows-x64"
    platform = "windows"

{
  "assemble": {
    "jlink": {
      "app": {
        "active": "ALWAYS",
        "mainJar": {
          "path": "target/{{distributionName}}-{{projectVersion}}.jar"
        },
        "jdk": {
          "path": "{{oracleJdks}}/jdk-16_osx-x64/Contents/Home",
          "platform": "osx"
        },
        "targetJdks": [
          {
            "path": "{{oracleJdks}}/jdk-16_osx-x64/Contents/Home",
            "platform": "osx"
          },
          {
            "path": "{{oracleJdks}}/jdk-16_linux-x64",
            "platform": "linux"
          },
          {
            "path": "{{oracleJdks}}/jdk-16_windows-x64",
            "platform": "windows"
          }
        ]
      }
    }
  }
}

<jreleaser>
  <assemble>
    <jlink>
      <name>app</name>
      <active>ALWAYS</active>
      <mainJar>
        <path>target/{{distributionName}}-{{projectVersion}}.jar</path>
      </mainJar>
      <jdk>
        <path>{{oracleJdks}}/jdk-16_osx-x64/Contents/Home</path>
        <platform>osx</platform>
      </jdk>
      <targetJdks>
        <targetJdk>
          <path>{{oracleJdks}}/jdk-16_osx-x64/Contents/Home</path>
          <platform>osx</platform>
        </targetJdk>
        <targetJdk>
          <path>{{oracleJdks}}/jdk-16_linux-x64</path>
          <platform>linux</platform>
        </targetJdk>
        <targetJdk>
          <path>{{oracleJdks}}/jdk-16_windows-x64</path>
          <platform>windows</platform>
        </targetJdk>
      </targetJdks>
    </jlink>
  </assemble>
</jreleaser>

jreleaser {
  assemble {
    jlink {
      app {
        active = 'ALWAYS'
        mainJar {
          path = 'target/{{distributionName}}-{{projectVersion}}.jar'
        }
        jdk {
          path = '{{oracleJdks}}/jdk-16_osx-x64/Contents/Home'
          platform = 'osx'
        }
        targetJdk {
          path = '{{oracleJdks}}/jdk-16_osx-x64/Contents/Home'
          platform = 'osx'
        }
        targetJdk {
          path = '{{oracleJdks}}/jdk-16_linux-x64'
          platform = 'linux'
        }
        targetJdk {
          path = '{{oracleJdks}}/jdk-16_windows-x64'
          platform = 'windows'
        }
      }
    }
  }
}

Transform

JReleaser itself uses the transform property to rename its artifacts depending on the type of release.

jreleaser.yml

distributions:
  jreleaser:
    artifacts:
      - path: apps/{{distributionName}}/build/distributions/{{distributionName}}-{{projectVersion}}.zip
        transform: '{{distributionName}}/{{distributionName}}-{{projectEffectiveVersion}}.zip'

  jreleaser-ant-tasks:
    artifacts:
      - path: plugins/{{distributionName}}/build/distributions/{{distributionName}}-{{projectVersion}}.zip
        transform: '{{distributionName}}/{{distributionName}}-{{projectEffectiveVersion}}.zip'

  jreleaser-tool-provider:
    type: SINGLE_JAR
    artifacts:
      - path: apps/jreleaser-tool-provider/build/libs/jreleaser-tool-provider-{{projectVersion}}.jar
        transform: 'jreleaser-tool-provider/jreleaser-tool-provider-{{projectEffectiveVersion}}.jar'

Artifacts point to these files when the project version is snapshot:

out
└── jreleaser
    └── artifacts
        ├── jreleaser
        │   └── jreleaser-early-access.zip
        ├── jreleaser-ant-tasks
        │   └── jreleaser-ant-tasks-early-access.zip
        └── jreleaser-tool-provider
            └── jreleaser-tool-provider-early-access.jar

Whereas the following files will be used when the project is release:

.
├── apps
│    ├── jreleaser
│    │   └── build
│    │       └── distributions
│    │           └── jreleaser-1.19.0.zip
│    └── jreleaser-tool-provider
│        └── build
│            └── libs
│                └── jreleaser-tool-provider-1.19.0.jar
└── plugins
    └── jreleaser-ant-tasks
        └── build
            └── distributions
                └── jreleaser-ant-tasks-1.19.0.zip