# Handling of platform streams
Following note is to outline the various ways users/developers
can specify which version of Quarkus platform to use in cli/plugin scenarios.
CLI, maven, or gradle syntax will be specified where relevant.
Note: Current platform functionallity is documented at https://quarkus.io/guides/platform and https://quarkus.io/guides/maven-tooling
## Registry/Defaults
A registry has a list of platforms (identifed by a key). Each platform can define one or more streams, and each stream can define one or more platform releases.
The ordering of elements is significant. The first listed platform will be treated as the default. The default stream is deduced from the platform (the first listed), and the recommended/default platform release is defined by the stream (the first listed).
In `.quarkus/config.yaml` or `~/.quarkus/config.yaml` you can set it up for following scenarios:
* Community first, but access to RHBQ
```
registries:
- registry.quarkus.io
- registry.quarkus.redhat.com
```
* RHBQ only
```
- registry.quarkus.redhat.com
```
* Acme, then RHBQ:
```
registries:
- registry.quarkus.acme.org
- registry.quarkus.redhat.com
```
The hard-coded default registry, used when no other configuration is found, is `registry.quarkus.io`.
### Specifying streams
Streams are identified using `platformKey:streamId` syntax (1..n to platform release):
* `io.quarkus.platform:999-SNAPSHOT`
* `com.redhat.quarkus.platform:1.11`
* `org.acme:24.0.1`
A specific stream can be specified using `-S platformKey:streamId`. When specifying a stream, leave empty segments where you want to use _discovered_ defaults.
For example, to specify the streams listed above:
* `io.quarkus.platform:999-SNAPSHOT`
* `-S 999-SNAPSHOT` OR `-S :999-SNAPSHOT`
Search for a `999-SNAPSHOT` stream, starting with the first platform listed in the first registry (probably `registry.quarkus.io`). Iterate through each discovered platform and use platform releases from the first discovered `999-SNAPSHOT` stream.
* `-S io.quarkus.platform:999-SNAPSHOT`
Search for platforms called `io.quarkus.platform`, starting with the first registry in the list. Iterate through each matching platform, and use platform releases from the first discovered `999-SNAPSHOT` stream.
* `com.redhat.quarkus.platform:1.11`
* `-S com.redhat.quarkus.platform:`
Search for platforms called `com.redhat.quarkus.platform`, starting with the first registry in the list. Use platform releases defined by the first stream listed in the first matching platform.
* `-S com.redhat.quarkus.platform:1.11`
Search for platforms called `com.redhat.quarkus.platform`, starting with the first registry in the list. Iterate through each matching platform, and look for a `1.11` stream. Use the platform releases defined by the first matching stream.
* `org.acme:24.0.1`
* `-S org.acme:`
Search for platforms called `org.acme`, starting with the first registry in the list. Use platform releases defined by the first stream listed in the first matching platform.
* `-S org.acme:24.0.1`
Search for platforms called `org.acme`, starting with the first registry in the list. Iterate through each matching platform, and look for a `24.0.1` stream. Use the platform releases defined by the first matching stream.
### Specifying platform releases
Platform releases are artifacts published in a maven repository, and
are identified using `groupId:artifactId:version` (GAV) syntax:
* `io.quarkus:quarkus-bom:999-SNAPSHOT`
* `com.redhat.quarkus:quarkus-bom:1.11.6.Final-redhat-00001`
* `com.redhat.quarkus:quarkus-universe-bom:1.11.6.Final-redhat-00001`
A specific platform release can be specified using `-P groupId:artifactId:version`. When specifying a platform release, leave empty segments where you want to use defaults (groupId: `io.quarkus`, artifactId: `quarkus-bom`, version: cli or tool version).
For example, to specify the platform releases listed above:
* `io.quarkus:quarkus-bom:999-SNAPSHOT`
* use default groupId and artifactId: `-P 999-SNAPSHOT`
* use default groupId and artifactId: `-P ::999-SNAPSHOT`
* use default groupId: `-P :quarkus-bom:999-SNAPSHOT`
* use default artifactId: `-P io.quarkus::999-SNAPSHOT`
* `-P io.quarkus:quarkus-bom:999-SNAPSHOT`
* `com.redhat.quarkus:quarkus-bom:1.11.6.Final-redhat-00001`
* use default artifactId:`-P com.redhat.quarkus::1.11.6.Final-redhat-00001`
* `-P com.redhat.quarkus:quarkus-bom:1.11.6.Final-redhat-00001`
* `com.redhat.quarkus:quarkus-universe-bom:1.11.6.Final-redhat-00001`
* `-P com.redhat.quarkus:quarkus-universe-bom:1.11.6.Final-redhat-00001`
## Registry Structure
A registry conceptually has a list of platforms, with streams and specific versioned platform releases. Below is the full model for a registry which has additional data like extensions and extensions releases.
```plantuml
@startuml
class Platform {
+ String platformKey
+ String name
+ Map<String,Object> metadata
+ boolean isDefault
}
class PlatformStream {
+ String streamKey
+ String name
+ Map<String,Object> metadata
}
class PlatformRelease {
+ String version
- String versionSortable
+ String quarkusCoreVersion
+ String upstreamQuarkusCoreVersion
+ List<String> memberBoms
+ Map<String,Object> metadata
}
class PlatformExtension {
+ Map<String,Object> metadata
}
class Extension {
+ String groupId
+ String artifactId
+ String name
+ String description
}
class ExtensionRelease {
+ String version
- String versionSortable
+ Map<String,Object> metadata
+ String quarkusCore
}
class Category {
+ String name
+ String description
+ Map<String,Object> metadata
}
class ExtensionReleaseCompatibility {
+ String quarkusCoreVersion
+ boolean compatible
}
note right of PlatformRelease::memberBoms
This is stored as a JSON array
end note
Platform *-- PlatformStream
PlatformStream *-- PlatformRelease
PlatformRelease *-- PlatformExtension
Extension *-- ExtensionRelease
ExtensionRelease o-- PlatformExtension
ExtensionRelease <-- ExtensionReleaseCompatibility
@enduml
```
Note: The registry top-level entity is called a "platform", while a *specific* versioned release of a platform is a "platform release". Sometimes "platform" is used in conversation instead of "platform release" (because humans). Just remember that when you are working with a specific published/versioned artifact, you are working either with a platform release.
Example below:
* platform: io.quarkus.platform
* stream: io.quarkus.platform:2.0
* (latest) platform-release & member: io.quarkus.platform:quarkus-bom:2.0.1.Final
* member: io.quarkus.platform:quarkus-kogito-bom:2.0.1.Final
* member: io.quarkus.platform:quarkus-camel-bom:2.0.1.Final
* platform-release & member: io.quarkus.platform:quarkus-bom:2.0.0.Final
* member: io.quarkus.platform:quarkus-kogito-bom:2.0.0.Final
* platform-release & member: io.quarkus.platform:quarkus-bom:2.0.10.Final
* member: io.quarkus.platform:quarkus-kogito-bom:2.0.10.Final
* member: io.quarkus.platform:quarkus-camel-bom:2.0.10.Final
* stream: io.quarkus.platform:1.11
* (latest) platform-release & member: io.quarkus.platform:quarkus-bom:1.11.1.Final
* member: io.quarkus.platform:quarkus-kogito-bom:1.11.1.Final
* member: io.quarkus.platform:quarkus-camel-bom:1.11.1.Final
* platform-release & member: io.quarkus.platform:quarkus-bom:1.11.0.Final
* member (bom): io.quarkus.platform:quarkus-kogito-bom:1.11.0.Final
* [.json]
* [.properties]
* member: io.quarkus.platform:quarkus-camel-bom:1.11.0.Final
* member: io.quarkus.platform:quarkus-camel-bom:1.11.0.Final
* platform: org.acme.platform
* stream: org.acme.platform:24.0
* platform-release & member: io.quarkus.platform:quarkus-bom:2.0.0.Final
* member: org.acme.io.quarkus.platform:quarkus-kogito-bom:2.0.0.Final
* member: org.acme.io.quarkus.platform:quarkus-camel-bom:2.0.0.Final
* member: org.acme.platform:quarkus-acme-bom:24.0.0.Final
rhbq registry:
* platform: com.redhat.quarkus.platform
* stream: com.redhat.quarkus.platform:2.0
* platform-release & member: com.redhat.quarkus.platform:quarkus-bom:2.0.0.Final
* member: com.redhat.quarkus.platform:quarkus-kogito-bom:2.0.0.Final
* member: com.redhat.quarkus.platform:quarkus-camel-bom:2.0.0.Final
* platform-release & member: com.redhat.quarkus.platform:quarkus-bom:2.0.1.Final
* member: com.redhat.quarkus.platform:quarkus-kogito-bom:2.0.1.Final
* member: com.redhat.quarkus.platform:quarkus-camel-bom:2.0.1.Final
* platform-release & member: com.redhat.quarkus.platform:quarkus-bom:2.0.2.Final
* member: com.redhat.quarkus.platform:quarkus-kogito-bom:2.0.2.Final
* member: com.redhat.quarkus.platform:quarkus-camel-bom:2.0.2.Final
## Default/90% experience:
* Creating a project: `quarkus create`
Logically translates via defaults from `registry.quarkus.io` to:
`quarkus create -S io.quarkus.platform:2.0`
which maps to:
`quarkus create -P io.quarkus:quarkus-bom:2.0.1.Final`
* Create a project using specific stream: `quarkus create -S 1.11`
Translates to:
`quarkus create -S io.quarkus.platform:1.11`
which maps to:
`quarkus create -P io.quarkus:quarkus-bom:1.11.1.Final`
* Imagine an RHBQ setup:
```
quarkus config set registries registry.quarkus.redhat.com,registry.quarkus.io
```
Then create a basic app using kogito:
```
quarkus create kogito
```
This would use the defaults from `registry.quarkus.redhat.com`. The above might map to:
`quarkus create -S com.redhat.quarkus.platform:2.0.2.Final`
which would in turn map to:
`quarkus create -P com.redhat.quarkus.platform:quarkus-kogito-bom:2.0.2.Final`
## Create
| Use case | Pre-stream tooling | 2.x tooling |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ---------------- |
| Default project create (latest) | `quarkus create` | `quarkus create` |
| Use specific RHBQ | `quarkus create --pg=com.redhat.quarkus --pv 1.11.6.Final-redhat-00001` | `quarkus create -S com.redhat.quarkus.platform:1.11` |
| Use preferred RHBQ | N/A | `quarkus create -S com.redhat.quarkus.platform:` |
| Use a specific core platform | `quarkus create --pg com.redhat.quarkus --pa quarkus-universe-bom --pv 1.11.6.Final-redhat-00001`| `quarkus create -P com.redhat.quarkus:quarkus-kogito-bom:1.11.6.Final-redhat-00001` |
| Use an explicit platform version | `quarkus create --pg=io.quarkus --pa=quarkus-bom --pv=999-SNAPSHOT` | `quarkus create -P io.quarkus:quarkus-bom:999-SNAPSHOT` |
## Listing
Just using `quarkus list` as example here - adding/removing could technically also support these flags but it would result in project on disk being possibly inconsistent.
| Use case | Pre-stream tooling | 2.x tooling |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ---------------- |
| Default project list. Resolves from on disk chosen platform boms | `quarkus ext list` | `quarkus ext list` |
| List from platform release not in a stream | N/A | `quarkus ext list -P 999-SNAPSHOT` |
| List from other platform than on disk, i.e. rhbq | N/A | `quarkus ext list -S com.redhat.quarkus.platform:` |
| Use a specific core platform | N/A | `quarkus ext list -P com.redhat.quarkus.platform::1.11.6.Final-redhat-00001` |
## IDE's
today they use latest/greatest... would say we suggest they
add a stream selector but otherwise tell people to use cli for very explicit control ?
## Offline
offline without access to either registry or maven repo = none of this works. Use manual creation.
offline without access to registry but have maven repo = could explicit platform reference work as done today ?
offline without access to registry, have maven repo but did download data from registry before offline = falls back to what is cached locally ? (where is that cache and how does it work when using just gradle?)
## Building
| Use case | Single/Universe Platform | Platform Streams with multiple boms |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ---------------- |
| Default build | `mvn package` | `mvn package` |
| Use an alternate explicit platform version | `mvn package -DplatformGroupId=io.quarkus -DplatformArtifactId=quarkus-bom -DplatformVersionId=999-SNAPSHOT` | | should be same, but platformArtifactId only applied to the first core platform
Sign in with Wallet
Connect another wallet