You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by pp...@apache.org on 2021/08/27 12:25:05 UTC
[camel-quarkus] branch main updated: Document the usage of partial
Quarkus BOMs #3023
This is an automated email from the ASF dual-hosted git repository.
ppalaga pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel-quarkus.git
The following commit(s) were added to refs/heads/main by this push:
new d430e50 Document the usage of partial Quarkus BOMs #3023
d430e50 is described below
commit d430e50847efab823b4a21b7b5c733f0f77ca7ab
Author: Peter Palaga <pp...@redhat.com>
AuthorDate: Fri Aug 27 13:31:29 2021 +0200
Document the usage of partial Quarkus BOMs #3023
---
.../pages/user-guide/dependency-management.adoc | 86 +++++++++++++---------
1 file changed, 51 insertions(+), 35 deletions(-)
diff --git a/docs/modules/ROOT/pages/user-guide/dependency-management.adoc b/docs/modules/ROOT/pages/user-guide/dependency-management.adoc
index 1f56346..065e5a6 100644
--- a/docs/modules/ROOT/pages/user-guide/dependency-management.adoc
+++ b/docs/modules/ROOT/pages/user-guide/dependency-management.adoc
@@ -2,28 +2,23 @@
A specific Camel Quarkus release is supposed to work only with a specific Quarkus release.
-== Quarkus Universe BOM
+== Quarkus tooling for starting a new project
-The easiest and most straightforward way to get the dependency versions right is to use https://code.quarkus.io/[code.quarkus.io].
-It will produce a project with the `io.quarkus:quarkus-universe-bom` set up in the `<depependencyManagement>` section
-of your `pom.xml` file.
+The easiest and most straightforward way to get the dependency versions right in a new project is to use one of the Quarkus tools:
+* https://code.quarkus.io/[code.quarkus.io] - an online project generator,
+* https://quarkus.io/guides/cli-tooling[Quarkus CLI tool]
+* https://quarkus.io/guides/maven-tooling[Quarkus Maven plugin]
+* Some of the https://quarkus.io/guides/ide-tooling[Quarkus IDE plugins]
-[NOTE]
+All of these allow you to select extensions and scaffold a new Maven or Gradle project.
+
+[INFO]
====
-BOM stands for "Bill of Materials" - it is a `pom.xml` whose main purpose is to manage the versions of artifacts
-so that end users importing the BOM in their projects do not need to care which particular versions of the artifacts
-are supposed to work together. In other words, having a BOM imported in the `<depependencyManagement>` section
-of your `pom.xml` allows you to avoid specifying versions for the dependencies managed by the given BOM.
+The universe of available extensions spans over Quarkus Core, Camel Quarkus and several other third party participating projects,
+such as Hazelcast, Cassandra, Kogito, OptaPlanner, etc.
====
-`quarkus-universe-bom` manages the artifacts from Quarkus, Camel Quarkus and other participating projects,
-such as Hazelcast, Cassandra, Kogito, Optaplanner, etc.
-
-This has the advantage that application developers do not need to care for the compatibility of the individual artifacts
-that may come from various independent projects.
-Note that not all combinations of artifacts managed by `quarkus-universe-bom` are tested.
-
-Here is a stub of a `pom.xml` file generated by https://code.quarkus.io/[code.quarkus.io]:
+The generated `pom.xml` will look similar to the following:
[source,xml,subs="attributes+"]
----
@@ -35,40 +30,59 @@ Here is a stub of a `pom.xml` file generated by https://code.quarkus.io/[code.qu
</properties>
<dependencyManagement>
<dependencies>
+ <!-- The BOMs managing the dependency versions -->
<dependency>
- <groupId>io.quarkus</groupId>
- <artifactId>quarkus-universe-bom</artifactId>
+ <groupId>io.quarkus.platform</groupId>
+ <artifactId>quarkus-bom</artifactId>
<version>${quarkus.platform.version}</version>
<type>pom</type>
- <scope>import</scope><!-- The BOM is imported in the <dependencyManagement> -->
+ <scope>import</scope>
+ </dependency>
+ <dependency>
+ <groupId>io.quarkus.platform</groupId>
+ <artifactId>quarkus-camel-bom</artifactId>
+ <version>${quarkus.platform.version}</version>
+ <type>pom</type>
+ <scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
+ <!-- The extensions you chose in the project generator tool -->
<dependency>
<groupId>org.apache.camel.quarkus</groupId>
- <artifactId>camel-quarkus-timer</artifactId>
+ <artifactId>camel-quarkus-sql</artifactId>
<!-- No explicit version required here and below -->
</dependency>
- <dependency>
- <groupId>io.quarkus</groupId>
- <artifactId>quarkus-resteasy</artifactId>
- </dependency>
- <dependency>
- <groupId>io.quarkus</groupId>
- <artifactId>quarkus-resteasy-jackson</artifactId>
- </dependency>
- <dependency>
- <groupId>org.apache.camel.quarkus</groupId>
- <artifactId>camel-quarkus-ftp</artifactId>
- </dependency>
...
</dependencies>
...
</project>
----
+[NOTE]
+====
+BOM stands for "Bill of Materials" - it is a `pom.xml` whose main purpose is to manage the versions of artifacts
+so that end users importing the BOM in their projects do not need to care which particular versions of the artifacts
+are supposed to work together. In other words, having a BOM imported in the `<depependencyManagement>` section
+of your `pom.xml` allows you to avoid specifying versions for the dependencies managed by the given BOM.
+====
+
+Which particular BOMs end up in the `pom.xml` file depends on extensions you have selected in the generator tool.
+The generator tools take care to select a minimal consistent set.
+
+If you choose to add an extension at a later point that is not managed by any of the BOMs in your `pom.xml` file,
+you do not need to search for the appropriate BOM manually.
+With https://quarkus.io/guides/cli-tooling[Quarkus CLI] you can select the extension, and the tool adds the appropriate BOM as needed.
+Quarkus CLI also comes in handy when upgrading the BOM versions.
+
+The `io.quarkus.platform` BOMs are aligned with each other.
+That means that if an artifact is managed more than one BOM, it is always managed in the same version.
+This has the advantage that application developers do not need to care for the compatibility of the individual artifacts
+that may come from various independent projects.
+Note that not all combinations of artifacts managed by the various BOMs are tested.
+
== Camel Quarkus BOM
As long as you do not plan to use any dependencies beyond those from Quarkus and Camel Quarkus,
@@ -83,12 +97,14 @@ such as `io.quarkus:quarkus-arc` (CDI), `io.quarkus:quarkus-hibernate-orm`, `io.
== Combining with other BOMs
-When combining `camel-quarkus-bom` or `quarkus-universe-bom` with any other BOM,
+When combining `camel-quarkus-bom` with any other BOM,
think carefully in which order you import them,
because the order of imports defines the precedence.
I.e. if `my-foo-bom` is imported before `camel-quarkus-bom` then the versions defined in
-`my-foo-bom` will take the precedence. This might or might not be what you want, depending on whether there are any overlaps between `my-foo-bom` and `camel-quarkus-bom` and depending on whether those versions with higher precedence work with the rest of the artifacts managed in `camel-quarkus-bom`.
+`my-foo-bom` will take the precedence.
+This might or might not be what you want, depending on whether there are any overlaps between `my-foo-bom` and `camel-quarkus-bom`
+and depending on whether those versions with higher precedence work with the rest of the artifacts managed in `camel-quarkus-bom`.
== What's next?