Are you happy with your logging solution? Would you help us out by taking a 30-second survey? Click here

source_gen

Automatic source code generation for Dart

Subscribe to updates I use source_gen


Statistics on source_gen

Number of watchers on Github 57
Number of open issues 1
Average time to close an issue 4 months
Main language Dart
Average time to merge a PR about 13 hours
Open pull requests 2+
Closed pull requests 14+
Last commit over 1 year ago
Repo Created over 4 years ago
Repo Last Updated over 1 year ago
Size 548 KB
Homepage https://pub.dartl...
Organization / Authordart-lang
Latest Releasev0.7.6
Contributors10
Page Updated
Do you use source_gen? Leave a review!
View source_gen activity
View on github
Fresh, new opensource launches 🚀🚀🚀
Trendy new open source projects in your inbox! View examples

Subscribe to our mailing list

Evaluating source_gen for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)

source_gen

Build Status Pub Package Version Join the chat on Gitter

Overview

source_gen provides utilities for automated source code generation for Dart:

  • A tool for generating code that is part of your Dart project.
  • A framework for creating and using multiple code generators in a single project.
  • A convention for human and tool generated Dart code to coexist with clean separation.

It's main purpose is to expose a developer-friendly API on top of lower-level packages like the analyzer or build. You don't have to use source_gen in order to generate source code; we also expose a set of library APIs that might be useful in your generators.

Quick Start Guide

Because source_gen is a package, not an executable, it should be included as a dependency in your project. If you are creating a generator for others to use (for example, a JSON serialization generator) or a library that builds on top of source_gen include it in your pubspec dependencies:

dependencies:
  source_gen:

If you're only using source_gen in your own project to generate code, and then you publish that code (generated code included), then you can simply add as a dev_dependency:

dev_dependencies:
  source_gen:

Once you have source_gen setup, you should reference the examples below.

Creating a generator

Extend the Generator or GeneratorForAnnotation class and source_gen will call your generator for a Dart library or for each element within a library tagged with the annotation you are interested in.

Running generators

source_gen is based on the build package. Use a PartBuilder or LibraryBuilder to wrap your Generator as a Builder which can be run using a build system compatible with package:build. See the build package documentation for information on running Builders.

FAQ

What is the difference between source_gen and build?

Build is a platform-agnostic framework for Dart asset or code generation that is pluggable into multiple build systems including barback (pub/dart transformers), bazel, and standalone tools like build_runner. You could also build your own.

Meanwhile, source_gen provides an API and tooling that is easily usable on top of build to make common tasks easier and more developer friendly. For example the PartBuilder class wraps one or more Generator instances to make a Builder which creates part of files, while the LibraryBuilder class wraps a single Generator to make a Builder which creates Dart library files.

What is the difference between source_gen and transformers?

Dart transformers are often used to create and modify code and assets as part of a Dart project.

Transformers allow modification of existing code and encapsulates changes by having developers use pub commands run, serve, and build. Unfortunately the API exposed by transformers hinder fast incremental builds, output caching, and predictability, so we introduced builders as part of package:build.

Builders and source_gen provide for a different model: outputs must be declared ahead of time and code is generated and updated as part of a project. It is designed to create part or standalone files that augment developer maintained Dart libraries. For example AngularDart uses build and source_gen to compile HTML and annotation metadata into plain .dart code.

Unlike transformers, generated code MAY be checked in as part of your project source, although the decision may vary depending on project needs.

Generated code SHOULD be included when publishing a project as a pub package. The fact that source_gen is used in a package is an implementation detail.

source_gen open issues Ask a question     (View All Issues)
  • almost 3 years Shouldn't require library name for annotation libraries
  • almost 3 years JsonSerialization: option on fields/properties to omit empty List/Map
  • almost 3 years Annotations do not support `Function`
  • over 3 years Handle missing constructor more cleanly
  • over 3 years Annotations do not support enums and user defined constant objects
  • over 3 years Add an annotation to specify the desired location for the generated files
  • over 3 years JsonSerializable: support send maps with trivial, non-String keys
  • almost 4 years Avoid generating empty files
  • almost 4 years JsonSerializable: add option to omit null fields in toJson
  • about 4 years JsonSerial: include type params in mixins
  • about 4 years Provide way to exclude some generators from command line.
  • about 4 years Provide a way to specify an output path
  • about 4 years Option to generate an instance "updateFromJson" mixin method
  • about 4 years JsonSerializable: supported nested json objects
  • over 4 years Option to generate a part per-file, instead of pre-library
  • over 4 years Ability to specify a directory(root) to place generated code
  • over 4 years Test to ensure generators NEVER run over code defined in `.g.dart` files
  • over 4 years Support incremental generations
  • over 4 years Model grouping class generation within a single (abstract?) class
  • over 4 years strategy to work with WebStorm/IntelliJ
  • over 4 years strategy to work with sublime
  • over 4 years standardize the generated names based on the generator
  • over 4 years Hint to include part definition
  • over 4 years Looking into TODO/Deprecated tasks for generated members
source_gen open pull requests (View All Pulls)
  • Add an incremental generator
  • Refer to library by URL.
source_gen list of languages used
source_gen latest release notes
v0.7.6 v0.7.6

0.7.6

  • TypeChecker now throws an UnresolvedAnnotationException with a more detailed exception body (and properties useful for further debugging) instead of Could not resolve @null.
v0.7.5+1 v0.7.5+1
  • LibraryBuilder and PartBuilder now have a more readable toString(), which is useful when emitting a warning or error in a build system. For example you may see Generating .g.dart: MyBuilder instead of Instance of LibraryBuilder in your build logs.
v0.7.4+2 v0.7.4+2
  • BUG FIX: ConstantReader.revive() now properly returns no URL fragment when the constant expression is resolved from a top-level or static-field. The documentation had said otherwise, and it was impossible to tell the difference between a constructor and a field. Now, fields are always in the form of accessor = {clazz}.{field} or {topLevelField}.

  • Fix file URIs on windows.

Other projects in Dart