From 70a8b9b65ba98aacbbdbe203515be97dc43167e5 Mon Sep 17 00:00:00 2001
From: Andres Almiray <aalmiray@gmail.com>
Date: Thu, 9 Jan 2025 19:23:42 +0100
Subject: [PATCH] Document matrix updates

Relates to https://github.com/jreleaser/jreleaser/issues/1780
Relates to https://github.com/jreleaser/jreleaser/issues/1782
Relates to https://github.com/jreleaser/jreleaser/issues/1783
---
 .../reference/pages/assemble/archive.adoc     | 200 ++++++++----------
 .../reference/pages/assemble/jlink.adoc       | 100 +++++++++
 .../pages/assemble/native-image.adoc          |  91 ++++++++
 .../reference/pages/distributions.adoc        |  85 ++++++++
 .../partials/matrix/gradle/matrix.adoc        |  17 ++
 .../partials/matrix/json/matrix.adoc          |  20 ++
 .../partials/matrix/maven/matrix.adoc         |  49 +++++
 .../partials/matrix/toml/matrix.adoc          |  14 ++
 .../partials/matrix/yaml/matrix.adoc          |  17 ++
 9 files changed, 476 insertions(+), 117 deletions(-)
 create mode 100644 docs/modules/reference/partials/matrix/gradle/matrix.adoc
 create mode 100644 docs/modules/reference/partials/matrix/json/matrix.adoc
 create mode 100644 docs/modules/reference/partials/matrix/maven/matrix.adoc
 create mode 100644 docs/modules/reference/partials/matrix/toml/matrix.adoc
 create mode 100644 docs/modules/reference/partials/matrix/yaml/matrix.adoc

diff --git a/docs/modules/reference/pages/assemble/archive.adoc b/docs/modules/reference/pages/assemble/archive.adoc
index a50528c30..07be37063 100644
--- a/docs/modules/reference/pages/assemble/archive.adoc
+++ b/docs/modules/reference/pages/assemble/archive.adoc
@@ -49,23 +49,7 @@ include::partial$assemble/yaml/common-head.adoc[]
         - ZIP
         - TGZ
 
-      # Includes the default matrix.
-      # icon:dot-circle[]
-      applyDefaultMatrix: false
-
-      # Configures matrix variables.
-      # icon:dot-circle[]
-      matrix:
-        vars:
-          os: [ linux, osx, windows ]
-          arch: [ arm64, amd64 ]
-        rows:
-          - { os: linux, arch: arm64 }
-          - { os: linux, arch: amd64 }
-          - { os: osx, arch: arm64 }
-          - { os: osx, arch: amd64 }
-          - { os: windows, arch: arm64 }
-          - { os: windows, arch: amd64 }
+include::partial$matrix/yaml/matrix.adoc[indent=6]
 
 include::partial$assemble/yaml/common-archive-options.adoc[]
 
@@ -104,20 +88,7 @@ include::partial$assemble/toml/common-head.adoc[]
   # icon:dot-circle[]
   formats = [ "ZIP", "TGZ"]
 
-  # Includes the default matrix.
-  # icon:dot-circle[]
-  applyDefaultMatrix = false
-
-  # Configures matrix variables.
-  # icon:dot-circle[]
-  matrix.vars.os = [ "linux", "osx", "windows" ]
-  matrix.vars.arch= [ "arm64", "amd64" ]
-  rows = [{ os = "linux", arch = "arm64" },
-          { os = "linux", arch = "amd64" },
-          { os = "osx", arch = "arm64" },
-          { os = "osx", arch = "amd64" },
-          { os = "windows", arch = "arm64" },
-          { os = "windows", arch = "amd64" }]
+include::partial$matrix/toml/matrix.adoc[]
 
 include::partial$assemble/toml/common-archive-options.adoc[]
 
@@ -159,26 +130,7 @@ include::partial$assemble/json/common-head.adoc[]
            "TGZ"
         ],
 
-        // Includes the default matrix.
-        // icon:dot-circle[]
-        "applyDefaultMatrix": false,
-
-        // Configures matrix variables.
-        // icon:dot-circle[]
-        "matrix": {
-          "vars": {
-            "os": [ "linux", "osx", "windows" ],
-            "arch": [ "arm64", "amd64" ]
-          },
-          "rows": [
-            { "os": "linux", "arch": "arm64" },
-            { "os": "linux", "arch": "amd64" },
-            { "os": "osx", "arch": "arm64" },
-            { "os": "osx", "arch": "amd64" },
-            { "os": "windows", "arch": "arm64" },
-            { "os": "windows", "arch": "amd64" }
-          ]
-        }
+include::partial$matrix/json/matrix.adoc[indent=8]
 
 include::partial$assemble/json/common-archive-options.adoc[]
 
@@ -229,55 +181,7 @@ include::partial$assemble/maven/common-head.adoc[]
           <format>TGZ</format>
         </formats>
 
-        <!--
-          Includes the default matrix.
-          icon:dot-circle[]
-        -->
-        <applyDefaultMatrix>false</applyDefaultMatrix>
-
-        <!--
-          Configures matrix variables.
-          icon:dot-circle[]
-        -->
-        <matrix>
-          <vars>
-            <os>
-              <e>linux</e>
-              <e>osx</e>
-              <e>windows</e>
-            </os>
-            <arch>
-              <e>arm64</e>
-              <e>amd64</e>
-            </arch>
-          </vars>
-          <rows>
-            <row>
-              <os>linux</os>
-              <arch>arm64</arch>
-            </row>
-            <row>
-              <os>linux</os>
-              <arch>amd64</arch>
-            </row>
-            <row>
-              <os>osx</os>
-              <arch>arm64</arch>
-            </row>
-            <row>
-              <os>osx</os>
-              <arch>amd64</arch>
-            </row>
-            <row>
-              <os>windows</os>
-              <arch>arm64</arch>
-            </row>
-            <row>
-              <os>windows</os>
-              <arch>amd64</arch>
-            </row>
-          </rows>
-        </matrix>
+include::partial$matrix/maven/matrix.adoc[indent=8]
 
 include::partial$assemble/maven/common-archive-options.adoc[]
 
@@ -320,23 +224,7 @@ include::partial$assemble/gradle/common-head.adoc[]
             'TGZ'
         ]
 
-       // Includes the default matrix.
-       // icon:dot-circle[]
-       applyDefaultMatrix = false
-
-       // Configures matrix variables.
-       // icon:dot-circle[]
-       matrix {
-         variable('os', ['linux', 'osx', 'windows'])
-         variable('arch', ['arm64', 'amd64'])
-
-         row(os: 'linux', arch: 'arm64')
-         row(os: 'linux', arch: 'amd64')
-         row(os: 'osx', arch: 'arm64')
-         row(os: 'osx', arch: 'amd64')
-         row(os: 'windows', arch: 'arm64')
-         row(os: 'windows', arch: 'amd64')
-       }
+include::partial$matrix/gradle/matrix.adoc[indent=8]
 
 include::partial$assemble/gradle/common-archive-options.adoc[]
 
@@ -380,6 +268,84 @@ include::partial$assemble/additional-files.adoc[]
 
 NOTE: This assembler ignores filtering artifacts by platform when `attachPlatform` is not enabled.
 
+== Matrix
+
+Parameterize archive generation with a set of key/value pairs. For example the following definitions are equivalent
+
+[source,yaml]
+.With matrix
+----
+matrix:
+  rows:
+    - { goos: darwin,  goarch: arm64, platform: osx-aarch_64     }
+    - { goos: darwin,  goarch: amd64, platform: osx-x86_64       }
+    - { goos: linux,   goarch: arm64, platform: linux-aarch_64   }
+    - { goos: linux,   goarch: amd64, platform: linux-x86_64     }
+    - { goos: windows, goarch: arm64, platform: windows-aarch_64 }
+    - { goos: windows, goarch: amd64, platform: windows-x86_64   }
+
+assemble:
+  archive:
+    helloworld:
+      active: ALWAYS
+      formats: [ ZIP ]
+      applyDefaultMatrix: true
+      archiveName: '{{distributionName}}-{{projectVersion}}-{{ matrix.goos }}-{{ matrix.goarch }}'
+      fileSets:
+        - input: 'target/{{ matrix.goos }}-{{ matrix.goarch }}'
+          output: 'bin'
+          includes: [ 'helloworld{.exe,}' ]
+        - input: '.'
+          includes: [ 'LICENSE' ]
+
+distributions:
+  helloworld:
+    executable:
+      windowsExtension: exe
+----
+
+[source,yaml]
+.Without matrix
+----
+assemble:
+  archive:
+    helloworld:
+      active: ALWAYS
+      formats: [ ZIP ]
+      attachPlatform: true
+      fileSets:
+        - input: 'target/{{ osPlatformReplaced }}'
+          output: 'bin'
+          includes: [ 'helloworld{.exe,}' ]
+        - input: '.'
+          includes: [ 'LICENSE' ]
+distributions:
+  helloworld:
+    executable:
+      windowsExtension: exe
+    artifacts:
+      - path: '{{artifactsDir}}/{{distributionName}}-{{projectVersion}}-darwin-arm64.zip'
+        platform: 'darwin-arm64'
+      - path: '{{artifactsDir}}/{{distributionName}}-{{projectVersion}}-darwin-amd64.zip'
+        platform: 'darwin-amd64'
+      - path: '{{artifactsDir}}/{{distributionName}}-{{projectVersion}}-windows-arm64.zip'
+        platform: 'windows-arm64'
+      - path: '{{artifactsDir}}/{{distributionName}}-{{projectVersion}}-windows-amd64.zip'
+        platform: 'windows-amd64'
+      - path: '{{artifactsDir}}/{{distributionName}}-{{projectVersion}}-linux-arm64.zip'
+        platform: 'linux-arm64'
+      - path: '{{artifactsDir}}/{{distributionName}}-{{projectVersion}}-linux-amd64.zip'
+        platform: 'linux-amd64'
+----
+
+=== Special keys
+
+The following keys have special meaning:
+
+[horizontal]
+platform:: Sets the platform for a matching archive.
+skip*:: Any properties with `skip` as prefix will be set as `extraProperties` in the matching archive.
+
 == Example
 
 Given the following file structure
diff --git a/docs/modules/reference/pages/assemble/jlink.adoc b/docs/modules/reference/pages/assemble/jlink.adoc
index 0808eb342..66cbb9540 100644
--- a/docs/modules/reference/pages/assemble/jlink.adoc
+++ b/docs/modules/reference/pages/assemble/jlink.adoc
@@ -70,6 +70,13 @@ include::partial$assemble/yaml/common-head.adoc[]
         - jdk.crypto.ec
         - jdk.localedata
 
+include::partial$matrix/yaml/matrix.adoc[indent=6]
+
+      # Define a pattern for parameterizable targetJdks
+      # icon:dot-circle[] icon:file-alt[]
+      targetJdkPattern:
+        path: path/to/jdk
+
       # List of JDKs for generating cross-platform images.
       # icon:dot-circle[] icon:file-alt[]
       targetJdks:
@@ -203,6 +210,12 @@ include::partial$assemble/toml/common-head.adoc[]
     "jdk.crypto.ec",
     "jdk.localedata"]
 
+include::partial$matrix/toml/matrix.adoc[]
+
+  # Define a pattern for parameterizable targetJdks
+  # icon:dot-circle[] icon:file-alt[]
+  targetJdkPattern.path = "path/to/jdk"
+
   # List of JDKs for generating cross-platform images.
   # icon:dot-circle[] icon:file-alt[]
   targetJdks = [
@@ -333,6 +346,14 @@ include::partial$assemble/json/common-head.adoc[]
           "jdk.localedata"
         ],
 
+include::partial$matrix/json/matrix.adoc[indent=8]
+
+        // Define a pattern for parameterizable targetJdks
+        // icon:dot-circle[] icon:file-alt[]
+        "targetJdkPattern": {
+          "path": "path/to/jdk"
+        },
+
         // List of JDKs for generating cross-platform images.
         // icon:dot-circle[] icon:file-alt[]
         "targetJdks": [
@@ -493,6 +514,16 @@ include::partial$assemble/maven/common-head.adoc[]
           <additionalModuleName>jdk.localedata</additionalModuleName>
         </additionalModuleNames>
 
+include::partial$matrix/maven/matrix.adoc[indent=8]
+
+        <!--
+          Define a pattern for parameterizable targetJdks
+          icon:dot-circle[] icon:file-alt[]
+        -->
+        <targetJdkPattern>
+          <path>path/to/jdk</path>
+        </targetJdkPattern>
+
         <!--
           List of JDKs for generating cross-platform images.
           icon:dot-circle[] icon:file-alt[]
@@ -668,6 +699,14 @@ include::partial$assemble/gradle/common-head.adoc[]
           'jdk.localedata'
         ]
 
+include::partial$matrix/gradle/matrix.adoc[indent=8]
+
+        // Define a pattern for parameterizable targetJdks
+        // icon:dot-circle[] icon:file-alt[]
+        targetJdkPattern {
+          path = 'path/to/jdk'
+        }
+
         // List of JDKs for generating cross-platform images.
         // icon:dot-circle[] icon:file-alt[]
         targetJdk {
@@ -812,6 +851,67 @@ default if left unspecified.
 
 include::partial$envvars-footer.adoc[]
 
+== Matrix
+
+Parameterize targetJdk resolution with a set of key/value pairs. For example the following definitions are equivalent
+
+[source,yaml]
+.With matrix
+----
+assemble:
+  jlink:
+    helloworld:
+      active: ALWAYS
+      imageName: '{{distributionName}}-{{projectVersion}}'
+      matrix:
+        rows:
+          - { platform: osx-aarch_64,      jdkdir: OsxArm,         filename: macosx_aarch64, suffix: '/zulu-17.jdk/Contents/Home' }
+          - { platform: osx-x86_64,        jdkdir: OsxIntel,       filename: macosx_x64,     suffix: '/zulu-17.jdk/Contents/Home' }
+          - { platform: linux_musl-x86_64, jdkdir: LinuxMuslIntel, filename: linux_musl_x64, suffix: '' }
+          - { platform: linux-x86_64,      jdkdir: LinuxIntel,     filename: linux_x64,      suffix: '' }
+          - { platform: linux-aarch_64,    jdkdir: LinuxArm,       filename: linux_aarch64,  suffix: '' }
+          - { platform: windows-x86_64,    jdkdir: WindowsIntel,   filename: win_x64,        suffix: '' }
+          - { platform: windows-aarch_64,  jdkdir: WindowsArm,     filename: win_aarch64,    suffix: '' }
+      targetJdkPattern:
+        path: '{{jdkPathPrefix}}/zulu17{{matrix.jdkdir}}/{{jdkFilePrefix}}-{{matrix.filename}}{{matrix.suffix}}'
+      mainJar:
+        path: 'target/{{distributionName}}-{{projectVersion}}.jar'
+----
+
+[source,yaml]
+.Without matrix
+----
+assemble:
+  jlink:
+    helloworld:
+      active: ALWAYS
+      imageName: '{{distributionName}}-{{projectVersion}}'
+      targetJdks:
+        - path: '{{jdkPathPrefix}}/zulu17OsxIntel/{{jdkFilePrefix}}-macosx_x64/zulu-17.jdk/Contents/Home'
+          platform: 'osx-x86_64'
+        - path: '{{jdkPathPrefix}}/zulu17OsxArm/{{jdkFilePrefix}}-macosx_aarch64/zulu-17.jdk/Contents/Home'
+          platform: 'osx-aarch_64'
+        - path: '{{jdkPathPrefix}}/zulu17LinuxIntel/{{jdkFilePrefix}}-linux_x64'
+          platform: 'linux-x86_64'
+        - path: '{{jdkPathPrefix}}/zulu17LinuxMuslIntel/{{jdkFilePrefix}}-linux_musl_x64'
+          platform: 'linux_musl-x86_64'
+        - path: '{{jdkPathPrefix}}/zulu17LinuxArm/{{jdkFilePrefix}}-linux_aarch64'
+          platform: 'linux-aarch_64'
+        - path: '{{jdkPathPrefix}}/zulu17WindowsIntel/{{jdkFilePrefix}}-win_x64'
+          platform: 'windows-x86_64'
+        - path: '{{jdkPathPrefix}}/zulu17WindowsArm/{{jdkFilePrefix}}-win_aarch64'
+          platform: 'windows-aarch_64'
+      mainJar:
+        path: 'target/{{distributionName}}-{{projectVersion}}.jar'
+----
+
+=== Special keys
+
+The following keys have special meaning:
+
+[horizontal]
+platform:: Sets the platform for a matching JDK.
+
 == JDKs
 
 You may specify a value for both `jdk` and `targetJdks`, either, or none. The following rules apply when resolving which
diff --git a/docs/modules/reference/pages/assemble/native-image.adoc b/docs/modules/reference/pages/assemble/native-image.adoc
index 74b0ab30c..144368c93 100644
--- a/docs/modules/reference/pages/assemble/native-image.adoc
+++ b/docs/modules/reference/pages/assemble/native-image.adoc
@@ -52,6 +52,13 @@ include::partial$assemble/yaml/common-head.adoc[]
       # icon:dot-circle[]
       archiveFormat: TGZ
 
+include::partial$matrix/yaml/matrix.adoc[indent=6]
+
+      # Define a pattern for parameterizable graalJdks
+      # icon:dot-circle[] icon:file-alt[]
+      graalJdkPattern:
+        path: path/to/jdk
+
       # List of Graal JDKs.
       # icon:dot-circle[] icon:file-alt[]
       graalJdks:
@@ -151,6 +158,12 @@ include::partial$assemble/toml/common-head.adoc[]
   # icon:dot-circle[]
   archiveFormat = "TGZ"
 
+include::partial$matrix/toml/matrix.adoc[]
+
+  # Define a pattern for parameterizable graalJdks
+  # icon:dot-circle[] icon:file-alt[]
+  graalJdkPattern.path = "path/to/jdk"
+
   # List of Graal JDKs.
   # icon:dot-circle[] icon:file-alt[]
   graalJdks = [
@@ -242,6 +255,14 @@ include::partial$assemble/json/common-head.adoc[]
         // icon:dot-circle[]
         "archiveFormat": "TGZ",
 
+include::partial$matrix/json/matrix.adoc[indent=8]
+
+        // Define a pattern for parameterizable graalJdks
+        // icon:dot-circle[] icon:file-alt[]
+        "graalJdkPattern": {
+          "path": "path/to/jdk"
+        },
+
         // List of Graal JDKs.
         // icon:dot-circle[] icon:file-alt[]
         "graalJdks": [
@@ -357,6 +378,16 @@ include::partial$assemble/maven/common-head.adoc[]
         -->
         <archiveFormat>TGZ</archiveFormat>
 
+include::partial$matrix/maven/matrix.adoc[indent=8]
+
+        <!--
+          Define a pattern for parameterizable graalJdks
+          icon:dot-circle[] icon:file-alt[]
+        -->
+        <graalJdkPattern>
+          <path>path/to/jdk</path>
+        </graalJdkPattern>
+
         <!--
           List of Graal JDKs.
           icon:dot-circle[] icon:file-alt[]
@@ -498,6 +529,14 @@ include::partial$assemble/gradle/common-head.adoc[]
         // icon:dot-circle[]
         archiveFormat = 'TGZ'
 
+include::partial$matrix/gradle/matrix.adoc[indent=8]
+
+        // Define a pattern for parameterizable graalJdks
+        // icon:dot-circle[] icon:file-alt[]
+        graalJdkPattern {
+          path = 'path/to/jdk'
+        }
+
         // List of Graal JDKs.
         // icon:dot-circle[] icon:file-alt[]
         graalJdk {
@@ -580,6 +619,58 @@ include::partial$named-envvars/active.adoc[]
 
 include::partial$envvars-footer.adoc[]
 
+== Matrix
+
+Parameterize graalJdk resolution with a set of key/value pairs. For example the following definitions are equivalent
+
+[source,yaml]
+.With matrix
+----
+assemble:
+  nativeImage:
+    helloworld:
+      active: ALWAYS
+      imageName: '{{distributionName}}-{{projectEffectiveVersion}}'
+      matrix:
+        rows:
+          - { platform: osx-aarch_64,   suffix: OsxArm,       dir: '/Contents/Home' }
+          - { platform: osx-x86_64,     suffix: OsxIntel,     dir: '/Contents/Home' }
+          - { platform: linux-x86_64,   suffix: LinuxIntel,   dir: '' }
+          - { platform: windows-x86_64, suffix: WindowsIntel, dir: '' }
+      graalJdkPattern:
+        path: '{{jdkPathPrefix}}/graalvm22{{matrix.suffix}}/{{graalFilePrefix}}{{matrix.dir}}'
+      mainJar:
+        path: 'target/{{distributionName}}-{{projectVersion}}.jar'
+----
+
+[source,yaml]
+.Without matrix
+----
+assemble:
+  nativeImage:
+    helloworld:
+      active: ALWAYS
+      imageName: '{{distributionName}}-{{projectEffectiveVersion}}'
+      mainJar:
+        path: 'target/{{distributionName}}-{{projectVersion}}.jar'
+      graalJdks:
+        - path: '{{jdkPathPrefix}}/graalvm22OsxIntel/{{graalFilePrefix}}/Contents/Home'
+          platform: 'osx-x86_64'
+        - path: '{{jdkPathPrefix}}/graalvm22OsxArm/{{graalFilePrefix}}/Contents/Home'
+          platform: 'osx-aarch_64'
+        - path: '{{jdkPathPrefix}}/graalvm22LinuxIntel/{{graalFilePrefix}}'
+          platform: 'linux-x86_64'
+        - path: '{{jdkPathPrefix}}/graalvm22WindowsIntel/{{graalFilePrefix}}'
+          platform: 'windows-x86_64'
+----
+
+=== Special keys
+
+The following keys have special meaning:
+
+[horizontal]
+platform:: Sets the platform for a matching JDK.
+
 == Graal JDKs
 
 The following rules apply when resolving which Graal JDK will be used to generate native image executables:
diff --git a/docs/modules/reference/pages/distributions.adoc b/docs/modules/reference/pages/distributions.adoc
index 816b292c6..f40251c0a 100644
--- a/docs/modules/reference/pages/distributions.adoc
+++ b/docs/modules/reference/pages/distributions.adoc
@@ -94,6 +94,13 @@ distributions:
         x86_64: amd64
         linux_musl: alpine
 
+include::partial$matrix/yaml/matrix.adoc[indent=4]
+
+    # Define a pattern for parameterizable artifacts
+    # icon:dot-circle[] icon:file-alt[]
+    artifactPattern:
+      path: path/to/archive
+
     # A list of artifacts.
     # At least on entry must be present.
     # icon:exclamation-triangle[] icon:file-alt[]
@@ -202,6 +209,12 @@ TOML::
     x86_64 = "amd64"
     linux_musl = "alpine"
 
+include::partial$matrix/toml/matrix.adoc[]
+
+  # Define a pattern for parameterizable artifacts
+  # icon:dot-circle[] icon:file-alt[]
+  artifactPattern.path = "path/to/archive"
+
   # A list of artifacts.
   # At least on entry must be present.
   # icon:exclamation-triangle[] icon:file-alt[]
@@ -318,6 +331,14 @@ JSON::
         }
       },
 
+include::partial$matrix/json/matrix.adoc[indent=6]
+
+      // Define a pattern for parameterizable artifacts
+      // icon:dot-circle[] icon:file-alt[]
+      "artifactPattern": {
+        "path": "path/to/archive"
+      },
+
       // A list of artifacts.
       // At least on entry must be present.
       // icon:exclamation-triangle[] icon:file-alt[]
@@ -479,6 +500,16 @@ Maven::
         </replacements>
       </platform>
 
+include::partial$matrix/maven/matrix.adoc[indent=6]
+
+      <!--
+        Define a pattern for parameterizable artifacts
+        icon:dot-circle[] icon:file-alt[]
+      -->
+      <artifactPattern>
+        <path>path/to/archive</path>
+      </artifactPattern>
+
       <!--
         A list of artifacts.
         At least on entry must be present.
@@ -626,6 +657,14 @@ jreleaser {
         ]
       }
 
+include::partial$matrix/gradle/matrix.adoc[indent=6]
+
+      // Define a pattern for parameterizable artifacts
+      // icon:dot-circle[] icon:file-alt[]
+      artifactPattern {
+        path = 'path/to/jdk'
+      }
+
       // A list of artifacts.
       // At least on entry must be present.
       // icon:exclamation-triangle[] icon:file-alt[]
@@ -697,3 +736,49 @@ include::partial$envvars-header.adoc[]
 |===
 
 include::partial$envvars-footer.adoc[]
+
+== Matrix
+
+Parameterize artifact resolution with a set of key/value pairs. For example the following definitions are equivalent
+
+[source,yaml]
+.With matrix
+----
+matrix:
+  rows:
+    - { platform: osx-aarch_64 }
+    - { platform: osx-x86_64   }
+    - { platform: linux-x86_64 }
+
+distributions:
+  helloworld:
+    executable:
+      windowsExtension: exe
+    applyDefaultMatrix: true
+    artifactPattern:
+      path: '{{artifactsDir}}/{{distributionName}}-{{projectVersion}}-{{matrix.platform}}.zip'
+----
+
+[source,yaml]
+.Without matrix
+----
+distributions:
+  helloworld:
+    executable:
+      windowsExtension: exe
+    artifacts:
+      - path: '{{artifactsDir}}/{{distributionName}}-{{projectVersion}}-osx-aarch_64.zip'
+        platform: 'osx-aarch_64'
+      - path: '{{artifactsDir}}/{{distributionName}}-{{projectVersion}}-osx-x86_64.zip'
+        platform: 'osx-x86_64'
+      - path: '{{artifactsDir}}/{{distributionName}}-{{projectVersion}}-linux-x86_64.zip'
+        platform: 'linux-x86_64'
+----
+
+=== Special keys
+
+The following keys have special meaning:
+
+[horizontal]
+platform:: Sets the platform for the artifact.
+extraProperties.*:: Any properties with `extraProperties.` as prefix will be set as `extraProperties` in the matching artifact.
diff --git a/docs/modules/reference/partials/matrix/gradle/matrix.adoc b/docs/modules/reference/partials/matrix/gradle/matrix.adoc
new file mode 100644
index 000000000..4e043b860
--- /dev/null
+++ b/docs/modules/reference/partials/matrix/gradle/matrix.adoc
@@ -0,0 +1,17 @@
+  // Includes the default matrix.
+  // icon:dot-circle[]
+  applyDefaultMatrix = false
+
+  // Configures matrix variables.
+  // icon:dot-circle[]
+  matrix {
+    variable('os', ['linux', 'osx', 'windows'])
+    variable('arch', ['arm64', 'amd64'])
+
+    row(os: 'linux', arch: 'arm64')
+    row(os: 'linux', arch: 'amd64')
+    row(os: 'osx', arch: 'arm64')
+    row(os: 'osx', arch: 'amd64')
+    row(os: 'windows', arch: 'arm64')
+    row(os: 'windows', arch: 'amd64')
+  }
\ No newline at end of file
diff --git a/docs/modules/reference/partials/matrix/json/matrix.adoc b/docs/modules/reference/partials/matrix/json/matrix.adoc
new file mode 100644
index 000000000..e6a5c596b
--- /dev/null
+++ b/docs/modules/reference/partials/matrix/json/matrix.adoc
@@ -0,0 +1,20 @@
+  // Includes the default matrix.
+  // icon:dot-circle[]
+  "applyDefaultMatrix": false,
+
+  // Configures matrix variables.
+  // icon:dot-circle[]
+  "matrix": {
+    "vars": {
+      "os": [ "linux", "osx", "windows" ],
+      "arch": [ "arm64", "amd64" ]
+    },
+    "rows": [
+      { "os": "linux", "arch": "arm64" },
+      { "os": "linux", "arch": "amd64" },
+      { "os": "osx", "arch": "arm64" },
+      { "os": "osx", "arch": "amd64" },
+      { "os": "windows", "arch": "arm64" },
+      { "os": "windows", "arch": "amd64" }
+    ]
+  },
\ No newline at end of file
diff --git a/docs/modules/reference/partials/matrix/maven/matrix.adoc b/docs/modules/reference/partials/matrix/maven/matrix.adoc
new file mode 100644
index 000000000..818be77f7
--- /dev/null
+++ b/docs/modules/reference/partials/matrix/maven/matrix.adoc
@@ -0,0 +1,49 @@
+  <!--
+    Includes the default matrix.
+    icon:dot-circle[]
+  -->
+  <applyDefaultMatrix>false</applyDefaultMatrix>
+
+  <!--
+    Configures matrix variables.
+    icon:dot-circle[]
+  -->
+  <matrix>
+    <vars>
+      <os>
+        <e>linux</e>
+        <e>osx</e>
+        <e>windows</e>
+      </os>
+      <arch>
+        <e>arm64</e>
+        <e>amd64</e>
+      </arch>
+    </vars>
+    <rows>
+      <row>
+        <os>linux</os>
+        <arch>arm64</arch>
+      </row>
+      <row>
+        <os>linux</os>
+        <arch>amd64</arch>
+      </row>
+      <row>
+        <os>osx</os>
+        <arch>arm64</arch>
+      </row>
+      <row>
+        <os>osx</os>
+        <arch>amd64</arch>
+      </row>
+      <row>
+        <os>windows</os>
+        <arch>arm64</arch>
+      </row>
+      <row>
+        <os>windows</os>
+        <arch>amd64</arch>
+      </row>
+    </rows>
+  </matrix>
\ No newline at end of file
diff --git a/docs/modules/reference/partials/matrix/toml/matrix.adoc b/docs/modules/reference/partials/matrix/toml/matrix.adoc
new file mode 100644
index 000000000..0a9072167
--- /dev/null
+++ b/docs/modules/reference/partials/matrix/toml/matrix.adoc
@@ -0,0 +1,14 @@
+  # Includes the default matrix.
+  # icon:dot-circle[]
+  applyDefaultMatrix = false
+
+  # Configures matrix variables.
+  # icon:dot-circle[]
+  matrix.vars.os = [ "linux", "osx", "windows" ]
+  matrix.vars.arch= [ "arm64", "amd64" ]
+  rows = [{ os = "linux", arch = "arm64" },
+          { os = "linux", arch = "amd64" },
+          { os = "osx", arch = "arm64" },
+          { os = "osx", arch = "amd64" },
+          { os = "windows", arch = "arm64" },
+          { os = "windows", arch = "amd64" }]
\ No newline at end of file
diff --git a/docs/modules/reference/partials/matrix/yaml/matrix.adoc b/docs/modules/reference/partials/matrix/yaml/matrix.adoc
new file mode 100644
index 000000000..0898fa8f4
--- /dev/null
+++ b/docs/modules/reference/partials/matrix/yaml/matrix.adoc
@@ -0,0 +1,17 @@
+  # Includes the default matrix.
+  # icon:dot-circle[]
+  applyDefaultMatrix: false
+
+  # Configures matrix variables.
+  # icon:dot-circle[]
+  matrix:
+    vars:
+      os: [ linux, osx, windows ]
+      arch: [ arm64, amd64 ]
+    rows:
+      - { os: linux, arch: arm64 }
+      - { os: linux, arch: amd64 }
+      - { os: osx, arch: arm64 }
+      - { os: osx, arch: amd64 }
+      - { os: windows, arch: arm64 }
+      - { os: windows, arch: amd64 }
\ No newline at end of file