Examples: add trivial Library and SharedPart builder examples (#390)

Progress towards #322

.travis.yml

@@ -8,6 +8,36 @@ jobs:
       script: ./tool/travis.sh dartfmt dartanalyzer
       env: PKG="_test_annotations"
       dart: dev
+    - stage: analyze_format
+      name: "SDK: dev - DIR: example - TASKS: [dartfmt -n --set-exit-if-changed ., dartanalyzer --fatal-infos --fatal-warnings .]"
+      script: ./tool/travis.sh dartfmt dartanalyzer
+      env: PKG="example"
+      dart: dev
+    - stage: analyze_format
+      name: "SDK: stable - DIR: example - TASKS: [dartfmt -n --set-exit-if-changed ., dartanalyzer --fatal-infos --fatal-warnings .]"
+      script: ./tool/travis.sh dartfmt dartanalyzer
+      env: PKG="example"
+      dart: stable
+    - stage: analyze_format
+      name: "SDK: dev - DIR: example_usage - TASKS: [dartfmt -n --set-exit-if-changed ., dartanalyzer --fatal-infos --fatal-warnings .]"
+      script: ./tool/travis.sh dartfmt dartanalyzer
+      env: PKG="example_usage"
+      dart: dev
+    - stage: analyze_format
+      name: "SDK: stable - DIR: example_usage - TASKS: [dartfmt -n --set-exit-if-changed ., dartanalyzer --fatal-infos --fatal-warnings .]"
+      script: ./tool/travis.sh dartfmt dartanalyzer
+      env: PKG="example_usage"
+      dart: stable
+    - stage: unit_test
+      name: "SDK: dev - DIR: example_usage - TASKS: pub run test --run-skipped"
+      script: ./tool/travis.sh test
+      env: PKG="example_usage"
+      dart: dev
+    - stage: unit_test
+      name: "SDK: stable - DIR: example_usage - TASKS: pub run test --run-skipped"
+      script: ./tool/travis.sh test
+      env: PKG="example_usage"
+      dart: stable
     - stage: analyze_format
       name: "SDK: dev - DIR: source_gen - TASKS: [dartfmt -n --set-exit-if-changed ., dartanalyzer --fatal-infos --fatal-warnings .]"
       script: ./tool/travis.sh dartfmt dartanalyzer
@@ -41,4 +71,5 @@ branches:
 cache:
   directories:
     - "$HOME/.pub-cache"
+    - example_usage/.dart_tool/build
     - source_gen/.dart_tool/build

example/build.yaml

@@ -0,0 +1,30 @@
+# Read about `build.yaml` at https://pub.dartlang.org/packages/build_config
+builders:
+  # name of the builder
+  member_count:
+    # library URI containing the builder - maps to `lib/member_count_library_generator.dart`
+    import: "package:source_gen_example/builder.dart"
+    # Name of the function in the above library to call.
+    builder_factories: ["metadataLibraryBuilder"]
+    # The mapping from the source extension to the generated file extension
+    build_extensions: {".dart": [".info.dart"]}
+    # Will automatically run on any package that depends on it
+    auto_apply: dependents
+    # Generate the output directly into the package, not to a hidden cache dir
+    build_to: source
+
+  property_product:
+    import: "package:source_gen_example/builder.dart"
+    builder_factories: ["productBuilder"]
+    build_extensions: {".dart": ["product.g.part"]}
+    auto_apply: dependents
+    build_to: cache
+    applies_builders: ["source_gen|combining_builder"]
+
+  property_sum:
+    import: "package:source_gen_example/builder.dart"
+    builder_factories: ["sumBuilder"]
+    build_extensions: {".dart": ["sum.g.part"]}
+    auto_apply: dependents
+    build_to: cache
+    applies_builders: ["source_gen|combining_builder"]

example/lib/builder.dart

@@ -0,0 +1,30 @@
+// Copyright (c) 2018, the Dart project authors. Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+/// Configuration for using `package:build`-compatible build systems.
+///
+/// See:
+/// * [build_runner](https://pub.dartlang.org/packages/build_runner)
+///
+/// This library is **not** intended to be imported by typical end-users unless
+/// you are creating a custom compilation pipeline. See documentation for
+/// details, and `build.yaml` for how these builders are configured by default.
+library source_gen_example.builder;
+
+import 'package:build/build.dart';
+import 'package:source_gen/source_gen.dart';
+
+import 'src/member_count_library_generator.dart';
+import 'src/property_product_generator.dart';
+import 'src/property_sum_generator.dart';
+
+Builder metadataLibraryBuilder(BuilderOptions options) =>
+    LibraryBuilder(MemberCountLibraryGenerator(),
+        generatedExtension: '.info.dart');
+
+Builder productBuilder(BuilderOptions options) =>
+    SharedPartBuilder([PropertyProductGenerator()], 'product');
+
+Builder sumBuilder(BuilderOptions options) =>
+    SharedPartBuilder([PropertySumGenerator()], 'sum');

example/lib/src/member_count_library_generator.dart

@@ -0,0 +1,20 @@
+// Copyright (c) 2018, the Dart project authors. Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'package:build/build.dart';
+import 'package:source_gen/source_gen.dart';
+
+import 'utils.dart';
+
+class MemberCountLibraryGenerator extends Generator {
+  @override
+  String generate(LibraryReader library, BuildStep buildStep) {
+    final topLevelVarCount = topLevelNumVariables(library).length;
+
+    return '''
+// Source library: ${library.element.source.uri}
+const topLevelNumVarCount = $topLevelVarCount;
+''';
+  }
+}

example/lib/src/property_product_generator.dart

@@ -0,0 +1,21 @@
+// Copyright (c) 2018, the Dart project authors. Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'package:build/build.dart';
+import 'package:source_gen/source_gen.dart';
+
+import 'utils.dart';
+
+class PropertyProductGenerator extends Generator {
+  @override
+  String generate(LibraryReader library, BuildStep buildStep) {
+    final productNames = topLevelNumVariables(library)
+        .map((element) => element.name)
+        .join(' * ');
+
+    return '''
+num allProduct() => $productNames;
+''';
+  }
+}

example/lib/src/property_sum_generator.dart

@@ -0,0 +1,21 @@
+// Copyright (c) 2018, the Dart project authors. Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'package:build/build.dart';
+import 'package:source_gen/source_gen.dart';
+
+import 'utils.dart';
+
+class PropertySumGenerator extends Generator {
+  @override
+  String generate(LibraryReader library, BuildStep buildStep) {
+    final sumNames = topLevelNumVariables(library)
+        .map((element) => element.name)
+        .join(' + ');
+
+    return '''
+num allSum() => $sumNames;
+''';
+  }
+}

example/lib/src/utils.dart

@@ -0,0 +1,13 @@
+// Copyright (c) 2018, the Dart project authors. Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'package:analyzer/dart/element/element.dart';
+import 'package:source_gen/source_gen.dart';
+
+/// Returns all [TopLevelVariableElement] members in [reader]'s library that
+/// have a type of [num].
+Iterable<TopLevelVariableElement> topLevelNumVariables(LibraryReader reader) =>
+    reader.allElements.whereType<TopLevelVariableElement>().where((element) =>
+        element.type
+            .isAssignableTo(reader.element.context.typeProvider.numType));

example/mono_pkg.yaml

@@ -0,0 +1,10 @@
+# See https://github.com/dart-lang/mono_repo for details
+dart:
+  - dev
+  - stable
+
+stages:
+  - analyze_format:
+    - group:
+        - dartfmt
+        - dartanalyzer: --fatal-infos --fatal-warnings .

example/pubspec.yaml

@@ -0,0 +1,12 @@
+name: source_gen_example
+
+environment:
+  sdk: '>=2.0.0 <3.0.0'
+
+dependencies:
+  build: ^1.0.0
+  source_gen: ^0.9.0
+
+dependency_overrides:
+  source_gen:
+    path: ../source_gen

example_usage/build.yaml

@@ -0,0 +1,10 @@
+# Read about `build.yaml` at https://pub.dartlang.org/packages/build_config
+targets:
+  $default:
+    builders:
+      # Configure the builder `pkg_name|builder_name`
+      # In this case, the member_count builder defined in `../example`
+      source_gen_example|member_count:
+        # Only run this builder on the specified input.
+        generate_for:
+          - lib/library_source.dart

example_usage/dart_test.yaml

@@ -0,0 +1,3 @@
+tags:
+  presubmit-only:
+    skip: "Should only be run during presubmit"

example_usage/lib/library_source.dart

@@ -0,0 +1,10 @@
+// Copyright (c) 2018, the Dart project authors. Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'dart:math';
+
+part 'library_source.g.dart';
+
+final answer = 42;
+final tau = pi * 2;

example_usage/mono_pkg.yaml

@@ -0,0 +1,16 @@
+# See https://github.com/dart-lang/mono_repo for details
+dart:
+  - dev
+  - stable
+
+stages:
+  - analyze_format:
+    - group:
+        - dartfmt
+        - dartanalyzer: --fatal-infos --fatal-warnings .
+  - unit_test:
+      - test: --run-skipped
+
+cache:
+  directories:
+    - .dart_tool/build

example_usage/pubspec.yaml

@@ -0,0 +1,15 @@
+name: source_gen_example_usage
+
+environment:
+  sdk: '>=2.0.0 <3.0.0'
+
+dev_dependencies:
+  build_runner: ^1.0.0
+  build_verify: ^1.1.0
+  source_gen_example:
+    path: ../example
+  test: ^1.5.1
+
+dependency_overrides:
+  source_gen:
+    path: ../source_gen

example_usage/test/ensure_build_test.dart

@@ -0,0 +1,13 @@
+// Copyright (c) 2017, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+@TestOn('vm')
+@Tags(['presubmit-only'])
+import 'package:build_verify/build_verify.dart';
+import 'package:test/test.dart';
+
+void main() {
+  test('ensure_build',
+      () => expectBuildClean(packageRelativeDirectory: 'example_usage'));
+}

tool/travis.sh

@@ -34,6 +34,11 @@ while (( "$#" )); do
     echo -e 'dartfmt -n --set-exit-if-changed .'
     dartfmt -n --set-exit-if-changed . || EXIT_CODE=$?
     ;;
+  test) echo
+    echo -e '\033[1mTASK: test\033[22m'
+    echo -e 'pub run test --run-skipped'
+    pub run test --run-skipped || EXIT_CODE=$?
+    ;;
   *) echo -e "\033[31mNot expecting TASK '${TASK}'. Error!\033[0m"
     EXIT_CODE=1
     ;;