Skip to content

Commit

Permalink
Fix quarkusio#3386 Document create-extension Maven mojo
Browse files Browse the repository at this point in the history
  • Loading branch information
ppalaga committed Jul 31, 2019
1 parent bcaecfb commit 29ef53f
Showing 1 changed file with 47 additions and 0 deletions.
47 changes: 47 additions & 0 deletions docs/src/main/asciidoc/extension-authors-guide.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -250,6 +250,8 @@ Your extension project should be setup as a multi-module project with two submod

2. A runtime submodule that contains the runtime behavior that will provide the extension behavior in the native executable or runtime JVM.

TIP: You may want to use `create-extension` mojo of `io.quarkus:quarkus-maven-plugin` to create these Maven modules - see the next section.

Your runtime artifact should depend on `io.quarkus:quarkus-core`, and possibly the runtime artifacts of other Quarkus
modules if you want to use functionality provided by them.
You will also need to include the `io.quarkus:quarkus-bootstrap-maven-plugin` to generate the Quarkus extension descriptor included into the runtime artifact, if you are using the Quarkus parent pom it will automatically inherit the correct configuration.
Expand Down Expand Up @@ -340,6 +342,51 @@ You will also need to configure the `maven-compiler-plugin` to detect the `quark
</build>
----

==== Create new extension modules using Maven

`create-extension` mojo of `io.quarkus:quarkus-maven-plugin` can be used to generate stubs of Maven modules needed for implementing a new Quarkus extension.

WARNING: This mojo can be currently used only for adding extensions to an established source tree, such as https://github.com/quarkusio/quarkus[Quarkus] or https://github.com/quarkusio/quarkus[Camel Quarkus]. Creating extension projects from scratch is not supported yet.

Example: Let's add a new extension called `my-ext` to Quarkus source tree:

[source, shell, subs=attributes+]
----
git clone https://github.com/quarkusio/quarkus.git
cd quarkus
cd extensions
mvn io.quarkus:quarkus-maven-plugin:{quarkus-version}:create-extension -N -Dquarkus.artifactIdBase=my-ext
----

The above sequence of commands will create three new Maven modules:

* `quarkus-my-ext-parent` in `my-ext` directory; this module is also added to `<modules>` of `quarkus-extensions-parent`
* `quarkus-my-ext` in `my-ext/runtime` directory
* `quarkus-my-ext-deployment` in `my-ext/deployment` directory; a basic `MyExtProcessor` class is generated in this module.

Trying to build the new extension without any change will result in Maven complaining about the missing version of `quarkus-my-ext` in `quarkus-my-ext-deployment`. So solve that, we need to add `quarkus-my-ext` to the `dependencyManagement` in `bom/runtime/pom.xml`. After that, the build of the new extension modules should pass flawlessly.

Note that those parameters of the mojo that will be constant for all extensions added in this source tree are configured in `extensions/pom.xml` so that they do not need to be passed on the command line each time a new extension is added.

[source,xml]
----
<plugin>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-maven-plugin</artifactId>
<version>${quarkus.version}</version>
<inherited>false</inherited>
<!-- Settings for stubbing new extensions via
mvn quarkus:create-extension -N -Dquarkus.artifactIdBase=my-new-extension
-->
<configuration>
<artifactIdPrefix>quarkus-</artifactIdPrefix>
<namePrefix xml:space="preserve">Quarkus - </namePrefix>
</configuration>
</plugin>
----

Please refer to https://github.com/quarkusio/quarkus/blob/{quarkus-version}/devtools/maven/src/main/java/io/quarkus/maven/CreateExtensionMojo.java[CreateExtensionMojo JavaDoc] for all available options of the mojo.

=== Build Step Processors

Work is done at deployment time by producing and consuming instances of `io.quarkus.builder.item.BuildItem`. This is done
Expand Down

0 comments on commit 29ef53f

Please sign in to comment.