Make explicit opt-out of target discovery neccessary for Rust 2018

[matklad]

Currently, Cargo automatically discovers tests, examples and binaries form the files on the file system. One can also add an explicit [[example]] section to Cargo.toml, to add non-discoverable examples, or to tweak an existing example (for example, by specifying required features).

However, adding explicit [[target]] disables automatic discovery for other targets of similar type, and this behavior is highly surprising.

Current Proposal

New keys will be available under the [package] section of Cargo.toml:

[package]
# ... 

autobins = true
autoexamples = true
autotests = true
autobenches = true

The value of each of these keys indicates whether or not Cargo's automatic inference logic is in effect for discovering targets. Turning these keys to false will completely disable inference and Cargo will not attempt to find more targets. For example setting autobins = false will disable Cargo probing src/bin looking for binaries.

If these keys are turned to true then Cargo will probe the standard set of directories for targets. Any explicitly named targets in the manifest will be merged with the automatically found targets. For example if autotests = true is enabled and you've got tests/foo.rs and tests/bar.rs, you could disable the test harness of tests/foo.rs with:

[[test]]
name = "foo"
harness = false

and you'll still be able to use cargo test --test bar as Cargo will automatically find the tests/bar.rs test.

In the 2015 edition (today in Cargo) these keys are set with the following rules:

• If an explicit target is specified, the key is set to false. For example writing [[bin]] will set autobins = false automatically.
• If no explicit targets are specified, the key is set to true.

In the 2018 edition these keys will be unconditionally set to true by default.

Impact on Users Today

Unconditionally turning these keys to true is a breaking change as it can cause files that weren't previously compiled as a test, for example, to get compiled as a test. As a result projects will need to reorganize their files or otherwise set autotests = true, for example.

If you receive a command-line warning though and don't know what to do with that, please leave a comment here!

Original Proposal

We would like to change this behavior eventually and for that in Rust 2018 we should:

• add a flag autodiscover for each target type, with values true and false (precise flag name and syntax are subject to bike shedding).
• in Rust 2018, warn if autodiscover is not specified, at least a single [[target]] is listed, and some other target would be discovered if autodiscover was set to true.
• in the edition after 2018, flip autodiscover default to true.

The relevant code is here: https://github.com/rust-lang/cargo/blob/d8b20310217e5e2bc515c13111ab9a7789709e42/src/cargo/util/toml/targets.rs. Note that the logic there is pretty subtle, because we already carry a significant backwards compatibility baggage :(

It might be a good idea to flip some of those warnings to errors in 2018 as well!

[dwijnand]

coming back to this, from @alexcrichton's comment in my #5335 proposal:

I'm not sure that autodiscovery is in the right location though as it's sort of a project-level distinction rather than a per-target distinction. Perhaps we could have keys like auto-examples = false inside the [package] section?

As we discussed on the other PR as well I think we'll want to start issuing warnings in the 2015 epoch if we'd like to message this out as part of the 2018 release

(the other PR is #5333)

is the desired behaviour, under the condition that you specified a target, like [[example]], for non-discoverability or configuration purposes, that:

• in Rust 2015 a warning is issued that discoverable targets are not being included, but will be in Rust 2018
• in Rust 2018 discoverable target are always included

does that sound right?

[alexcrichton]

@dwijnand I believe so yeah! We'll still want some way to say "I've exhaustively listed all targets here, please do not continue to infer", but other than that your description sounds accurate.

[dwijnand]

part of the reason for my brainstorming is I was wondering if we could avoid the repetition of a key for each target in [package] by having something like no-auto = ["examples"]. But then I couldn't tell if it was more important to explicitly opt-out or opt-in of auto-discovery, so I'll just go with your initial idea and take it from there.

[alexcrichton]

Oh I'd be fine as well with something like no-auto = ["examples"]!

[dwijnand]

so that would work well for your "I've exhaustively listed all targets here, please do not continue to infer".

but I wonder: what do Rust 2015 users do to silence the warning? if they don't want to infer they too can add their target no-auto. but what if they want all targets included? should the solution there be defining no-auto = []? seems a bit subtle.

[alexcrichton]

@dwijnand oh for 2015 users I think it's the same as 2018, you'd specify no-auto = [...]

In general we can't really do much for the 2018 edition that we couldn't already do through slow deprecation, so it's mostly just serving as a good banner time to get things done by and send out messaging.

[elichai]

If you receive a command-line warning though and don't know what to do with that, please leave a comment here!

I'm getting this warning. i'm trying to enable a feature in the crate for one of my examples. (currently just added autoexamples = false)