A Quarkus build processor is a class in an extension’s deployment module. It contains build steps that run during augmentation, preparing application behavior before the packaged application starts. Deployment classes are omitted from the final runtime artifact, while the extension’s runtime module remains available to the application. section 12.2.2 section 12.6
A processor coordinates build-time work through several mechanisms:
- Defines build steps with @BuildStep methods; each step consumes and produces build items, forming a build-time action graph. section 12.2.2 section 12.2.3
- Uses build items to communicate with processors in the same or other extensions, such as registering CDI beans or HTTP filters. section 12.2.3
- Scans application classes through ApplicationIndexBuildItem and Jandex, allowing metadata queries without loading classes into the JVM. section 12.2.3
- Calls a recorder when runtime logic must be preserved as bytecode; use Gizmo directly when generating or modifying JVM bytecode is more appropriate. section 12.2.2
Generating an extension endpoint
A MetadataExtensionProcessor build step consumes application information, dependency metadata, configuration, and a recorder. It creates a JSON metadata object, records a handler, and produces a RouteBuildItem for the configured HTTP path. The Vert.x HTTP extension later consumes that item and registers the route. Marking the recorder operation STATIC_INIT runs it before RUNTIME_INIT; in native mode, the result can be recorded during image construction, while JVM mode executes both phases at startup. section 12.3.5 section 12.6
Figure 12.1 The relationships between build-time processing components and how they translate to runtime
Trace how processors, build steps, build items, recorders, and runtime behavior connect across the augmentation pipeline. section 12.2.3
