Feature examples force explicit listing of all [example]'s

[Xion]

Suppose I have a collection of multiple examples/ in the form of simple *.rs files.

$ ls examples
foo.rs bar.rs baz.rs thud.rs qux.rs

I can expand it & add more example binaries by simply creating a new file inside the examples/ directory:

$ echo "fn main() { println!(\"Hello world\"); }" >./examples/hello.rs
$ cargo run --example hello
Hello world

However, as soon as I want to write an example that requires one of the crate's [features], I have to declare it in Cargo.toml:

[features]
magic = []

[[example]]
name = "do_magic"
required-features = ["magic"]

Unfortunately, this has a nasty side effect: it is now mandatory to explicitly declare all examples in Cargo.toml, whether they require features or not. Otherwise, cargo run --example will not be able to locate the relevant Rust source file, and presumably cargo test will skip over building it, silently.

(I've encountered this issue in my project here).

Is there a reason why [[example]] sections work this way? Wouldn't it be more intuitive if the all examples/*.rs files were interpreted as standalone examples by default, whilst also allowing for an individual [[example]] section to override the properties of a particular example without affecting the auto-detected ones?

[lukaslueg]

Actually, this is true for all targets. Changing this would cause massive breakage for all crates that have examples built from more than one source file, where shared files reside beside examples in /examples.

[matklad]

Yeah, this behavior defenitelly feels weird to me... On the other hand, we defefenetelly can’t just change it (targets.rs includes all sorts of weird backward compatibility stuff for a reason), and we need to provide some way to opt out of automatic behavior....

I wonder if we could potentially change the way we infer targets in the new epoch?

[Xion]

Changing this would cause massive breakage for all crates that have examples built from more than one source file, where shared files reside beside examples in /examples.

I see. I didn't know such sharing was possible. When I needed to share code between different integration tests/, for instance (which AFAIK have the same crate-per-file mechanics as examples/) I used a tests/common subdirectory instead. Otherwise, a tests/shared.rs file would itself be interpreted as another test, which I expect would also happen for examples?

However, if changing the default behavior is not feasible, perhaps we could have an opt-in mechanic where you declare that aside from these specific [[example]]s, you want every *.rs file be picked up automatically by Cargo:

[[example]]
name = "do_magic"
required-features = ["magic"]

[[example]]
name = "*"  # match every remaining examples/*.rs file

This could probably be extended to [[test]]s, [[benchmark]]s, and [[bin]]s.

[matklad]

Closing in favor of #5330!