Skip to content

Commit

Permalink
Document matrix updates
Browse files Browse the repository at this point in the history 
Relates to jreleaser/jreleaser#1780
Relates to jreleaser/jreleaser#1782
Relates to jreleaser/jreleaser#1783
  • Loading branch information
@aalmiray
aalmiray committed Jan 9, 2025
1 parent 582f1e0 commit 70a8b9b
Show file tree
Hide file tree
Showing 9 changed files with 476 additions and 117 deletions.
200 changes: 83 additions & 117 deletions docs/modules/reference/pages/assemble/archive.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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[]
Expand Down Expand Up @@ -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[]
Expand Down Expand Up @@ -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[]
Expand Down Expand Up @@ -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[]
Expand Down Expand Up @@ -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[]
Expand Down Expand Up @@ -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
Expand Down
100 changes: 100 additions & 0 deletions docs/modules/reference/pages/assemble/jlink.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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 = [
Expand Down Expand Up @@ -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": [
Expand Down Expand Up @@ -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[]
Expand Down Expand Up @@ -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 {
Expand Down Expand Up @@ -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
Expand Down
Loading

0 comments on commit 70a8b9b

Please sign in to comment.