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:
- An input whose text contains neither
ComponentScannorSpringBootApplicationis skipped without being resolved. That is almost every file of a package. - Generated files (
.spring.dart) are never inputs.
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:
- Advice of auto-configurations, for proxy pruning. For each auto-configuration library and the libraries of the same package it imports, the build reads the text.
AspectMetadatain it means aspects the build cannot read (pruning is then off and the search stops early). Only a library whose text mentionsAdvisorhas its declarations resolved, to read the advisors' pointcuts. - Deferred proxies. Among the generated modules the auto-configurations and the application reach, only a
.spring.dartfile whose text containsAopProxyFactory.deferredhas its getters resolved.
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 configuration files are parsed into an environment only when the first module with
build:is decided, then reused for the other modules of the build. An application whose starters use nobuild:never parses them for this. - The profile files are searched only when the property is not set.
- The module declarations are walked for deferred proxies only when a module was decided
neverornotInRelease; the modules that are always in are walked only when those removed modules define such a bean. Each declaration is walked once.
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:
- files, libraries and auto-configuration modules are processed in a fixed order (by path, by package and name);
- the
fingerprintof the application (in its debug part,main.spring.debug.dart) is an FNV-1a hash of the generated code, stable across runs and platforms; - the
build-info.propertieswritten for an application with the actuator has no build time.
Fewer build runs for errors
- All problems at once. The scanner keeps going after a bad declaration and reports every independent problem of the build together (
N problems in this build:), so you fix them in one round instead of one build per error. See Build-time checks. - No flicker while you type. While a scanned library has syntax errors, the existing generated file is written again unchanged, so the files that import it do not turn red and
watchdoes not regenerate on every keystroke. See Errors and the generated files. - The last good output is kept in memory. Under
watch, the builder keeps the last content it generated for each output and uses it when the sources break, without reading the disk.