Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 36 ยท Native Images and Dev Mode

How Quarkus Works: Build-Time Processing

Learn why Quarkus starts fast and uses little memory: build steps, the Jandex index, generated bytecode, ArC dependency injection and the closed-world principle.

Quarkus apps often start in a fraction of a second and use far less memory than the same service built on a traditional framework. It is not magic, and it is not only GraalVM. The key idea is simple: do at build time everything that does not depend on the running environment, so that startup has almost nothing left to do.

Understanding this one idea explains the build-time properties you met in configuration, why some things must be annotated for native builds, why extensions exist, and why dev mode reloads so fast. This lesson is the "how it works" tour. The TryIts demonstrate the principle with plain Java; the real build steps are shown read-only.

What a traditional framework does at startup

A classic dependency-injection framework, when the JVM starts, typically:

  1. Scans the classpath for annotated classes, reading thousands of class files.
  2. Parses annotations and builds metadata with reflection.
  3. Creates proxies by generating bytecode.
  4. Wires the beans together and reads configuration.

All of that happens every time the process starts, and all of that metadata lives in memory for the life of the process. Yet the classes do not change between two starts of the same deployment. The work is repeated for nothing.

What Quarkus does instead

Quarkus splits the life of an application into phases:

Phase Runs Examples of work
Augmentation (build) When you run mvn package or when dev mode reloads Index classes, read annotations, decide the bean graph, generate proxies and wiring code, process config marked build-time
Static init Once, at JVM start (or captured in a native image) Run recorded initialization that needs no runtime values
Runtime init At JVM start, after static init Bind ports, open connections, read runtime configuration

The augmentation phase produces ordinary bytecode that does the wiring directly: new OrderService(new PriceCalculator()) in effect, not "look up a class by name and call its constructor by reflection". At startup the JVM just runs that straight-line code.

Where the work moves

Build time Scan, analyze, generate.
Package Jar with generated code.
Start Run straight-line code.

Startup no longer discovers anything.

1 / 2

The main parts

Jandex. Quarkus builds a Jandex index: a compact, searchable summary of every class, annotation and method in your application and its libraries. Extensions ask questions such as "which classes have @Path?" and get an answer from the index without loading the classes.

Extensions and build steps. A Quarkus extension has two modules: a deployment module, which runs only during augmentation, and a runtime module, which goes into your app. The deployment module contains build steps: methods annotated @BuildStep that consume build items (such as "annotated classes") and produce others (such as "generated beans" or "reflection registrations"). The framework sorts the steps by their inputs and outputs and runs them, in parallel where possible.

Java
@BuildStep
void registerResources(CombinedIndexBuildItem index,
                       BuildProducer<AdditionalBeanBuildItem> beans) {
    for (AnnotationInstance a : index.getIndex()
            .getAnnotations(DotName.createSimple("org.acme.Audited"))) {
        beans.produce(AdditionalBeanBuildItem.unremovableOf(
                a.target().asClass().name().toString()));
    }
}

You do not need to write extensions to use Quarkus, but knowing they exist explains the two-module layout in the extension catalog (quarkus-rest and quarkus-rest-deployment).

ArC, the CDI container. Quarkus does not run a full Jakarta CDI implementation at runtime. ArC resolves injection points at build time and generates a class for each bean, so there is no runtime lookup and unused beans can be removed. A bean that nothing injects is deleted from the build, unless it is marked @Unremovable. This is why a bean obtained only through CDI.current().select(...) or by a string name may seem to vanish. The chapter on CDI covers this in detail.

Recorders. When a step must run something at startup (open a pool, register a route), it does not run it itself. It records the call to a recorder class, and the recorded calls are written as bytecode that runs at startup. That is how "build time" decisions flow into "runtime" actions.

Java Stand-in: discovery at startup versus precomputed wiring

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Dead-code removal: unused beans disappear

Because the bean graph is fully known at build time, Quarkus can prove that a bean is never used and drop it, with its dependencies. The same principle powers the smaller native images: only reachable code is kept.

Java Stand-in: removing unused beans from a graph

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

What this costs you

The closed-world principle has consequences you will meet in real code:

  • No classpath scanning at runtime. Anything discovered by scanning must be visible at build time. Libraries that rely on Class.forName with user-provided names need an extension or explicit registration.
  • Reflection must be declared for native images. Use @RegisterForReflection on classes that a library such as Jackson reads reflectively (see native images).
  • Build-time config is frozen. Changing quarkus.hibernate-orm.database.generation at runtime has no effect, and Quarkus tells you so.
  • Conditional beans are decided at build time with @IfBuildProfile, @IfBuildProperty and friends, or at runtime with ordinary if statements.

In return you get fast startup, low resident memory, easy native compilation, and an application whose structure was validated before it ever ran: a missing bean is a build error, not a production surprise.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the central idea behind Quarkus's fast startup?

    Scanning, annotation processing and bean wiring are done once during augmentation, so startup only runs generated code.
  2. 2. What does a @BuildStep method do?

    Build steps live in an extension's deployment module and run only while the application is built.
  3. 3. Why might an unused CDI bean disappear from a Quarkus application?

    Because the bean graph is known at build time, unused beans are removed to save memory and image size.
  4. 4. Which is a consequence of the closed-world model?

    Values consumed during augmentation are baked into the generated code and are fixed once the app is built.

Summary

  • Quarkus moves scanning, annotation processing and wiring from startup to the build.
  • Jandex indexes classes, build steps produce generated code, ArC resolves CDI at build time, recorders carry startup actions.
  • Unused beans can be removed; reflection and dynamic class loading need explicit declarations.
  • The payoff is fast startup, low memory and an easy path to native images.

Next: Native Images with GraalVM