www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - Idiomatic way to add examples to dub package

reply FreeSlave <freeslave93 gmail.com> writes:
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.
Apr 26
next sibling parent reply drug <drug2004 bk.ru> writes:
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.
Apr 27
parent reply Laurent =?UTF-8?B?VHLDqWd1aWVy?= <laurent.treguier.sink gmail.com> writes:
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
Apr 27
parent drug <drug2004 bk.ru> writes:
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
Apr 27
prev sibling parent reply Basile B. <b2.temp gmx.com> writes:
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.
Apr 27
parent reply FreeSlave <freeslave93 gmail.com> writes:
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.
Apr 28
parent bauss <jj_1337 live.dk> writes:
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.
Apr 28