
# 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.

```yaml
# 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 `@SpringBootApplication` output;
- the `@ComponentScan` modules of an application (`publish_to: none` in `pubspec.yaml`): nothing outside imports them.

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](optimizations/aop-proxies.md).

### `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](dart-defines.md)). 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.

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

How prefixes are read:

- A prefix covers every property under it, matched by whole `.`-separated segments: `spring.datasource` covers `spring.datasource.url`, not `spring.datasourceish`.
- Names are compared with relaxed binding, without case and ignoring `-` and `_` inside a segment: `spring.dataSource`, `spring.data-source` and `SPRING_DATASOURCE` are the same prefix.
- Each entry is trimmed; a trailing `.` or `[` is dropped (`spring.datasource.` is `spring.datasource`).

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

```yaml
# 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`

```yaml
# 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

```yaml
# 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`:

```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`):

```yaml
# 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](builders.md).

## See also

- [The builders](builders.md)
- [AOP proxies: pruning and deferring](optimizations/aop-proxies.md)
- [--dart-define keys](dart-defines.md)
- [Properties the build reads](build-properties.md)
