Skip to content
Permalink
Browse files
Document the usage of partial Quarkus BOMs #3023
  • Loading branch information
ppalaga committed Aug 27, 2021
1 parent 5f71941 commit d430e50847efab823b4a21b7b5c733f0f77ca7ab
Showing 1 changed file with 51 additions and 35 deletions.
@@ -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?

0 comments on commit d430e50

Please sign in to comment.