distributions.adoc

Distributions

Distributions define artifacts that may be published using supported packages and announced with supported announcers.

Each distribution is responsible for defining a unique name and a list of artifacts that belong to it.

A distribution requires at least 1 artifact to be listed.

Distributions inherit the configuration specified in the reference:packagers/index.adoc block and may override it.

Distributions have a type that enables or disables additional features. These types are:

• concepts:distributions/binary.adoc

• concepts:distributions/flat-binary.adoc

• concepts:distributions/java-binary.adoc

• concepts:distributions/jlink.adoc

• concepts:distributions/native-image.adoc

• concepts:distributions/native-package.adoc

• concepts:distributions/single-jar.adoc

partial$legend.adoc

YAML

# [dot circle]
distributions:
  # A named distribution
  # [exclamation triangle]
  app:

    # Enables or disables the distribution.
    # Supported values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
    # Defaults to `ALWAYS`.
    # [dot circle]
    active: ALWAYS

    # The distribution type.
    # Used to determine packager templates.
    # Supported values are: [`JAVA_BINARY`, `SINGLE_JAR`, `JLINK`, `BINARY`, `FLAT-BINARY`, `NATIVE_PACKAGE`].
    # [exclamation triangle]
    type: JAVA_BINARY

    # The stereotype of this distribution.
    # Supported values are [`NONE`, `CLI`, `DESKTOP`, `WEB`, `MOBILE`].
    # Defaults to `${project.stereotype}`.
    # [dot circle]
    stereotype: CLI

    # [dot circle]
    executable:
      # Name of the executable launcher.
      # If left undefined, will use ${distribution.name}.
      # [dot circle]
      name: app

      # Executable extension on Linux/MacOS.
      # If left undefined, value will be left empty.
      # [dot circle]
      unixExtension: sh

      # Executable extension on Windows.
      # If left undefined, will use `bat`.
      # [dot circle]
      windowsExtension: cmd

    # A list of tags.
    # [dot circle]
    tags:
      - cli
      - awesome

    # Additional properties used when evaluating templates.
    # [dot circle] [file alt]
    extraProperties:
      # Key will be capitalized and prefixed with `distribution`, i.e, `distributionFoo`.
      foo: bar

    platform:
      # Key value pairs.
      # Keys match a full platform or an os.name, os.arch.
      # Same rules apply as in platform.adoc.
      # [dot circle]
      replacements:
        osx-x86_64: mac
        aarch_64: aarch64
        x86_64: amd64
        linux_musl: alpine

    # A list of artifacts.
    # At least on entry must be present.
    # [exclamation triangle] [file alt]
    artifacts:
      - path: path/to/{{distributionName}}-{{projectVersion}}.zip
      - path: path/to/{{distributionName}}-{{projectVersion}}-mac.zip
        platform: osx
      - path: path/to/{{distributionName}}-{{projectVersion}}-win.zip
        platform: windows

    # [dot circle]
    java:
      # Maven coordinates: groupId.
      # If left undefined, will use ${project.java.groupId}.
      # [dot circle]
      groupId: com.acme

      # Maven coordinates: artifactId.
      # If left undefined, will use ${project.java.artifactId}.
      # [dot circle]
      artifactId: app

      # The minimum Java version required by consumers to run the application.
      # If left undefined, will use ${project.java.version}.
      # [dot circle]
      version: 8

      # The application's entry point.
      # If left undefined, will use ${project.java.mainClass}.
      # [dot circle]
      mainClass: com.acme.Main

      # Identifies the project as being member of a multi-project build.
      # If left undefined, will use ${project.java.multiProject}.
      # [dot circle]
      multiProject: false

      # Additional properties used when evaluating templates.
      # [dot circle]
      extraProperties:
        # Key will be capitalized and prefixed with `java`, i.e, `javaFoo`.
        foo: bar

TOML

# A named distribution
# [exclamation triangle]
[distributions.app]

  # Enables or disables the distribution.
  # Supported values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
  # Defaults to `ALWAYS`.
  # [dot circle]
  active = "ALWAYS"

  # The distribution type.
  # Used to determine packager templates.
  # Supported values are: [`JAVA_BINARY`, `SINGLE_JAR`, `JLINK`, `BINARY`, `FLAT-BINARY`, `NATIVE_PACKAGE`].
  # [exclamation triangle]
  type = "JAVA_BINARY"

  # The stereotype of this distribution.
  # Supported values are [`NONE`, `CLI`, `DESKTOP`, `WEB`, `MOBILE`].
  # Defaults to `${project.stereotype}`.
  # [dot circle]
  stereotype = "CLI"

  # [dot circle]
  [distributions.app.executable]
    # Name of the executable launcher.
    # If left undefined, will use ${distribution.name}.
    # [dot circle]
    name = "app"

    # Executable extension on Linux/MacOS.
    # If left undefined, value will be left empty.
    # [dot circle]
    unixExtension = "sh"

    # Executable extension on Windows.
    # If left undefined, will use `bat`.
    # [dot circle]
    windowsExtension = "cmd"

  # A list of tags.
  # [dot circle]
  tags = ["cli", "awesome"]

  # Additional properties used when evaluating templates.
  # [dot circle] [file alt]
  extraProperties.foo = "bar"
  # Key will be capitalized and prefixed with `distribution`, i.e, `distributionFoo`.

  # Key value pairs.
  # Keys match a full platform or an os.name, os.arch.
  # Same rules apply as in platform.adoc.
  # [dot circle]
  [distributions.app.platform.replacements]
    osx-x86_64 = "mac"
    aarch_64 = "aarch64"
    x86_64 = "amd64"
    linux_musl = "alpine"

  # A list of artifacts.
  # At least on entry must be present.
  # [exclamation triangle] [file alt]
  artifacts = [
    { path = "path/to/{{distributionName}}-{{projectVersion}}.zip" },
    { path = "path/to/{{distributionName}}-{{projectVersion}}-mac.zip", platform = "osx" },
    { path = "path/to/{{distributionName}}-{{projectVersion}}-win.zip", platform = "windows" }
  ]

  # Maven coordinates: groupId.
  # If left undefined, will use ${project.java.groupId}.
  # [dot circle]
  java.groupId = "com.acme"

  # Maven coordinates: artifactId.
  # If left undefined, will use ${project.java.artifactId}.
  # [dot circle]
  java.artifactId = "app"

  # The minimum Java version required by consumers to run the application.
  # If left undefined, will use ${project.java.version}.
  # [dot circle]
  java.version = "8"

  # The application's entry point.
  # If left undefined, will use ${project.java.mainClass}.
  # [dot circle]
  java.mainClass = "com.acme.Main"

  # Identifies the project as being member of a multi-project build.
  # If left undefined, will use ${project.java.multiProject}.
  # [dot circle]
  java.multiProject = false

  # Additional properties used when evaluating templates.
  # [dot circle]
  java.extraProperties.foo = "bar"
  # Key will be capitalized and prefixed with `java`, i.e, `javaFoo`.

JSON

{
  // [dot circle]
  "distributions": {
    // A named distribution
    // [exclamation triangle]
    "app": {

      // Enables or disables the distribution.
      // Supported values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
      // Defaults to `ALWAYS`.
      // [dot circle]
      "active": "ALWAYS",

      // The distribution type.
      // Used to determine packager templates.
      // Supported values are: [`JAVA_BINARY`, `SINGLE_JAR`, `JLINK`, `BINARY`, `FLAT-BINARY`, `NATIVE_PACKAGE`].
      // [exclamation triangle]
      "type": "JAVA_BINARY",

      // The stereotype of this distribution.
      // Supported values are [`NONE`, `CLI`, `DESKTOP`, `WEB`, `MOBILE`].
      // Defaults to `${project.stereotype}`.
      // [dot circle]
      "stereotype": "CLI",

      // [dot circle]
      "executable":  {
        // Name of the executable launcher.
        // If left undefined, will use ${distribution.name}.
        // [dot circle]
        "name": "app",

        // Executable extension on Linux/MacOS.
        // If left undefined, value will be left empty.
        // [dot circle]
        "unixExtension": "sh",

        // Executable extension on Windows.
        // If left undefined, will use `bat`.
        // [dot circle]
        "windowsExtension": "cmd"
      },

      // A list of tags.
      // [dot circle]
      "tags": [
         "cli",
         "awesome"
      ],

      // Additional properties used when evaluating templates.
      // [dot circle] [file alt]
      "extraProperties": {
        // Key will be capitalized and prefixed with `distribution`, i.e, `distributionFoo`.
        "foo": "bar"
      },

      "platform": {
        // Key value pairs.
        // Keys match a full platform or an os.name, os.arch.
        // Same rules apply as in platform.adoc.
        // [dot circle]
        "replacements": {
          "osx-x86_64": "mac",
          "aarch_64": "aarch64",
          "x86_64": "amd64",
          "linux_musl": "alpine"
        }
      },

      // A list of artifacts.
      // At least on entry must be present.
      // [exclamation triangle] [file alt]
      "artifacts": [
        {
          "path": "path/to/{{distributionName}}-{{projectVersion}}.zip"
        },
        {
          "path": "path/to/{{distributionName}}-{{projectVersion}}-mac.zip",
          "platform": "osx"
        },
        {
          "path": "path/to/{{distributionName}}-{{projectVersion}}-win.zip",
          "platform": "windows"
        }
      ],

      // [dot circle]
      "java": {
        // Maven coordinates: groupId.
        // If left undefined, will use ${project.java.groupId}.
        // [dot circle]
        "groupId": "com.acme",

        // Maven coordinates: artifactId.
        // If left undefined, will use ${project.java.artifactId}.
        // [dot circle]
        "artifactId": "app",

        // The minimum Java version required by consumers to run the application.
        // If left undefined, will use ${project.java.version}.
        // [dot circle]
        "version": "8",

        // The application's entry point.
        // If left undefined, will use ${project.java.mainClass}.
        // [dot circle]
        "mainClass": "com.acme.Main",

        // Identifies the project as being member of a multi-project build.
        // If left undefined, will use ${project.java.multiProject}.
        // [dot circle]
        "multiProject": false,

        // Additional properties used when evaluating templates.
        // [dot circle]
        "extraProperties": {
          // Key will be capitalized and prefixed with `java`, i.e, `javaFoo`.
          "foo": "bar"
        }
      }
    }
  }
}

Maven

<jreleaser>
  <!--
    [dot circle]
  -->
  <distributions>
    <!--
      A named distribution
      [exclamation triangle]
    -->
    <app>

      <!--
        Enables or disables the distribution.
        Supported values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
        Defaults to `ALWAYS`.
        [dot circle]
      -->
      <active>ALWAYS</active>

      <!--
        The distribution type.
        Used to determine packager templates.
        Supported values are>[`JAVA_BINARY`, `SINGLE_JAR`, `JLINK`, `BINARY`, `FLAT-BINARY`, `NATIVE_PACKAGE`].
        [exclamation triangle]
      -->
      <type>JAVA_BINARY</type>

      <!--
        The stereotype of this distribution.
        Supported values are [`NONE`, `CLI`, `DESKTOP`, `WEB`, `MOBILE`].
        Defaults to `${project.stereotype}`.
        [dot circle]
      -->
      <stereotype>CLI</stereotype>

      <!--
        [dot circle]
      -->
      <executable>
        <!--
          Name of the executable launcher.
          If left undefined, will use ${distribution.name}.
          [dot circle]
        -->
        <name>app</name>

        <!--
          Executable extension on Linux/MacOS.
          If left undefined, value will be left empty.
          [dot circle]
        -->
        <unixExtension>sh</unixExtension>

        <!--
          Executable extension on Windows.
          If left undefined, will use `bat`.
          [dot circle]
        -->
        <windowsExtension>cmd</windowsExtension>
      </executable>

      <!--
        A list of tags.
        [dot circle]
      -->
      <tags>
        <tag>cli</tag>
        <tag>awesome</tag>
      </tags>

      <!--
        Additional properties used when evaluating templates.
        [dot circle] [file alt]
      -->
      <extraProperties>
        <!--
          Key will be capitalized and prefixed with `distribution`, i.e, `distributionFoo`.
        -->
        <foo>bar</foo>
      </extraProperties>

      <!--
        [dot circle]
      -->
      <platform>
        <!--
          Key value pairs.
          Keys match a full platform or an os.name, os.arch.
          Same rules apply as in platform.adoc.
          [dot circle]
        -->
        <replacements>
          <osx-x86_64>mac</osx-x86_64>
          <aarch_64>aarch64</aarch_64>
          <x86_64>amd64</x86_64>
          <linux_musl>alpine</linux_musl>
        </replacements>
      </platform>

      <!--
        A list of artifacts.
        At least on entry must be present.
        [exclamation triangle] [file alt]
      -->
      <artifacts>
        <artifact>
          <path>path/to/${project.artifactId}-${project.version}.zip</path>
        </artifact>
        <artifact>
          <path>path/to/${project.artifactId}-${project.version}-mac.zip</path>
          <platform>osx</platform>
        </artifact>
        <artifact>
          <path>path/to/${project.artifactId}-${project.version}-win.zip</path>
          <platform>windows</platform>
        </artifact>
      </artifacts>

      <!--
        [dot circle]
      -->
      <java>
        <!--
          Maven coordinates>groupId.
          If left undefined, will use ${project.java.groupId}.
          [dot circle]
        -->
        <groupId>com.acme</groupId>

        <!--
          Maven coordinates>artifactId.
          If left undefined, will use ${project.java.artifactId}.
          [dot circle]
        -->
        <artifactId>app</artifactId>

        <!--
          The minimum Java version required by consumers to run the application.
          If left undefined, will use ${project.java.version}.
          [dot circle]
        -->
        <version>8</version>

        <!--
          The application's entry point.
          If left undefined, will use ${project.java.mainClass}.
          [dot circle]
        -->
        <mainClass>com.acme.Main</mainClass>

        <!--
          Identifies the project as being member of a multi-project build.
          If left undefined, will use ${project.java.multiProject}.
          [dot circle]
        -->
        <multiProject>false</multiProject>

        <!--
          Additional properties used when evaluating templates.
          [dot circle]
        -->
        <extraProperties>
          <!--
            Key will be capitalized and prefixed with `java`, i.e, `javaFoo`.
          -->
          <foo>bar</foo>
        </extraProperties>
      </java>
    </app>
  </distributions>
</jreleaser>

Gradle

jreleaser {
  // [dot circle]
  distributions {
    // A named distribution
    // [exclamation triangle]
    app {

      // Enables or disables the distribution.
      // Supported values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
      // Defaults to `ALWAYS`.
      // [dot circle]
      active = 'ALWAYS'

      // The distribution type.
      // Used to determine packager templates.
      // Supported values are = [`JAVA_BINARY`, `SINGLE_JAR`, `JLINK`, `BINARY`, `FLAT-BINARY`, `NATIVE_PACKAGE`].
      // [exclamation triangle]
      distributionType = 'JAVA_BINARY'

      // The stereotype of this distribution.
      // Supported values are [`NONE`, `CLI`, `DESKTOP`, `WEB`, `MOBILE`].
      // Defaults to `${project.stereotype}`.
      // [dot circle]
      stereotype = 'CLI'

      // [dot circle]
      executable {
        // Name of the executable launcher.
        // If left undefined, will use ${distribution.name}.
        // [dot circle]
        name = 'app'

        // Executable extension on Linux/MacOS.
        // If left undefined, value will be left empty.
        // [dot circle]
        unixExtension = 'sh'

        // Executable extension on Windows.
        // If left undefined, will use `bat`.
        // [dot circle]
        windowsExtension = 'cmd'
      }

      // A list of tags.
      // [dot circle]
      tags = ['cli', 'awesome']

      // Additional properties used when evaluating templates.
      // Key will be capitalized and prefixed with `distribution`, i.e, `distributionFoo`.
      // [dot circle] [file alt]
      extraProperties.put('foo', 'bar')

      // [dot circle]
      platform {

        // Key value pairs.
        // Keys match a full platform or an os.name, os.arch.
        // Same rules apply as in platform.adoc.
        // [dot circle]
        replacements = [
          'osx-x86_64': 'mac',
          aarch_64: 'aarch64',
          x86_64: 'amd64',
          linux_musl: 'alpine'
        ]
      }

      // A list of artifacts.
      // At least on entry must be present.
      // [exclamation triangle] [file alt]
      artifact {
        path = "path/to/${project.name}-${project.version}.zip"
      }
      artifact {
        path = "path/to/${project.name}-${project.version}-mac.zip"
        platform = 'osx'
      }
      artifact {
        path = "path/to/${project.name}-${project.version}-win.zip"
        platform = 'windows'
      }

      // [dot circle]
      java {
        // Maven coordinates = groupId.
        // If left undefined, will use ${project.java.groupId}.
        // [dot circle]
        groupId = 'com.acme'

        // Maven coordinates = artifactId.
        // If left undefined, will use ${project.java.artifactId}.
        // [dot circle]
        artifactId = 'app'

        // The minimum Java version required by consumers to run the application.
        // If left undefined, will use ${project.java.version}.
        // [dot circle]
        version = '8'

        // The application's entry point.
        // If left undefined, will use ${project.java.mainClass}.
        // [dot circle]
        mainClass = 'com.acme.Main'

        // Identifies the project as being member of a multi-project build.
        // If left undefined, will use ${project.java.multiProject}.
        // [dot circle]
        multiProject = false

        // Additional properties used when evaluating templates.
        // Key will be capitalized and prefixed with `java`, i.e, `javaFoo`.
        // [dot circle]
        extraProperties.put('foo', 'bar')
      }
    }
  }
}

It’s recommended to list universal artifacts first, then platform specific.

partial$platform.adoc