-
Notifications
You must be signed in to change notification settings - Fork 2.5k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #26822 from gsmet/2.11.0-backports-1
2.11.0 backports 1
- Loading branch information
Showing
46 changed files
with
1,037 additions
and
430 deletions.
There are no files selected for viewing
Large diffs are not rendered by default.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,170 @@ | ||
//// | ||
This guide is maintained in the main Quarkus repository | ||
and pull requests should be submitted there: | ||
https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc | ||
//// | ||
= Quarkus Extension Metadata | ||
|
||
include::./attributes.adoc[] | ||
|
||
Quarkus extensions are distributed as Maven JAR artifacts that application and other libraries may depend on. When a Quarkus application project is built, tested or edited using the Quarkus dev tools, Quarkus extension JAR artifacts will be identified on the application classpath by the presence of the Quarkus extension metadata files in them. | ||
This document describes the purpose of each Quarkus extension metadata file and its content. | ||
|
||
[[quarkus-extension-yaml]] | ||
== META-INF/quarkus-extension.yaml | ||
|
||
Every **runtime** extension artifact **must** include this file. This file is used by Quarkus dev tools when displaying information about an extension, creating a new project or adding extensions to an existing project, etc. This file isn't used at application build or bootstrap times. | ||
The basic and required metadata included in this file can be generated by the Quarkus Maven and Gradle plugins when the extension artifact is built. However, typically, extension authors will want to provide more information about the extension to the Quarkus dev tools and users. The extra information could be provided | ||
in a template `META-INF/quarkus-extension.yaml` found in the extension runtime module's resources directory, e.g. `src/main/resources/META-INF/quarkus-extension.yaml`. Here is an example of such a template for the `quarkus-resteasy-reactive` extension: | ||
|
||
[source,yaml,subs=attributes+] | ||
---- | ||
name: "RESTEasy Reactive" <1> | ||
artifact: ${project.groupId}:${project.artifactId}:${project.version} <2> | ||
metadata: | ||
short-name: "resteasy-reactive" <3> | ||
keywords: <4> | ||
- "jaxrs" | ||
- "web" | ||
- "rest" | ||
categories: <5> | ||
- "web" | ||
- "reactive" | ||
status: "stable" <6> | ||
guide: "https://quarkus.io/guides/resteasy-reactive" <7> | ||
codestart: <8> | ||
name: "resteasy-reactive" | ||
languages: | ||
- "java" | ||
- "kotlin" | ||
- "scala" | ||
artifact: "io.quarkus:quarkus-project-core-extension-codestarts" | ||
config: <9> | ||
- "quarkus.resteasy-reactive." | ||
---- | ||
|
||
<1> Extension name displayed to users | ||
<2> Extension runtime artifact expression that will be replaced with the actual coordinates during the build, this field could be omitted | ||
<3> Short name that could be used to quickly locate an extension in the catalog of extensions provided by the dev tools to the users | ||
<4> Keywords that can be used to search for extensions in the extension catalog provided by the dev tools to the users | ||
<5> Categories the extension should appear under on https://code.quarkus.io[code.quarkus.io]. This field can be omitted, the extension will still be listed on https://code.quarkus.io[code.quarkus.io] but won't be categorized | ||
<6> Maturity status that could be `stable`, `preview`, `experimental`. It is up to extension maintainers to evaluate the maturity status and communicate it to the users | ||
<7> Link to the extension guide or documentation page | ||
<8> https://quarkus.io/guides/extension-codestart[Codestart] information | ||
<9> Configuration prefix | ||
|
||
And here is the final version of the file included in the runtime JAR augmented with other information collected by the Quarkus Maven plugin: | ||
|
||
[source,yaml,subs=attributes+] | ||
---- | ||
name: "RESTEasy Reactive" | ||
artifact: "io.quarkus:quarkus-resteasy-reactive:999-SNAPSHOT" | ||
metadata: | ||
short-name: "resteasy-reactive" | ||
keywords: | ||
- "jaxrs" | ||
- "web" | ||
- "rest" | ||
categories: | ||
- "web" | ||
- "reactive" | ||
status: "stable" | ||
guide: "https://quarkus.io/guides/resteasy-reactive" | ||
codestart: | ||
name: "resteasy-reactive" | ||
languages: | ||
- "java" | ||
- "kotlin" | ||
- "scala" | ||
artifact: "io.quarkus:quarkus-project-core-extension-codestarts::jar:999-SNAPSHOT" | ||
config: | ||
- "quarkus.resteasy-reactive." | ||
built-with-quarkus-core: "999-SNAPSHOT" <1> | ||
capabilities: <2> | ||
provides: | ||
- "io.quarkus.rest" | ||
- "io.quarkus.resteasy.reactive" | ||
extension-dependencies: <3> | ||
- "io.quarkus:quarkus-resteasy-reactive-common" | ||
- "io.quarkus:quarkus-mutiny" | ||
- "io.quarkus:quarkus-smallrye-context-propagation" | ||
- "io.quarkus:quarkus-vertx" | ||
- "io.quarkus:quarkus-arc" | ||
- "io.quarkus:quarkus-netty" | ||
- "io.quarkus:quarkus-vertx-http" | ||
- "io.quarkus:quarkus-core" | ||
- "io.quarkus:quarkus-jsonp" | ||
description: "A JAX-RS implementation utilizing build time processing and Vert.x.\ | ||
\ This extension is not compatible with the quarkus-resteasy extension, or any of\ | ||
\ the extensions that depend on it." <4> | ||
---- | ||
|
||
<1> Quarkus version the extension was built with | ||
<2> https://quarkus.io/guides/capabilities[Capabilities] this extension provides | ||
<3> Direct dependencies on other extensions | ||
<4> Description that can be displayed to users. In this case, the description was copied from the `pom.xml` of the extension module but it could also be provided in the template file. | ||
|
||
[[quarkus-extension-properties]] | ||
== META-INF/quarkus-extension.properties | ||
|
||
Every **runtime** extension artifact **must** include this file. This file is read by the Quarkus bootstrap mechanism and is meant to contain only the information that is relevant for **building or bootstrapping** an applications. This file is typically generated by the corresponding Quarkus Maven or Gradle plugin when the extension project is built and shouldn't be edited manually. | ||
The following properties may appear in this file: | ||
|
||
[cols=3*,options="header"] | ||
|=== | ||
| Name | ||
| Presence | ||
| Description | ||
|
||
| `deployment-artifact` | ||
| Required | ||
| Points to the corresponding extension deployment artifact in the `groupId:artifactId[:classifier:type]:version` format | ||
|
||
| `parent-first-artifacts` | ||
| Optional | ||
| Comma-separated list of artifact keys (`groupId:artifactId:classifier:type`) that are to be loaded in a parent first manner. This can be used to work around issues where a given class needs to be loaded by the system ClassLoader. | ||
|
||
| `runner-parent-first-artifacts` | ||
| Optional | ||
| Comma-separated list of artifact keys that are to be loaded in a parent first manner in addition to those configured with `parent-first-artifacts` when an application is launched from a production binary package. This can be used to work around issues where a given class needs to be loaded by the system ClassLoader. | ||
|
||
| `excluded-artifacts` | ||
| Optional | ||
| Comma-separated list of artifact keys that will never be loaded by the class loader, and will not be packed into the final application. | ||
|
||
| `lesser-priority-artifacts` | ||
| Optional | ||
| Comma-separated list of artifact keys that will only be used to load a class or resource if no other artifact containing that class or resource exists. This is used in order to control the order of artifacts when multiple contain the same classes. | ||
|
||
| `removed-resources.*` | ||
| Optional | ||
| Resources that should be removed/hidden from dependencies. This allows for classes and other resources to be removed from dependencies, so they are not accessible to the application. This is a map of artifact key to a comma-separated list of resources to be removed. When running in dev and test mode these resources are hidden from the ClassLoader, when running in production mode these files are removed from the jars that contain them. Note that if you want to remove a class you need to specify the class file name. e.g. to remove com.acme.Foo you would specify com/acme/Foo.class. | ||
|
||
| `provides-capabilities` | ||
| Optional | ||
| List of https://quarkus.io/guides/capabilities[capabilities] this extension provides | ||
|
||
| `requires-capabilities` | ||
| Optional | ||
| List of https://quarkus.io/guides/capabilities[capabilities] this extension requires to be provided by other Quarkus extensions | ||
|
||
| `conditional-dependencies` | ||
| Optional | ||
| List of https://quarkus.io/guides/conditional-extension-dependencies[conditional dependencies] this extension declares | ||
|
||
| `dependency-condition` | ||
| Optional | ||
| https://quarkus.io/guides/conditional-extension-dependencies[Dependency condition] that has to be satisfied for a conditional dependency on this extension to be activated | ||
|
||
|=== | ||
|
||
[[quarkus-config-roots]] | ||
== META-INF/quarkus-config-roots.list | ||
|
||
This file may appear in a runtime extension artifact as well as in a deployment one. This file must not be edited manually, it is generated as part of the extension project build process and contains a list of Java class names that are annotated with `io.quarkus.runtime.annotations.ConfigRoot` an extension provides. | ||
|
||
[[quarkus-javadoc-properties]] | ||
== META-INF/quarkus-javadoc.properties | ||
|
||
Same as `quarkus-config-roots.list`, this file may appear in a runtime extension artifact as well in a deployment one. it must not be edited manually, it is generated as part of the extension project build process and descriptions of configuration options available in classes annotated with `io.quarkus.runtime.annotations.ConfigRoot`. | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.