Most dub packages are libraries and should provide runnable examples.
What's the current idiomatic way to add examples? I used sub-packages with dependency on the library and "*" as version and running them as dub run :examplename
Now I've noticed vibed uses a different scheme - examples are like separate packages that are supposed to ran with --root option (if running from the library root directory) and specify the dependency with "path" property like here https://github.com/vibe-d/vibe.d/blob/master/examples/http_server/dub.json
That involves more typing when running an example but keeps the main dub.json independent from examples (no need to specify sub-packages)

Also I still don't understand if I need to include dub.selections.json in VCS repo. I read somewhere that it should be included but vibed examples don't have dub.selections.json. E.g. here https://github.com/dlang/dub/issues/829#issuecomment-215741874 jacob-carlborg  said
> For applications the dub.selection.json files should be in version control, for libraries it should not be

Examples are applications so I thought dub.selections.json should be included. But it may be an outdated information.

If there're tutorials on both topics (how to include examples and when one should include dub.selections.json in VCS), I would like to read them. I could not find any useful info on code.dlang.org regarding these issues, while those look like basic issues that must be covered in manuals.

26.04.2018 21:16, FreeSlave пишет:
> Most dub packages are libraries and should provide runnable examples.
> What's the current idiomatic way to add examples? I used sub-packages with dependency on the library and "*" as version and running them as dub run :examplename
> Now I've noticed vibed uses a different scheme - examples are like separate packages that are supposed to ran with --root option (if running from the library root directory) and specify the dependency with "path" property like here https://github.com/vibe-d/vibe.d/blob/master/examples/http_server/dub.json
> That involves more typing when running an example but keeps the main dub.json independent from examples (no need to specify sub-packages)
> 
> Also I still don't understand if I need to include dub.selections.json in VCS repo. I read somewhere that it should be included but vibed examples don't have dub.selections.json. E.g. here https://github.com/dlang/dub/issues/829#issuecomment-215741874 jacob-carlborg  said
>> For applications the dub.selection.json files should be in version control, for libraries it should not be
> 
> Examples are applications so I thought dub.selections.json should be included. But it may be an outdated information.
> 
> If there're tutorials on both topics (how to include examples and when one should include dub.selections.json in VCS), I would like to read them. I could not find any useful info on code.dlang.org regarding these issues, while those look like basic issues that must be covered in manuals.

I think that separate examples are better, it can of course depends on specific case, but in general independence simplifies at least maintenance.
dub.selections.json shouldn't be included in case of library because it should be configured at import site. in case of application it has been configured and so dub.selections.json should be included. IMHO.

On Friday, 27 April 2018 at 10:18:53 UTC, drug wrote:
> dub.selections.json shouldn't be included in case of library because it should be configured at import site. in case of application it has been configured and so dub.selections.json should be included. IMHO.

This is the way Rust packages handle their Cargo.lock file, if I'm not mistaken, and it seems reasonable to me

27.04.2018 13:58, Laurent Tréguier пишет:
> This is the way Rust packages handle their Cargo.lock file, if I'm not mistaken, and it seems reasonable to me
Exactly

On Thursday, 26 April 2018 at 18:16:01 UTC, FreeSlave wrote:
> Most dub packages are libraries and should provide runnable examples.
> What's the current idiomatic way to add examples?

IMO the most simple way (and the best too) is to put single file packages in the example folder, so that an example can just be run with DUB like that:

`dub example1.d`.

Other good point is that you can specify that the dependency to the main package is local, like here: https://github.com/BBasile/kheops/blob/master/runnable/actions_window.d#L5.

And finally the example folder is neither polluted with sub-folders nor with sub.selection JSON, FTW.

On Friday, 27 April 2018 at 12:37:04 UTC, Basile B. wrote:
> On Thursday, 26 April 2018 at 18:16:01 UTC, FreeSlave wrote:
>> Most dub packages are libraries and should provide runnable examples.
>> What's the current idiomatic way to add examples?
>
> IMO the most simple way (and the best too) is to put single file packages in the example folder, so that an example can just be run with DUB like that:
>
> `dub example1.d`.
>
> Other good point is that you can specify that the dependency to the main package is local, like here: https://github.com/BBasile/kheops/blob/master/runnable/actions_window.d#L5.
>
> And finally the example folder is neither polluted with sub-folders nor with sub.selection JSON, FTW.

That's probably the best option. No need for using subPackages, nor for creating dub.json per every example. And no --root option is needed.

On Saturday, 28 April 2018 at 15:11:31 UTC, FreeSlave wrote:
> On Friday, 27 April 2018 at 12:37:04 UTC, Basile B. wrote:
>> On Thursday, 26 April 2018 at 18:16:01 UTC, FreeSlave wrote:
>>> Most dub packages are libraries and should provide runnable examples.
>>> What's the current idiomatic way to add examples?
>>
>> IMO the most simple way (and the best too) is to put single file packages in the example folder, so that an example can just be run with DUB like that:
>>
>> `dub example1.d`.
>>
>> Other good point is that you can specify that the dependency to the main package is local, like here: https://github.com/BBasile/kheops/blob/master/runnable/actions_window.d#L5.
>>
>> And finally the example folder is neither polluted with sub-folders nor with sub.selection JSON, FTW.
>
> That's probably the best option. No need for using subPackages, nor for creating dub.json per every example. And no --root option is needed.

The difference is however with most vibe.d examples, they're each separate applications.