Explain how to use this package

[Rodsevich]

I've been trying hard enough to figure out how to use this package, reading all the extense build package documentation and that... and I'm still lost.
Can someone please put some trivial e2e example in the wiki, with both the code and the commands needed to generate code and execute it in your project?
Thanks in advance

[kevmoo]

Here are two examples:

https://github.com/dart-lang/json_serializable/tree/master/json_serializable
https://github.com/kevmoo/build_cli/tree/master/build_cli

build_cli is more simple, so it might be a good spot to start.

Agreed, we need better docs here, but this may get you unblocked...

[matanlurey]

I think @kevmoo's comments are likely all we'll have at this point.

Pull requests welcome!

[kevmoo]

I'm going to reopen and keep this assigned to me. Once we publish the bits on master, I want to come back here and add an example.

[kevmoo]

I have a PR out w/ some initial examples. #390

[graphicbeacon]

Hi @kevmoo, thanks for putting up the examples. After spending hours looking over the code, its beginning to click.

However I've seen in example_usage/build.yaml this build configuration for SharedPartBuilders:

source_gen_example|property_sum:
  generate_for:
    - lib/*.dart
source_gen_example|property_product:
  generate_for:
    - lib/*.dart

And I would like to know:

Why upon removing this configuration, the contents of the build output file example_usage/lib/library_source.g.dart remain the same?

So far I've seen that it relates to this line in example_usage/lib/library_source.dart:

part 'library_source.g.dart';

Removing that line understandably does not create library_source.g.dart, so what then is the purpose of the snippet in example_usage/build.yaml?

[natebosch]

@graphicbeacon - the purpose of the generate_for argument in the example is to limit the files that are generated. By default a Builder can apply to all files in a target, and by default the target includes everything in lib/, web/, bin/, and example/ among others:

https://github.com/dart-lang/build/blob/92a4482a8407009d36f5c94601c4acdd58b64569/build_runner_core/lib/src/generate/options.dart#L21-L31

By adding a generate_for it means that this Builder would only apply to lib/*.dart (note that this is not a recursive glob, so it would not apply to subdirectories). Removing the statement would make it apply to everything in the target again, which includes the files in that glob. If you want to make it apply to nothing you could use generate_for: [] to give an empty list, or better yet use enabled: false.

[graphicbeacon]

Thank you @natebosch. That clarifies things.

I wish to cover this on my YouTube channel. I hope that will help with documentation.

[kevmoo]

@graphicbeacon – if you want to send a PR adding notes to clarify what you've learned, we'd happily add it!

[ashokgelal]

The nicely documented build.yaml is very helpful but how would someone actually run the examples? I've added build_runner package and run pub run build_runner x but no luck. I've already spent more than an hour reading through build, build_runner, and build_config docs (oh, my!) and still confused. They seem to point at each other. This package seriously lacks good documentation.

[ashokgelal]

Ok. now I kind of feel stupid. Looks like I needed to look into https://github.com/dart-lang/source_gen/tree/master/example_usage. But my comment about lack of good documentation that just doesn't point to each other still stands. Outside the official doc, any good tutorial for source_gen is also seriously lacking. Waiting for @graphicbeacon to jump in and create a serious tutorial ;) Big fan of your videos, BTW :)

[kevmoo]

Have you run 'pub upgrade' in this directory? Which SDK are you using?

…

On Sat, Apr 20, 2019 at 10:54 PM Ashok Gelal ***@***.***> wrote: Unfortunately, still no luck: [image: Screenshot 2019-04-20 23 53 04] <https://user-images.githubusercontent.com/401055/56466011-93c03600-63c7-11e9-8a65-3289ee0a6e93.png> — You are receiving this because you modified the open/close state. Reply to this email directly, view it on GitHub <#322 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAAEFCTBK5BSDWGDGR4EGDDPRP6QLANCNFSM4EY7HUPA> .

[ashokgelal]

I got it working (somehow :). Not sure why but I'm sure it was on my side