Options

The main builder, spring_core_dart_generator:spring_core_dart, takes four options. They go into the build.yaml of the package being built, next to its pubspec.yaml. The other builders of the package take no options.

# build.yaml
targets:
  $default:
    builders:
      spring_core_dart_generator:spring_core_dart:
        options:
          aop_proxies: all
          aop_prune: true
          aop_defer: false
          dart_defines_exclude: []

Without a build.yaml, or without options:, every option has its default. That is the right choice for almost every application.

Why

The defaults give the smallest code that still behaves like Spring. The options exist for the cases the build cannot decide alone: advice added in code at run time, a library always reached through a starter, properties that must not be set by --dart-define.

The options

Option Values Default Invalid value
aop_proxies all, interfaces, none all ArgumentError: Expected all, interfaces or none
aop_prune true, false true ArgumentError: Expected true or false
aop_defer true, false false ArgumentError: Expected true or false
dart_defines_exclude a list of property name prefixes [] ArgumentError (see below)

An invalid value fails the build before any file is generated.

aop_proxies

Which beans may get a generated AOP proxy class.

Value Meaning
all A proxy class for every bean whose class, or one of its interfaces, can be implemented; a subclass proxy for a class that can only be extended.
interfaces Proxies only through a bean's abstract supertypes. A bean without one gets no proxy.
none No proxy classes. AOP cannot advise the beans of the module.

The value must be one of the three names, written as text in YAML.

aop_prune

With true, the outputs that know every piece of advice of the application leave out the proxy classes, and the proxy members, that no advice can match:

The @ComponentScan modules of a library package are never pruned. The lib/ modules of a starter (a package with lib/spring_auto_configuration.dart) leave to the application the proxy classes only its aspects can match (AopProxyFactory.deferred), and the application writes those its pointcuts may match.

With false, every bean keeps its proxy class with every member, starters defer nothing, and the application writes every proxy left to it. Use false when advice is registered in code at run time (a registrar, a BeanFactoryPostProcessor, registerSingleton, Advised.addAdvisor): with pruning on, the startup fails in that case and says so.

Everything about it: AOP proxies: pruning and deferring.

aop_defer

With true, the lib/ modules of a library package without lib/spring_auto_configuration.dart leave to the application the proxy classes only its aspects can match, as a starter's modules do. This is for a library whose modules a starter's auto-configuration imports, so the application's build finds them through it (spring_boot_actuator sets it). Any other library keeps every proxy by default, because any module may import it.

Deferring needs aop_prune: true in the same build. In an application package (publish_to: none) the option changes nothing: its modules are pruned instead.

dart_defines_exclude

The @SpringBootApplication output lists in springApplication.dartDefines every property the application may read, so --dart-define can set it (see --dart-define keys). The properties under a prefix of dart_defines_exclude are left out of that list, in both of their forms (spring.flutter.theme.mode and SPRING_FLUTTER_THEME_MODE). They can still be set by config files, environment variables and arguments.

targets:
  $default:
    builders:
      spring_core_dart_generator:spring_core_dart:
        options:
          dart_defines_exclude:
            - spring.flutter.theme
            - spring.datasource

How prefixes are read:

Each of these fails the build with an ArgumentError:

Value Message
not a list (dart_defines_exclude: spring.datasource) Expected a list of property name prefixes
an entry that is not a string Expected a property name prefix (a string)
an entry with * Wildcards are not supported: a prefix already covers every property under it (write spring.datasource, not spring.datasource.*)
a blank entry Expected a property name prefix, not a blank entry
other characters than letters, digits, _ . - [ ] Expected a property name prefix: letters, digits, _ . - [ and ]

Full examples

An application that adds advice at run time

# build.yaml of the application
targets:
  $default:
    builders:
      spring_core_dart_generator:spring_core_dart:
        options:
          # A registrar adds an advisor the build cannot see:
          # keep every proxy class and every member.
          aop_prune: false

A Flutter app that keeps theme properties away from --dart-define

# build.yaml of the application
targets:
  $default:
    builders:
      spring_core_dart_generator:spring_core_dart:
        options:
          dart_defines_exclude: [spring.flutter.theme]

A module that never needs AOP

# build.yaml of a package
targets:
  $default:
    builders:
      spring_core_dart_generator:spring_core_dart:
        options:
          aop_proxies: none

The spring_properties builder (hand-written starters)

Most of a starter can be written by hand, but the binding of its typed @ConfigurationProperties classes is best generated. That raises a problem: the starter's lib/ imports the generated file, and the starter's example (built by the main builder) imports lib/. A builder cannot read what another input of its own phase writes, so the example's build would not see the file.

The spring_properties builder solves it. It is the main builder, limited to lib/, in a phase of its own that runs before the main one. It is off unless a package turns it on (auto_apply: none), and it takes the same options as the main builder.

A typical starter's build.yaml:

# build.yaml of a starter (spring_boot_starter_cache)
targets:
  $default:
    builders:
      # The main builder writes only the example's application.
      spring_core_dart_generator:spring_core_dart:
        generate_for: [example/**]
      # The binding of the typed properties, before the main builder runs.
      spring_core_dart_generator:spring_properties:
        enabled: true
        generate_for: [lib/src/config/**]
      spring_core_dart_generator:spring_test:
        enabled: false

A library a starter imports, with aop_defer (from spring_boot_actuator):

# build.yaml of spring_boot_actuator
targets:
  $default:
    builders:
      spring_core_dart_generator:spring_core_dart:
        enabled: false
      spring_core_dart_generator:spring_properties:
        enabled: true
        generate_for: [lib/src/properties/**]
        options:
          # The actuator starter's auto-configuration imports these
          # modules: the application writes the proxy classes its aspects
          # need, as for a starter's own modules.
          aop_defer: true
      spring_core_dart_generator:spring_test:
        enabled: false

Options are set per builder: options given to spring_core_dart do not apply to spring_properties, and the other way round.

enabled and generate_for are build_runner's own keys, available for every builder. The builders of the package and what they write are on The builders.

See also