cleanup: make source_gen a mono repo

Progress towards #322 by making it easier to include a fully functional example
dart-lang · Jun 10, 2018 · ccbc792 · ccbc792
1 parent 2b9157b
commit ccbc792
Show file tree

Hide file tree

Showing 37 changed files with 239 additions and 160 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -1,12 +1,24 @@
+# Created with https://github.com/dart-lang/mono_repo
 language: dart
 
-dart:
-  - dev
+jobs:
+  include:
+    - stage: analyze_format
+      script: ./tool/travis.sh dartfmt dartanalyzer
+      env: PKG="_test_annotations"
+      dart: dev
+    - stage: analyze_format
+      script: ./tool/travis.sh dartfmt dartanalyzer
+      env: PKG="source_gen"
+      dart: dev
+    - stage: unit_test
+      script: ./tool/travis.sh test
+      env: PKG="source_gen"
+      dart: dev
 
-dart_task:
-  - test
-  - dartfmt
-  - dartanalyzer
+stages:
+  - analyze_format
+  - unit_test
 
 # Only building master means that we don't run two builds for each pull request.
 branches:

diff --git a/LICENSE b/LICENSE
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1 @@
+source_gen/LICENSE
diff --git a/README.md b/README.md
diff --git a/README.md b/README.md
@@ -0,0 +1 @@
+source_gen/README.md
diff --git a/_test_annotations/.mono_repo.yml b/_test_annotations/.mono_repo.yml
@@ -0,0 +1,9 @@
+# See https://github.com/dart-lang/mono_repo for details
+dart:
+  - dev
+
+stages:
+  - analyze_format:
+    - group:
+        - dartfmt
+        - dartanalyzer: --fatal-infos --fatal-warnings .
diff --git a/source_gen/.mono_repo.yml b/source_gen/.mono_repo.yml
@@ -0,0 +1,11 @@
+# See https://github.com/dart-lang/mono_repo for details
+dart:
+  - dev
+
+stages:
+  - analyze_format:
+    - group:
+        - dartfmt
+        - dartanalyzer: --fatal-infos --fatal-warnings .
+  - unit_test:
+    - test:
diff --git a/CHANGELOG.md → source_gen/CHANGELOG.md b/CHANGELOG.md → source_gen/CHANGELOG.md
diff --git a/source_gen/LICENSE b/source_gen/LICENSE
@@ -0,0 +1,26 @@
+Copyright 2015, the Dart project authors. All rights reserved.
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions and the following
+      disclaimer in the documentation and/or other materials provided
+      with the distribution.
+    * Neither the name of Google Inc. nor the names of its
+      contributors may be used to endorse or promote products derived
+      from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
diff --git a/source_gen/README.md b/source_gen/README.md
@@ -0,0 +1,127 @@
+# source_gen
+
+<p align="center">
+  <a href="https://travis-ci.org/dart-lang/source_gen">
+    <img src="https://travis-ci.org/dart-lang/source_gen.svg?branch=master" alt="Build Status" />
+  </a>
+  <a href="https://pub.dartlang.org/packages/source_gen">
+    <img src="https://img.shields.io/pub/v/source_gen.svg" alt="Pub Package Version" />
+  </a>
+  <a href="https://gitter.im/dart-lang/build">
+    <img src="https://badges.gitter.im/dart-lang/build.svg" alt="Join the chat on Gitter" />
+  </a>
+</p>
+
+## 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](https://pub.dartlang.org/packages/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`][pub_deps]:
+
+```yaml
+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`:
+
+```yaml
+dev_dependencies:
+  source_gen:
+```
+
+[pub_deps]: https://www.dartlang.org/tools/pub/dependencies
+
+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.
+
+* [Trivial example][]
+
+## Running generators
+
+`source_gen` is based on the [`build`][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]?
+
+Build is a platform-agnostic framework for Dart asset or code generation that
+is pluggable into multiple build systems including
+[barback (pub/dart transformers)][build_barback], [bazel][bazel_codegen], 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`][api:PartBuilder] class wraps one or more
+[`Generator`][api:Generator] instances to make a [`Builder`][api:Builder] which
+creates `part of` files, while the [`LibraryBuilder`][api: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`][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][angular2] 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*.
+
+<!-- Packages -->
+[angular2]: https://pub.dartlang.org/packages/angular2
+[bazel_codegen]: https://pub.dartlang.org/packages/_bazel_codegen
+[build]: https://pub.dartlang.org/packages/build
+[build_barback]: https://pub.dartlang.org/packages/build_barback
+[build_runner]: https://pub.dartlang.org/packages/build_runner
+
+<!-- Dartdoc -->
+[api:Builder]: https://www.dartdocs.org/documentation/build/latest/builder/Builder-class.html
+[api:Generator]: https://www.dartdocs.org/documentation/source_gen/latest/builder/Generator-class.html
+[api:PartBuilder]: https://www.dartdocs.org/documentation/source_gen/latest/builder/PartBuilder-class.html
+[api:LibraryBuilder]: https://www.dartdocs.org/documentation/source_gen/latest/builder/LibraryBuilder-class.html
+
+[Dart transformers]: https://www.dartlang.org/tools/pub/assets-and-transformers.html
+[Trivial example]: https://github.com/dart-lang/source_gen/blob/master/test/src/comment_generator.dart
+[build.dart]: https://github.com/dart-lang/source_gen/blob/master/build.dart
+[generate]: http://www.dartdocs.org/documentation/source_gen/latest/index.html#source_gen/source_gen@id_generate
+[build]: http://www.dartdocs.org/documentation/source_gen/latest/index.html#source_gen/source_gen@id_build
diff --git a/lib/source_gen.dart → source_gen/lib/source_gen.dart b/lib/source_gen.dart → source_gen/lib/source_gen.dart
diff --git a/lib/src/builder.dart → source_gen/lib/src/builder.dart b/lib/src/builder.dart → source_gen/lib/src/builder.dart
diff --git a/lib/src/constants/reader.dart → source_gen/lib/src/constants/reader.dart b/lib/src/constants/reader.dart → source_gen/lib/src/constants/reader.dart
diff --git a/lib/src/constants/revive.dart → source_gen/lib/src/constants/revive.dart b/lib/src/constants/revive.dart → source_gen/lib/src/constants/revive.dart
diff --git a/lib/src/constants/utils.dart → source_gen/lib/src/constants/utils.dart b/lib/src/constants/utils.dart → source_gen/lib/src/constants/utils.dart
diff --git a/lib/src/generated_output.dart → source_gen/lib/src/generated_output.dart b/lib/src/generated_output.dart → source_gen/lib/src/generated_output.dart
diff --git a/lib/src/generator.dart → source_gen/lib/src/generator.dart b/lib/src/generator.dart → source_gen/lib/src/generator.dart
diff --git a/lib/src/generator_for_annotation.dart → ...gen/lib/src/generator_for_annotation.dart b/lib/src/generator_for_annotation.dart → ...gen/lib/src/generator_for_annotation.dart
diff --git a/lib/src/library.dart → source_gen/lib/src/library.dart b/lib/src/library.dart → source_gen/lib/src/library.dart
diff --git a/lib/src/span_for_element.dart → source_gen/lib/src/span_for_element.dart b/lib/src/span_for_element.dart → source_gen/lib/src/span_for_element.dart
diff --git a/lib/src/type_checker.dart → source_gen/lib/src/type_checker.dart b/lib/src/type_checker.dart → source_gen/lib/src/type_checker.dart
diff --git a/lib/src/utils.dart → source_gen/lib/src/utils.dart b/lib/src/utils.dart → source_gen/lib/src/utils.dart
diff --git a/pubspec.yaml → source_gen/pubspec.yaml b/pubspec.yaml → source_gen/pubspec.yaml
@@ -17,4 +17,4 @@ dev_dependencies:
   collection: ^1.1.2
   test: ^0.12.3
   _test_annotations:
-    path: ./_test_annotations
+    path: ../_test_annotations
diff --git a/test/builder_test.dart → source_gen/test/builder_test.dart b/test/builder_test.dart → source_gen/test/builder_test.dart
diff --git a/test/constants/utils_test.dart → source_gen/test/constants/utils_test.dart b/test/constants/utils_test.dart → source_gen/test/constants/utils_test.dart
diff --git a/test/constants_test.dart → source_gen/test/constants_test.dart b/test/constants_test.dart → source_gen/test/constants_test.dart
diff --git a/test/generator_for_annotation_test.dart → ...n/test/generator_for_annotation_test.dart b/test/generator_for_annotation_test.dart → ...n/test/generator_for_annotation_test.dart
diff --git a/test/library/find_type_test.dart → source_gen/test/library/find_type_test.dart b/test/library/find_type_test.dart → source_gen/test/library/find_type_test.dart
diff --git a/test/library/path_to_url_test.dart → ...ce_gen/test/library/path_to_url_test.dart b/test/library/path_to_url_test.dart → ...ce_gen/test/library/path_to_url_test.dart
diff --git a/test/span_for_element_test.dart → source_gen/test/span_for_element_test.dart b/test/span_for_element_test.dart → source_gen/test/span_for_element_test.dart
diff --git a/test/src/comment_generator.dart → source_gen/test/src/comment_generator.dart b/test/src/comment_generator.dart → source_gen/test/src/comment_generator.dart
diff --git a/test/src/unformatted_code_generator.dart → .../test/src/unformatted_code_generator.dart b/test/src/unformatted_code_generator.dart → .../test/src/unformatted_code_generator.dart
diff --git a/test/test_files/annotated_classes.dart → ...en/test/test_files/annotated_classes.dart b/test/test_files/annotated_classes.dart → ...en/test/test_files/annotated_classes.dart
diff --git a/test/test_files/annotated_classes_part.dart → ...st/test_files/annotated_classes_part.dart b/test/test_files/annotated_classes_part.dart → ...st/test_files/annotated_classes_part.dart
diff --git a/test/test_files/annotation_part.dart → ..._gen/test/test_files/annotation_part.dart b/test/test_files/annotation_part.dart → ..._gen/test/test_files/annotation_part.dart
diff --git a/test/test_files/annotations.dart → source_gen/test/test_files/annotations.dart b/test/test_files/annotations.dart → source_gen/test/test_files/annotations.dart
diff --git a/test/type_checker_test.dart → source_gen/test/type_checker_test.dart b/test/type_checker_test.dart → source_gen/test/type_checker_test.dart
diff --git a/test/utils_test.dart → source_gen/test/utils_test.dart b/test/utils_test.dart → source_gen/test/utils_test.dart