From 29ef53f7b4dc94bd7d8f3e08e34e23961b0ad33d Mon Sep 17 00:00:00 2001 From: Peter Palaga Date: Wed, 31 Jul 2019 18:58:01 +0200 Subject: [PATCH] Fix #3386 Document create-extension Maven mojo --- .../asciidoc/extension-authors-guide.adoc | 47 +++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/docs/src/main/asciidoc/extension-authors-guide.adoc b/docs/src/main/asciidoc/extension-authors-guide.adoc index 97e25bd237f54..bdac8c35e2388 100644 --- a/docs/src/main/asciidoc/extension-authors-guide.adoc +++ b/docs/src/main/asciidoc/extension-authors-guide.adoc @@ -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. @@ -340,6 +342,51 @@ You will also need to configure the `maven-compiler-plugin` to detect the `quark ---- +==== 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 `` 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] +---- + + io.quarkus + quarkus-maven-plugin + ${quarkus.version} + false + + + quarkus- + Quarkus - + + +---- + +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