Artifacts & Globs

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

  • added to a Git release.

  • 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.

Properties

Artifacts have the following properties:

  • path. Defines the location of the file. Path may be relative or absolute. We recomend 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’d looking for. You may apply a name transformation using this property. Its value may use Name Templates. This property is optional.

  • platform. Defines the OS specific platform for this file. Some assemblers and packagers require that artifacts define a platform.

  • extraProperties. Defines key/value pairs of metadata that’s related to the artifact.

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-arm

  • windows

  • linux

  • linux-x86_64

Use linux_musl for artifacts that target Alpine Linux.

Globs have the following properties:

  • pattern. Defines pattern used to match artifacts.

  • extraProperties. Defines key/value pairs of metadata that’s related to the resolved artifacts.

The pattern field accepts glob or regex patterns by using glob: and regex: prefixes accordingly. If no prefix is specified then glob: will be used.

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-0.7.0.zip
│    └── jreleaser-tool-provider
│        └── build
│            └── libs
│                └── jreleaser-tool-provider-0.7.0.jar
└── plugins
    └── jreleaser-ant-tasks
        └── build
            └── distributions
                └── jreleaser-ant-tasks-0.7.0.zip