build.yaml and build_runner

gisila_orm registers a build_runner builder, gisila_orm|schemaBuilder. It is an alternative to dart run gisila_orm:generate for packages with one schema file.

When to use: only if your workflow already runs build_runner and you have a single schema file. Prefer generate: it supports several schema files and writes incremental migrations, which the builder doesn’t.

What the package declares

# gisila_orm's own build.yaml
builders:
  schemaBuilder:
    import: "package:gisila_orm/generators/schema_builder.dart"
    builder_factories: ["schemaBuilder"]
    build_extensions:
      ".gisila.yaml": [".gisila.g.dart", ".gisila.up.sql", ".gisila.down.sql"]
      ".gisila.yml":  [".gisila.g.dart", ".gisila.up.sql", ".gisila.down.sql"]
    auto_apply: dependents
    build_to: source

Setting	Effect
auto_apply: dependents	Runs automatically in any package that depends on gisila_orm. No build.yaml needed in your package.
build_to: source	Outputs are written next to the input, in your source tree. Commit them.
Inputs	Each *.gisila.yaml / *.gisila.yml.
Outputs	<stem>.gisila.g.dart, <stem>.gisila.up.sql, <stem>.gisila.down.sql.

Behaviour

Situation	Result
One schema file in the package	Generates the three outputs beside it, the same content generate would write.
Two or more schema files	Generates nothing and logs that you should run dart run gisila_orm:generate. build_runner can’t merge several inputs into one shared output.
Validation errors	Logs the diagnostics and fails the build.
Invalid default:	Logs error[invalid_default] and fails the build.

Files under .gisila/ and files named project.gisila.yaml are ignored. The builder doesn’t write incremental migrations or update the snapshot.

Configuring it in your package

To restrict which files the builder reads, or to turn it off, add a build.yaml to your package:

targets:
  $default:
    builders:
      gisila_orm|schemaBuilder:
        generate_for:
          include:
            - lib/models/**.gisila.yaml

# Disable it when you use `dart run gisila_orm:generate`
targets:
  $default:
    builders:
      gisila_orm|schemaBuilder:
        enabled: false

The builder takes no options.

Disabling it is worth considering when you have other build_runner generators: with several schema files it does nothing anyway, and with one it would rewrite the same files generate writes.

Running it

dart run build_runner build
# or, through the generate wrapper (adds --delete-conflicting-outputs):
dart run gisila_orm:generate --build-runner

Caution

--delete-conflicting-outputs deletes generated files build_runner considers stale. Don’t combine it with --build-filter, which can make build_runner delete outputs outside the filter. Use --no-delete with generate --build-runner to leave it off.

SchemaBuilder

Builder schemaBuilder(BuilderOptions options); // factory named in build.yaml
class SchemaBuilder implements Builder { ... }

Exported from package:gisila_orm/generators/schema_builder.dart. You don’t use it directly.

See also: CLI commands, The codegen pipeline.