Listing of Cargo features

tools and infrastructure cargo
1

Cargo creates an implicit Cargo feature for every optional dependency. However, crate authors often specify explicit features, and don't mean to support the implicit features. Tools like cargo add and docs.rs display lists of features according to Cargo's logic, but this may not match authors' intentions.

For example a crate with:

[dependencies]
turboencabulator_rs = { optional = true }
rust_waneshaft = { optional = true }

[features]
encabulate = ["turboencabulator_rs", "rust_waneshaft"]

is displayed as having three features: "turboencabulator_rs", "rust_waneshaft", and "encabulate". However, the code is most likely only checking for #[cfg(feature = "encabulate")], and completely ignores existence of the two implicitly created Cargo features.

Here's my proposal:

If an optional dependency is mentioned anywhere in [features], its implicit Cargo feature should be hidden from lists of crate's features. For backwards-compatibility, these features still have to exist.

2

Since we have dep:<pkgname> to disable the creation of the implicit feature as of 1.60, I feel the bar is higher for us to create a convention that fills a similar role.

Instead, I feel we should continue to raise awareness of the implicit feature so people ask questions and are more likely to discover the dep:<pkgname> syntax that was introduced after they started writing features.

7 Likes
3

There are reasons people would want to hide explicit features too. IIRC there is a crate that supports “doc-comments” on features now (@epage I have a small feeling you may be involved with it?). It would be good to also support some kind of metadata or convention to allow hiding explicit features (leading _?), and get support for that and the comments into places like docs.rs.

4

Yes, having the equivalent of #[doc(hidden)] for features and having it respected by cargo add, docs.rs, etc would be useful.

I believe you are referring to document_features. iirc this will only list features that are explicitly documented, hiding the rest. This works well when you are explicitly using the crate but might not be great to apply it universally. As we iterate on improving the visibility of features, we'll want to keep in mind the desire to hide features so we don't lose the feature as we adjust the workflow.

5

_ seems to be already used for internal features (e.g. 1, 2).

I've noticed that docs.rs hides features starting with __! For example: konst 0.2.13 - Docs.rs has a __test feature not shown here.

6

So it does

I forgot we added that. Glancing at it again I realise we don’t properly support dep:, we will still list the optional dependency as being available as a feature even if it has been disabled. Fixing that might need more info from cargo-metadata, I’ll try to take a better look and open an issue later (along with one about supporting the document-features syntax).

1 Like
7

I've created an issue for cargo add to reflect docs.rs's behavior.

1 Like