Document cq:create -Dcq.nativeSupported=false for creating JVM-only e…

…xtensions apache#1662

docs/modules/ROOT/nav.adoc

@@ -8,6 +8,7 @@
 * xref:contributor-guide/index.adoc[Contributor guide]
 ** xref:contributor-guide/create-new-extension.adoc[Create new extension]
 ** xref:contributor-guide/promote-jvm-to-native.adoc[Promote JVM extension to Native]
+** xref:contributor-guide/create-jvm-only-extension.adoc[Create JVM-only extension]
 ** xref:contributor-guide/extension-metadata.adoc[Extension metadata]
 ** xref:contributor-guide/extension-documentation.adoc[Extension documentation]
 ** xref:contributor-guide/ci.adoc[Continuous Integration]

docs/modules/ROOT/pages/contributor-guide/create-jvm-only-extension.adoc

@@ -0,0 +1,38 @@
+[[create-jvm-only-extension]]
+= Create a JVM-only extension
+
+== Why JVM-only extensions
+
+Quarkus applications can be built and run in two modes: JVM and native. While native mode is clearly superior when it
+comes to application start time, memory consumption and size on disk, the JVM mode may still be a valid option. Here is
+why:
+
+First, Quarkus works really well on stock JVMs, such as OpenJDK. While the memory consumption and start times are not
+as good as in native mode, they are still very good when
+https://quarkus.io/blog/runtime-performance/#application-start-time[compared] to traditional JVM stacks.
+
+Second, JVM mode beats native mode in https://quarkus.io/blog/runtime-performance/#throughput-reqsec[peak throughput]
+and https://quarkus.io/blog/runtime-performance/#response-times-ms[response latency]. You should prefer JVM mode if
+these metrics matter to you.
+
+And third, creating a Quarkus extension that works well both in JVM and native mode requires some time and
+xref:contributor-guide/create-new-extension.adoc[expertise]. In case some extension is needed quickly and the native
+support is dispensable, relying on JVM-only extensions may make a lot of sense.
+
+== How to create a JVM-only extension
+
+The steps are the same as when xref:contributor-guide/create-new-extension.adoc[creating a native extension], except
+for the following:
+
+* Add `-Dcq.nativeSupported=false` to `cq:create` mojo invocation:
++
+[source,shell]
+----
+$ cd camel-quarkus
+$ mvn cq:create -N -Dcq.artifactIdBase=foo-abc
+----
++
+* A basic integration test is generated for you. It just checks that the newly added Camel component can be loaded.
+  Adding some meaningful assertions to the generated test is highly welcome though.
+* You do not need to add the test to `tooling/scripts/test-categories.yaml` because it is necessary only for
+  native tests.

docs/modules/ROOT/pages/contributor-guide/create-new-extension.adoc

@@ -44,21 +44,21 @@ because the test project needs to get finished. You need to build `poms/bom` and
 7. Review the generated
    `extensions/foo-abc/runtime/src/main/resources/META-INF/quarkus-extension.yaml` file.
 +
-   The
-   `description` comes from Camel Catalog. If it looks improper or too long due to concatenation of multiple
-   component descriptions, you may override it by setting an explicit `<description>` in the runtime `pom.xml`
-   of your new extension. If you think the value coming from Camel Catalog should be changed, please
-   https://issues.apache.org/jira/secure/CreateIssue!default.jspa[file a new Camel issue] and ask to fix the metadata
-   for the given Camel component.
+The
+`description` comes from Camel Catalog. If it looks improper or too long due to concatenation of multiple
+component descriptions, you may override it by setting an explicit `<description>` in the runtime `pom.xml`
+of your new extension. If you think the value coming from Camel Catalog should be changed, please
+https://issues.apache.org/jira/secure/CreateIssue!default.jspa[file a new Camel issue] and ask to fix the metadata
+for the given Camel component.
 +
-   If there is some important keyword missing in both the `name` and `description` through which your new extension
-   should definitely be findable on https://code.quarkus.io[code.quarkus.io], consider setting
-   `<quarkus.metadata.keywords>` property in your runtime `pom.xml`.
+If there is some important keyword missing in both the `name` and `description` through which your new extension
+should definitely be findable on https://code.quarkus.io[code.quarkus.io], consider setting
+`<quarkus.metadata.keywords>` property in your runtime `pom.xml`.
 +
-   Run `mvn -N cq:update-quarkus-metadata` from the source tree's root directory to re-generate the
-   `quarkus-extension.yaml` file.
+Run `mvn -N cq:update-quarkus-metadata` from the source tree's root directory to re-generate the
+`quarkus-extension.yaml` file.
 +
-   Check the xref:contributor-guide/extension-metadata.adoc[Extension metadata] page for more details about the `quarkus-extension.yaml` file
+Check the xref:contributor-guide/extension-metadata.adoc[Extension metadata] page for more details about the `quarkus-extension.yaml` file
 
 8. Review the dependencies in the generated runtime and deployment modules. In case the given library is supported by
    Quarkus, you may want to add a dependency on the corresponding Quarkus extension.