You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by al...@apache.org on 2020/04/07 16:54:24 UTC
[camel-quarkus] branch master updated: Completed the contributor
guide with a section to promote JVM Only extension to native #1021
This is an automated email from the ASF dual-hosted git repository.
aldettinger pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/camel-quarkus.git
The following commit(s) were added to refs/heads/master by this push:
new 3fe59a5 Completed the contributor guide with a section to promote JVM Only extension to native #1021
3fe59a5 is described below
commit 3fe59a585913ceeeb4e04c6f53ea83e00cb94808
Author: aldettinger <al...@gmail.com>
AuthorDate: Tue Apr 7 17:45:27 2020 +0200
Completed the contributor guide with a section to promote JVM Only extension to native #1021
---
docs/modules/ROOT/pages/contributor-guide.adoc | 131 +++++++++++++++++++++++++
1 file changed, 131 insertions(+)
diff --git a/docs/modules/ROOT/pages/contributor-guide.adoc b/docs/modules/ROOT/pages/contributor-guide.adoc
index a2ed996..fcfb5d4 100644
--- a/docs/modules/ROOT/pages/contributor-guide.adoc
+++ b/docs/modules/ROOT/pages/contributor-guide.adoc
@@ -124,3 +124,134 @@ Review the result visually.
12. Please squash your commits before sending a pull request.
Good luck!
+
+== Promote a JVM Only extension to Native
+
+The directory `extensions-jvm` contains some extensions that need to be tested in link:https://quarkus.io/guides/building-native-image[native mode]. Configuring the link:https://quarkus.io/guides/writing-native-applications-tips[native build] and implementing integration tests of such extensions may open the door to even faster startup and lower footprint.
+Please find some guiding steps below to start this quest:
+
+1. Make sure that nobody else works on promoting the same extension by searching through the
+ https://github.com/apache/camel-quarkus/issues[GitHub issues].
+
+2. Let others know that you work on promoting the given extension by either creating a
+ https://github.com/apache/camel-quarkus/issues/new[new issue] or asking to assign an existing one to you.
+
+3. Select the JVM Only extension to be promoted, for instance the grpc extension like below:
++
+[source,shell]
+----
+$ cd camel-quarkus
+$ export EXT='grpc'
+----
+
+4. Split the JVM Only extension into `extensions` and `integration-tests` folders, from a shell execute:
++
+[source,shell]
+----
+$ {
+ sed -i '/integration-test/d' "extensions-jvm/${EXT}/pom.xml"
+ sed -i "/<module>${EXT}<\/module>/d" "extensions-jvm/pom.xml"
+ git mv "extensions-jvm/${EXT}/integration-test/" "integration-tests/${EXT}"
+ git mv "extensions-jvm/${EXT}" "extensions/${EXT}"
+ sed -i -r "s/(.*)activemq(.*)/\1activemq\2\n\1${EXT}\2/g" extensions/pom.xml
+ sed -i -r "s/(.*)activemq(.*)/\1activemq\2\n\1${EXT}\2/g" integration-tests/pom.xml
+ sed -i "s/camel-quarkus-grpc-parent/camel-quarkus-integration-tests/g" "integration-tests/${EXT}/pom.xml"
+ sed -i "s/camel-quarkus-grpc-integration-test/camel-quarkus-integration-test-${EXT}/g" "integration-tests/${EXT}/pom.xml"
+ sed -i -r "s/Quarkus :: (.*) :: Integration Test/Quarkus :: Integration Test :: \1/g" "integration-tests/${EXT}/pom.xml"
+ }
+----
+
+5. Add the native profile at the end of `integration-tests/${EXT}/pom.xml`:
++
+[source,xml]
+----
+ <profiles>
+ <profile>
+ <id>native</id>
+ <activation>
+ <property>
+ <name>native</name>
+ </property>
+ </activation>
+ <properties>
+ <quarkus.package.type>native</quarkus.package.type>
+ </properties>
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-failsafe-plugin</artifactId>
+ <executions>
+ <execution>
+ <goals>
+ <goal>integration-test</goal>
+ <goal>verify</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+ </profile>
+ </profiles>
+----
+
+6. Remove the warning link:https://quarkus.io/guides/writing-extensions#build-step-processors[build step] from `extensions/${EXT}/deployment/src/main/java/org/apache/camel/quarkus/component/${EXT}/deployment/${EXT}Processor.java`:
++
+[source,java]
+----
+ /**
+ * Remove this once this extension starts supporting the native mode.
+ */
+ @BuildStep(onlyIf = NativeBuild.class)
+ @Record(value = ExecutionTime.RUNTIME_INIT)
+ void warnJvmInNative(JvmOnlyRecorder recorder) {
+ JvmOnlyRecorder.warnJvmInNative(LOG, FEATURE); // warn at build time
+ recorder.warnJvmInNative(FEATURE); // warn at runtime
+ }
+----
+
+7. Create a native test at `integration-tests/${EXT}/src/test/java/org/apache/camel/quarkus/component/${EXT}/it/${EXT}IT.java`
+
+8. Check `extensions/${EXT}/runtime/src/main/resources/META-INF/quarkus-extension.yaml`:
+* Ensure guide is set to `"https://quarkus.io/guides/camel"`
+* Ensure keyword `camel` is present
+* Remove the `preview` status
+
+9. Add itests to `.github/workflows/pr-build.yaml`, for instance:
++
+[source,yaml]
+----
+- category: Rpc
+ test-modules: >
+ grpc
+----
+
+10. Unify source files format, update docs and rebuild the whole project:
++
+[source,shell]
+----
+mvn clean install -D skipTests -P format
+----
+
+11. Build the extension:
++
+[source,shell]
+----
+cd "extensions/${EXT}"
+mvn clean install
+----
+
+12. Execute integration tests:
++
+[source,shell]
+----
+cd "../../integration-tests/${EXT}"
+mvn clean verify -P native
+----
+
+13. Now it's time to solve native build issues if any, extend integration tests coverage and perhaps even shifting some treatments
+from runtime to build time. The https://quarkus.io/guides/extension-authors-guide[Quarkus extension author's guide] may be a good
+ally for this.
+
+14. Please also check the link:#create-a-new-extension[Create a new extension] section as it contains some useful tips for a good contribution.
\ No newline at end of file