|
| 1 | +//// |
| 2 | +This guide is maintained in the main Quarkus repository |
| 3 | +and pull requests should be submitted there: |
| 4 | +https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc |
| 5 | +//// |
| 6 | +[id="modularity-reference"] |
| 7 | += Modularity SPI reference |
| 8 | +include::_attributes.adoc[] |
| 9 | +:diataxis-type: reference |
| 10 | +:categories: architecture |
| 11 | +:extension-status: experimental |
| 12 | +:summary: Reference for the build items that Quarkus extensions use to participate in Quarkus modularity. |
| 13 | +:topics: modularity,jpms,modules,extensions,spi |
| 14 | + |
| 15 | +This document describes the build items that extension authors use to integrate with the xref:modularity.adoc[Quarkus modularity] system. |
| 16 | +Extensions can declare boot modules, add inter-module dependencies, and consume the completed module model. |
| 17 | + |
| 18 | +include::{includes}/extension-status.adoc[] |
| 19 | + |
| 20 | +== `BootModulePathBuildItem` |
| 21 | + |
| 22 | +`BootModulePathBuildItem` is a `MultiBuildItem` produced by extensions. |
| 23 | +It declares that a named module must be placed on the boot module path. |
| 24 | + |
| 25 | +An extension should produce this item when it provides a module that must be in the JDK's boot module layer. |
| 26 | +This is necessary when the module is required before the dynamic module loader (`smallrye-modules`) starts, or when the module must participate in the boot class loading chain. |
| 27 | + |
| 28 | +The constructor takes a single `String` parameter: the module name. |
| 29 | + |
| 30 | +[source,java] |
| 31 | +---- |
| 32 | +@BuildStep |
| 33 | +BootModulePathBuildItem myBootModule() { |
| 34 | + return new BootModulePathBuildItem("com.example.my.boot.module"); |
| 35 | +} |
| 36 | +---- |
| 37 | + |
| 38 | +The modularity extension computes the transitive closure of all declared boot modules. |
| 39 | +If a boot module depends on other modules (via `LINKED` dependencies), those modules are also included in the boot set automatically. |
| 40 | +Automatic modules are excluded from the boot set because they cannot be linked by `jlink`. |
| 41 | + |
| 42 | +== `AddDependencyBuildItem` |
| 43 | + |
| 44 | +`AddDependencyBuildItem` is a `MultiBuildItem` produced by extensions. |
| 45 | +It adds a dependency between two modules at build time. |
| 46 | + |
| 47 | +An extension should produce this item when it needs to wire a module dependency that is not expressed in the Maven POM or in the module's `module-info.class` descriptor. |
| 48 | +This is common when Quarkus extensions generate code that references types from another module, or when service loading relationships must be declared explicitly. |
| 49 | + |
| 50 | +The constructor takes three parameters: the source module name (`String`), the target module name (`String`), and a set of dependency modifiers (`Modifiers<Dependency.Modifier>`). |
| 51 | + |
| 52 | +[source,java] |
| 53 | +---- |
| 54 | +@BuildStep |
| 55 | +AddDependencyBuildItem extraDependency() { |
| 56 | + return new AddDependencyBuildItem( |
| 57 | + "com.example.source.module", |
| 58 | + "com.example.target.module", |
| 59 | + Dependency.Modifier.set(Dependency.Modifier.LINKED, Dependency.Modifier.READ)); |
| 60 | +} |
| 61 | +---- |
| 62 | + |
| 63 | +When multiple items declare the same source/target pair, their modifier sets are merged. |
| 64 | + |
| 65 | +== `ApplicationModuleInfoBuildItem` |
| 66 | + |
| 67 | +`ApplicationModuleInfoBuildItem` is a `SimpleBuildItem` produced by the modularity extension. |
| 68 | +It contains the completed `AppModuleModel`, which includes the module descriptor for every module in the application, the set of boot modules, and the set of JDK modules in use. |
| 69 | + |
| 70 | +This item is consumed by downstream packaging extensions such as the xref:jlink.adoc[jlink extension]. |
| 71 | +Extension authors generally do not need to consume this item unless they are implementing a custom packaging step. |
| 72 | + |
| 73 | +== Dependency modifiers |
| 74 | + |
| 75 | +The `Dependency.Modifier` enum (from `io.smallrye.modules.desc`) defines the following values. |
| 76 | +These are used with `AddDependencyBuildItem` to control how the dependency is wired. |
| 77 | + |
| 78 | +`LINKED`:: |
| 79 | +The dependency is linked for class loading. |
| 80 | +Classes from the target module are visible to the source module's class loader. |
| 81 | + |
| 82 | +`READ`:: |
| 83 | +The dependency is readable from the source module. |
| 84 | +Exported packages from the target module are accessible to the source module. |
| 85 | + |
| 86 | +`SERVICES`:: |
| 87 | +Service implementations in the target module are available to the source module via `ServiceLoader`. |
| 88 | + |
| 89 | +`OPTIONAL`:: |
| 90 | +The dependency is optional. |
| 91 | +If the target module is not present at link time, the dependency is silently ignored rather than causing a failure. |
| 92 | + |
| 93 | +`TRANSITIVE`:: |
| 94 | +The dependency is transitive. |
| 95 | +Any module that depends on the source module also implicitly depends on the target module. |
| 96 | + |
| 97 | +`SYNTHETIC`:: |
| 98 | +The dependency was added by a framework rather than declared in the original module descriptor. _Note:_ because modifier sets are merged when a dependency is declared in two places, this modifier would take precedence over a non-synthetic dependency, which is a minor detail but possibly undesirable. Thus, this modifier may change to be "non-synthetic" or something along those lines in the final version, so that an explicit dependency will never be marked as being synthetic. |
| 99 | + |
| 100 | +`MANDATED`:: |
| 101 | +The dependency is mandated by specification (for example, the implicit dependency on `java.base`). |
| 102 | + |
| 103 | +== Related core build items |
| 104 | + |
| 105 | +The `quarkus-core-deployment` module provides two additional build items that affect the module graph. |
| 106 | +These are documented separately but are noted here for completeness. |
| 107 | + |
| 108 | +`ModuleOpenBuildItem` declares that one module should open specified packages to another module (equivalent to the `--add-opens` JVM flag). |
| 109 | +`ModuleEnableNativeAccessBuildItem` declares that a module requires native access (equivalent to the `--enable-native-access` JVM flag). |
0 commit comments