|
| 1 | +# source_gen |
| 2 | + |
| 3 | +<p align="center"> |
| 4 | + <a href="https://travis-ci.org/dart-lang/source_gen"> |
| 5 | + <img src="https://travis-ci.org/dart-lang/source_gen.svg?branch=master" alt="Build Status" /> |
| 6 | + </a> |
| 7 | + <a href="https://pub.dartlang.org/packages/source_gen"> |
| 8 | + <img src="https://img.shields.io/pub/v/source_gen.svg" alt="Pub Package Version" /> |
| 9 | + </a> |
| 10 | + <a href="https://gitter.im/dart-lang/build"> |
| 11 | + <img src="https://badges.gitter.im/dart-lang/build.svg" alt="Join the chat on Gitter" /> |
| 12 | + </a> |
| 13 | +</p> |
| 14 | + |
| 15 | +## Overview |
| 16 | + |
| 17 | +`source_gen` provides utilities for automated source code generation for Dart: |
| 18 | + |
| 19 | +* A **tool** for generating code that is part of your Dart project. |
| 20 | +* A **framework** for creating and using multiple code generators in a single |
| 21 | + project. |
| 22 | +* A **convention** for human and tool generated Dart code to coexist with clean |
| 23 | + separation. |
| 24 | + |
| 25 | +It's main purpose is to expose a developer-friendly API on top of lower-level |
| 26 | +packages like the [analyzer](https://pub.dartlang.org/packages/analyzer) or |
| 27 | +[build][]. You don't _have_ to use `source_gen` in order to generate source code; |
| 28 | +we also expose a set of library APIs that might be useful in your generators. |
| 29 | + |
| 30 | +## Quick Start Guide |
| 31 | + |
| 32 | +Because `source_gen` is a package, not an executable, it should be included as |
| 33 | +a dependency in your project. If you are creating a generator for others to use |
| 34 | +(for example, a JSON serialization generator) or a library that builds on top |
| 35 | +of `source_gen` include it in your [pubspec `dependencies`][pub_deps]: |
| 36 | + |
| 37 | +```yaml |
| 38 | +dependencies: |
| 39 | + source_gen: |
| 40 | +``` |
| 41 | +
|
| 42 | +If you're only using `source_gen` in your own project to generate code, and |
| 43 | +then you publish that code (generated code included), then you can simply add |
| 44 | +as a `dev_dependency`: |
| 45 | + |
| 46 | +```yaml |
| 47 | +dev_dependencies: |
| 48 | + source_gen: |
| 49 | +``` |
| 50 | + |
| 51 | +[pub_deps]: https://www.dartlang.org/tools/pub/dependencies |
| 52 | + |
| 53 | +Once you have `source_gen` setup, you should reference the examples below. |
| 54 | + |
| 55 | +## Creating a generator |
| 56 | + |
| 57 | +Extend the `Generator` or `GeneratorForAnnotation` class and `source_gen` will |
| 58 | +call your generator for a Dart library or for each element within a library |
| 59 | +tagged with the annotation you are interested in. |
| 60 | + |
| 61 | +* [Trivial example][] |
| 62 | + |
| 63 | +## Running generators |
| 64 | + |
| 65 | +`source_gen` is based on the [`build`][build] package. Use a `PartBuilder` or |
| 66 | +`LibraryBuilder` to wrap your `Generator` as a `Builder` which can be run using |
| 67 | +a build system compatible with `package:build`. See the build package |
| 68 | +documentation for information on running Builders. |
| 69 | + |
| 70 | +## FAQ |
| 71 | + |
| 72 | +### What is the difference between `source_gen` and [`build`][build]? |
| 73 | + |
| 74 | +Build is a platform-agnostic framework for Dart asset or code generation that |
| 75 | +is pluggable into multiple build systems including |
| 76 | +[barback (pub/dart transformers)][build_barback], [bazel][bazel_codegen], and |
| 77 | +standalone tools like [build_runner][]. You could also build your own. |
| 78 | + |
| 79 | +Meanwhile, `source_gen` provides an API and tooling that is easily usable on |
| 80 | +top of `build` to make common tasks easier and more developer friendly. For |
| 81 | +example the [`PartBuilder`][api:PartBuilder] class wraps one or more |
| 82 | +[`Generator`][api:Generator] instances to make a [`Builder`][api:Builder] which |
| 83 | +creates `part of` files, while the [`LibraryBuilder`][api:LibraryBuilder] class |
| 84 | +wraps a single Generator to make a `Builder` which creates Dart library files. |
| 85 | + |
| 86 | +### What is the difference between `source_gen` and transformers? |
| 87 | + |
| 88 | +[Dart transformers][] are often used to create and modify code and assets as part |
| 89 | +of a Dart project. |
| 90 | + |
| 91 | +Transformers allow modification of existing code and encapsulates changes by |
| 92 | +having developers use `pub` commands – `run`, `serve`, and `build`. |
| 93 | +Unfortunately the API exposed by transformers hinder fast incremental builds, |
| 94 | +output caching, and predictability, so we introduced _builders_ as part of |
| 95 | +[`package:build`][build]. |
| 96 | + |
| 97 | +Builders and `source_gen` provide for a different model: outputs _must_ be |
| 98 | +declared ahead of time and code is generated and updated as part of a project. |
| 99 | +It is designed to create *part* _or_ standalone files that augment developer |
| 100 | +maintained Dart libraries. For example [AngularDart][angular2] uses `build` and |
| 101 | +`source_gen` to "compile" HTML and annotation metadata into plain `.dart` code. |
| 102 | + |
| 103 | +Unlike _transformers_, generated code **MAY** be checked in as part of your |
| 104 | +project source, although the decision may vary depending on project needs. |
| 105 | + |
| 106 | +Generated code **SHOULD** be included when publishing a project as a *pub |
| 107 | +package*. The fact that `source_gen` is used in a package is an *implementation |
| 108 | +detail*. |
| 109 | + |
| 110 | +<!-- Packages --> |
| 111 | +[angular2]: https://pub.dartlang.org/packages/angular2 |
| 112 | +[bazel_codegen]: https://pub.dartlang.org/packages/_bazel_codegen |
| 113 | +[build]: https://pub.dartlang.org/packages/build |
| 114 | +[build_barback]: https://pub.dartlang.org/packages/build_barback |
| 115 | +[build_runner]: https://pub.dartlang.org/packages/build_runner |
| 116 | + |
| 117 | +<!-- Dartdoc --> |
| 118 | +[api:Builder]: https://www.dartdocs.org/documentation/build/latest/builder/Builder-class.html |
| 119 | +[api:Generator]: https://www.dartdocs.org/documentation/source_gen/latest/builder/Generator-class.html |
| 120 | +[api:PartBuilder]: https://www.dartdocs.org/documentation/source_gen/latest/builder/PartBuilder-class.html |
| 121 | +[api:LibraryBuilder]: https://www.dartdocs.org/documentation/source_gen/latest/builder/LibraryBuilder-class.html |
| 122 | + |
| 123 | +[Dart transformers]: https://www.dartlang.org/tools/pub/assets-and-transformers.html |
| 124 | +[Trivial example]: https://github.com/dart-lang/source_gen/blob/master/test/src/comment_generator.dart |
| 125 | +[build.dart]: https://github.com/dart-lang/source_gen/blob/master/build.dart |
| 126 | +[generate]: http://www.dartdocs.org/documentation/source_gen/latest/index.html#source_gen/source_gen@id_generate |
| 127 | +[build]: http://www.dartdocs.org/documentation/source_gen/latest/index.html#source_gen/source_gen@id_build |
0 commit comments