Allow example as special executable type

[awvwgk]

Suggested in #257 (review).

Additionally to the currently available executable and test tables an example table would allow to have usage example in a project which do not count as production executables but rather as demonstrations.

The syntax would be identical to the executable and test table with:

[[example]]
name = "demo"
source-dir = "example"  # suggestions for the default dir?
main = "main.f90"

Also, example executables can be automatically discovered like executables or test:

[build]
auto-examples = true

[milancurcic]

I love this idea. I now see that Cargo has it too.

Having examples as a kind of binary would encourage people to write more examples on how to use their libraries.

I personally learn more easily from runnable examples than from documentation.

examples/ seems to me like a good directory name. Just like Cargo.

I also think all programs in examples/ should be built automatically (like tests), without a special flag in the manifest.

[urbanjost]

I was thinking about something like this and had in mind dev/ for developer and then maybe having subdirectories like example|sample, benchmark, so as not to clutter the top directory too much, but if example/ (and benchmark/ ?) are already in common use ( any measure of the audience different package managers have?) and no one sees that becoming a dozen directories then just starting with example/ (or demo/ or sample/, I personally have no strong preference on that name) .

So should the new subcommand generate an example/ directory?

I also confuse myself when I do not adhere to a strict rule about plurals. If we are using /app and /test I think it should be /example instead of /examples. So far we have stuck to the singular and mixing that makes it harder to remember.

[milancurcic]

FWIW, Cargo uses src, benches, examples, and tests (https://doc.rust-lang.org/cargo/guide/project-layout.html).

Although "benches" is is perhaps more technically accurate, I like how "benchmarks" sounds.

[urbanjost]

OK. I think there should be a switch on new for the two new ones and that they should be adopted as above into the metrics. I waffle between whether they should be created by default with new though. I think an install should not install those files so a simple install would just be for apps. With a new category in the TOML file as proposed above it would be easy to skip installing them. With the no autobuild option you could prevent the possibly annoying build of every test and demo and benchmark every time you make a source code and just want to build your main src/ stuff or just do an fpm test so I think that works for me. I wonder if the default for bench|benches|benchmark and example|examples should be no auto build but that would be easier to decide with a working prototype.

I know I have a bias here and not sure how common the need is for everyone but my aspiration when building a library|module for public consumption is that each routine have a manpage with a working demo program that I automatically extract and build and run so it is testable. That can mean having dozens of small example programs that I do not want included in an install (I say aspiration because I do not always get around to that, but really thing it is a good practice!). So speaking personally this would be great.

[urbanjost]

PS: I use scale/ but I think benchmark/ is better.

[awvwgk]

I decided to just go ahead and create a PR to update both Fortran and Haskell fpm with an example program type. Since we are using singular nouns for test and executable I used this for example as well. Let me know what you think.

[milancurcic]

Personally I prefer "tests" and "examples" (plural) as it encourages making multiples of those, and most packages would benefit from multiple tests and examples. For "app" I'm okay with singular because application packages are more likely to be singular (I think?).

So I suggest changing "test" to "tests" sooner rather than later.

But this is minor preference--60/40 kind of thing. :)

[awvwgk]

I was more thinking about being compatible with the table names here, changing those is harder, not impossible, TOML-Fortran can easily migrate such a change in a backwards compatible way. For the default directory names, we can discuss changing those in another PR, for now I would like to be consistent with the existing implementation (one feature at a time).