Build Runnerでコードを生成する

Transcript

1. lcdsmao Build Runnerで コードを生成する Flutter × Kotlin Multiplatform by CyberAgent #3 2021/4/27
2. About Me lcdsmao lcdsmao Mao Yufeng
3. Agenda - コード生成とは？ - コード生成Package紹介 - 実際プロダクションでコード生成した例
4. Top 3 Most Used Command? >flutter pub run build_runner build
5. The process of build runner Source files Code generator Generated files
6. Packages for code generation - build: - build_runnerの処理対象Builderを提供する。 Builderを継承して、コード生成ロジックが定義できる。 - https://pub.dev/packages/build - source_gen (optional) - Builderのwrapper、Dartファイルをより生成しやすくする。 - https://pub.dev/packages/source_gen - code_builder (optional) - Dartのソースコードを生成する。 (JavaPoet,KotlinPoetと似ている。) - https://pub.dev/packages/code_builder - build_config, analyzer, et al. (transive dependencies)
7. Package: build
8. Package: build - Builder Builderを継承して、コード生成のビジネスロジック定義する。 - BuildStep 外部のファイルとやりとりするもの。ファイルの読み取りと書き込み、Dartのソースファイルの解析ができる。 - Resolver Analyzerを経由で、Dartのソースファイルを静的に分析することができる。
9. Defination: Builder /// The basic builder class, used to build new files from existing ones. abstract class Builder { /// Mapping from input file extension to output file extensions. Map<String, List<String>> get buildExtensions; /// Generates the outputs for a given [BuildStep]. FutureOr<void> build(BuildStep buildStep); }
10. A builder that copy dart files (1 → 1) class CopyBuilder implements Builder { @override final buildExtensions = const { '.dart': ['.dart.copy'] }; @override Future<void> build(BuildStep buildStep) async { final inputId = buildStep.inputId; final copy = inputId.addExtension('.copy'); final contents = await buildStep.readAsString(inputId); await buildStep.writeAsString(copy, contents); } } --lib |--foo.dart +--bar.dart ↓ --lib |--foo.dart |--foo.dart.copy |--bar.dart +--bar.dart.copy
11. Static analysis of dart source code @override Future<void> build(BuildStep buildStep) async { final LibraryElement inputLibrary = await buildStep.inputLibrary; // Get all imports final List<ImportElement> imports = inputLibrary.imports; // Find element with name of foo final List<Element> topElements = inputLibrary.topLevelElements; // Generate content ... }
12. A bulder that export all files (n → 1) class ExportAllBuilder implements Builder { @override Map<String, List<String>> get buildExtensions { return const { r'$lib$': ['export.dart'], }; } @override Future<void> build(BuildStep buildStep) async { await for (final input in buildStep.findAssets(Glob('lib/*.dart'))) { // do something } } }
13. Export custom builder to build runner // my_builder/lib/builder.dart Builder copyBuilder(BuilderOptions options) => CopyBuilder(); # my_builder/build.yaml builders: copy: import: "package:my_builder/builder.dart" builder_factories: ["copyBuilder"] build_extensions: {".dart": [".copy.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 /// Creates a [Builder] honoring the configuation in [options]. typedef BuilderFactory = Builder Function(BuilderOptions options);
14. build docs https://github.com/dart-lang/build/tree/master/docs
15. Package: source_gen
16. Package: source_gen Subclasses of Builder: - LibraryBuilder - SharedPartBuilder - PartBuilder Generator Generatorを継承する
17. Use LibraryBuilder with Genreator class MyGenerator extends Generator { @override String generate(LibraryReader library, BuildStep buildStep) { final LibraryElement libraryElement = library.element; return '// generated content ...'; } } Builder myLibraryBuilder(BuilderOptions options) => LibraryBuilder( MyGenerator(), generatedExtension: '.copy.dart', );
18. A Generator that read annotated value class MyAnnotation { const MyAnnotation(this.value); final String value; } class MyGenerator extends GeneratorForAnnotation<MyAnnotation> { @override FutureOr<String> generateForAnnotatedElement( Element element, ConstantReader annotation, BuildStep buildStep) { final value = annotation.read('value').stringValue; return 'const ${element.displayName} = \'$value\';'; } }
19. Package: code_builder
20. Define a class named Animal final animal = Class((b) => b ..name = 'Animal' ..methods.add(Method.returnsVoid((b) => b ..name = 'eat' ..body = const Code("print('Yum');")))); class Animal { void eat() => print('Yum!'); } ↓
21. Generated code require some imports import 'dart:async'; final controller = StreamController<int>();
22. Definition: Reference /// A reference to [symbol], such as a class, or top-level method or field. Reference refer(String symbol, [String url]) => Reference(symbol, url);
23. Use Reference final Reference streamControllerRefer = refer('StreamController()', 'dart:async'); final library = Library( (b) => b..body.add(streamControllerRefer.assignFinal('controller').statement), ); // Collects references and automatically allocates imports. final emitter = DartEmitter(Allocator()); final content = library.accept(emitter); import 'dart:async'; final controller = StreamController<int>(); content:
24. code_builder examples Test code: https://github.com/dart-lang/code_builder/tree/master/test/specs
25. Example
26. Riverpod final someProvider = Provider((ref) { // something }); // In test ProviderScope( overrides: [ provider.overrideWithValue(someValue), ], child: SomeWidget(), );
27. AppThemeModeState final appThemeModeStateProvider = StateNotifierProvider( (_) => AppThemeModeState(), ); @FakeState(ThemeMode.dark) class AppThemeModeState extends StateNotifier<ThemeMode?> { AppThemeModeState() : super(null); void toggle() { state = state == ThemeMode.light ? ThemeMode.dark : ThemeMode.light; } }
28. Definition: FakeState class FakeState { const FakeState(this.defaultValue); final Object? defaultValue; }
29. Definition: FakeStateNotifier class FakeStateNotifier<T> extends StateNotifier<T> { FakeStateNotifier(T state) : super(state); @override dynamic noSuchMethod(Invocation invocation) { if (invocation.isMethod) { return null; } return super.noSuchMethod(invocation); } }
30. Generate fake state and ProviderScope overrides // theme_mode_state.fake.dart class FakeAppThemeModeState extends FakeStateNotifier<ThemeMode?> implements AppThemeModeState { FakeAppThemeModeState([ThemeMode? state = ThemeMode.dark]) : super(state); } // generated_state_overrides.dart final defaultStateOverrides = <Override>[ appThemeModeStateProvider.overrideWithValue(FakeAppThemeModeState()), // ... ]; // In test ProviderScope( overrides: [ ...defaultStateOverrides, ], child: SomeWidget(), );
31. Recap
32. Recap - 1対１のコード生成はsource_genを使った方が楽かも - n対mのコード生成はbuildを直接使う必要 - 複雑なコード生成はcode_builderを使いましょう - プロダクションコードに対してコード生成したら便利かも
33. 宣伝 The Flutter code generator for your assets, fonts, colors, … — Get rid of all String-based APIs. https://github.com/FlutterGen/flutter_gen
35. PS
36. An annotation that has an object value // package:some_builder class ObjectAnnotation { const ObjectAnnotation(this.value); final Object value; } // package:my_flutter_project enum Platform { android, ios } @ObjectAnnotation(Platform.android) final foo = 123;
37. Read the source of annotation class ObjectGenerator extends GeneratorForAnnotation<MyAnnotation> { @override FutureOr<String> generateForAnnotatedElement( Element element, ConstantReader annotation, BuildStep buildStep) { final ElementAnnotation elementAnnotation = element.metadata.first; // Read the source directly instead of using `ConstantReader annoation` final source = elementAnnotation.toSource(); final value = source.substring( '@ObjectAnnotation('.length, source.length - 1, ); return 'const ${element.displayName} = $value;'; } } @ObjectAnnotation(Platform.android) ⬇ Platform.android