Build speed

The generator runs on every .dart file of lib/, bin/, test/ and example/, under build_runner build and on every save under build_runner watch. Resolving Dart code with the analyzer is the expensive part of a build, so the generator is written to resolve as little as it can, and to do extra work only when there is something to gain from it.

This page lists what it does, as the code does it.

Why

build_runner watch is part of the edit loop: a slow builder makes every save slow. The generator must look at the whole package for an application, and at the dependencies for auto-configurations and proxies, so it is easy to make it slow. Each item below avoids work the result does not need.

Most files produce nothing, cheaply

The main builder declares one possible output per library (lib/a.dart may produce lib/spring_gen/a.spring.dart). For each input it first reads the text of the file and checks two words:

Only the files that may declare a @ComponentScan variable or a @SpringBootApplication main are resolved.

Nested scans are found by text first

A @ComponentScan or @SpringBootApplication build looks at every file below its directories to find nested @ComponentScan roots. A file whose text does not contain ComponentScan is not resolved for that search.

Only the declarations that matter are resolved

Every scanned library is resolved to its elements (classes, members, annotations). Resolving the bodies of code is more expensive, and the generator does it only where a body tells something:

What Which bodies are resolved
The type a @Bean method really returns (DataSource dataSource() => HikariDataSource(url) registers a HikariDataSource) only the @Bean methods, of the library's classes and of the classes they @Import
The initial values of fields (IntrospectedProperty.initialValue) only the fields of @Introspected and @Table classes, of the DTOs of data repositories, and of classes a @ConfigurationProperties @Bean method returns
The calls of the ObjectMapper (see Only what runs) only a library (or part file) whose text names one of readValue, treeToValue, convertValue, readList, readMap, writeValueAsString, valueToTree; sendJson and broadcast only in a library that imports the WebSocket starter

A library that names no mapper method is not resolved for mapper calls at all.

Starters' libraries are read by text first

The application's build looks into dependencies for two things, and uses text checks before it resolves:

Only packages the application really depends on are searched (see Auto-configurations); in a pub workspace the siblings are skipped.

Build conditions cost nothing until used

For modules left out of the build:

The test builder reads tests as syntax

The spring_test builder skips a test file whose text contains neither SpringBootTest nor DataTest. It reads the others as syntax (parseString), without the analyzer's resolution. It resolves a test file only when its syntax does not tell enough: a @TestBean field whose value is a constructor call (to know the class) or whose type may be a nullable type alias.

Other builders do nothing without their properties

The Flutter builders run for every package that depends on the generator, pure Dart servers included. The web_dev_config.yaml builder, for example, does not even load the configuration unless a config file sets a spring.flutter.web.dev-server.* key or spring.flutter.security.web.mode. See The builders.

Stable output

The generated code is the same from one build to the next when the sources are the same:

Fewer build runs for errors

See also