Open MartinNowak opened 7 years ago
I use sub-packages as examples for all my projects. trashcan has only one example, but probably will have more later. What about the case when there're multiple examples?
Subpackages for examples are a correct use, but for trashcan those just seems to be different commands of the same executable.
I'd even say that examples should probably be discouraged. Sub packages make sense when they are part of the public interface. For simple examples, single-file packages are usually the best choice.
I think examples are pretty useful. They allow to see how library should be used. I know that sub-configurations are not meant to provide examples but I don't see better alternative for now. Being sub-packages, examples are easily runnable via the familiar instrument (dub). Maybe dub could have mechanism specially for examples and it surely can be made easier to use than sub-packages.
I've just checked single-file package mechanism. It's pretty good. The only thing it's missing to make it into examples running engine is automatic dependency on the main package. Basically for examples dependencies: "*"
should be implicit.
Dub offers 2 ways to structure multiple targets in a single package. The basic use-case is a library with an executable (such as dub itself). It possible to simply have a library and an executable configuration in the dub.json config, they can include additional sources, and dub will even pick the appropriate config automatically (e.g. the executable config for
dub run
and the library config for dependencies).Still it happens often that the more complicated subPackage method is chosen. Which is a standalone dub project in the same source tree, usually depending on the root project.
Just one example going through the effort of lots of boilerplate files.
dub run trashcan:put -- file
https://github.com/FreeSlave/trashcan/blob/ae20dbf9d4c6d1789ed6c0f949782764802aa667/dub.json https://github.com/FreeSlave/trashcan/tree/ae20dbf9d4c6d1789ed6c0f949782764802aa667/examples/putSeems like we're badly communicating when to use configs and when to use subpackages. I've added a recipe to the cookbook, Creating a library package that also comes with an executable.