Cargo: Add dependency of examples towards features

[tomaka]

Cargo should allow writing:

[package]
# ...

[features]
a = []

[example]
src = "examples/example-that-uses-a.rs"
features = ["a"]

example-that-uses-a would only be compiled if you call cargo test --features "a".
More formally, examples should have the possibiliy to declare a list of features that must be enabled for this example to be compiled.

The motivation is to avoid having to write ugly code like this one.
Newcomers often copy-paste a library's examples to get started, and don't necessarly understand what the #![cfg(feature)] thing is and that they shouldn't copy it.

[tsurai]

Considering that this issue is from may I wonder if this has been solved in some other way by now. Because I stumbled into a similar problem recently and would like to try to implement this feature if it still is desired.

[alexcrichton]

@tsurai nah unfortunately this hasn't been implemented just yet, but feel free to jump on it!

[tsurai]

@alexcrichton I've written a simple implementation allowing the user to declare feature dependencies for examples like this:

[package]
# ...

[features]
a = []
b = []

[examples]
ex_1 = ["a", "b"]

ex_1 is the name of example and relates to examples/ex_1.rs.

This is my first time working on cargo and I'm not sure if my code is at the right place or has flaws in its logic. It would be very nice if you could look over it and give me some critique. I don't want to open a pull request with code that has errors or a too low quality for cargo.

[alexcrichton]

Nice work @tsurai! I know it's probably not easy jumping into Cargo :)

I think though that we may want to instead have a design like:

• A [[example]] section is allowed to have a features key which indicates what features it depends on
• An example isn't built during cargo test unless those features are otherwise activated

That should avoid having an extra manifest key and put the dependency next to the example definition if there is one

[tsurai]

Thanks for your guidance @alexcrichton!

I didn't even know that a [[example]] already exists (doesn't seem to be documented on crates.io?)

Before I'm running off in the wrong direction again...
you want me to add a features field to the TomlExampleTarget type? Basically write a new but slightly altered version of TomlTarget with an additional field to hold the feature dependencies.

The filter logic should not need much changing as it prevents examples from being build if their dependencies are not met.

Is that what you mean?

[alexcrichton]

Ah it's somewhat documented but not explicitly mentioned.

I think what you mentioned does align with what I was thinking, but it's starting to feel a little odd to me in terms of making [[example]] special over other kinds of targets. It's likely that all targets but [lib] want the ability to only be conditionally included if a feature is activated (e.g. binaries, benchmarks, or tests may not otherwise be compiled).

[tsurai]

I made another prototype that works for all targets but [lib] as you suggested.
It's just the basic logic without any notifications but is this more like what you want @alexcrichton?

[alexcrichton]

Yeah that seems about right to me!

[rtbo]

Do you have any news on example.features?
Will cargo test be the only use case?
Is it possible also to use it to automatically add features for cargo run --example my_example

[alexcrichton]

@rtbo there's a PR to implement this but it seems to be going stale

[adamcrume]

What's the status of this? It seems to be still unavailable in Rust 1.10.

[alexcrichton]

@adamcrume there was a rebased version of the original PR, and it basically just needs a revival at this point I believe with some comments addressed (all on the PR itself)

[loggerhead]

Any news?

[Kixunil]

I'd appreciate if this was available. I'd also like to add feature-dependent examples directly in doc - is there any way to solve it?

[alexcrichton]

AFAIK no news since my previous comment

[cyplo]

It seems that the referenced PRs are closed/merged now, would that mean that this issue is no longer ? thanks !

[alexcrichton]

Indeed!

[Kixunil]

Is it implemented for examples in doc too? I can't figure out from code...

[brendanzab]

Seems it is the required-features field. Eg.

[[example]]
name = "stlc"
required-features = ["moniker-derive"]