Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

RFC: Cargo feature visibility (private/public) #3487

Open
wants to merge 6 commits into
base: master
Choose a base branch
from
Open

RFC: Cargo feature visibility (private/public) #3487

Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
8a883f9
Add initial feature-visibility RFC split from feature-metadata
tgross35 Sep 9, 2023
04ee34d
Update RFC number
tgross35 Sep 9, 2023
7247b2c
Misc cleanup
epage Sep 10, 2023
50fba0d
Add motivation and one alternative. Remove unused items, fix typos
tgross35 Sep 15, 2023
187afcf
Clarify index changes, add cfg diagnostic drawback
tgross35 Sep 15, 2023
778bdd7
Update text/3487-feature-visibility.md
tgross35 Sep 15, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Clarify index changes, add cfg diagnostic drawback
  • Loading branch information
@tgross35
tgross35 committed Sep 15, 2023
commit 187afcf4f1c36ab8202174c1e6fe740c23bb2c88
20 changes: 9 additions & 11 deletions text/3487-feature-visibility.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,11 +25,11 @@ be available to downstream users. Examples include:
- Debugging, benchmarking or test-related features that expose unstable internal
API
- Intermediate features that are enabled by user-facing features but not meant
to be used on their own
to be used on their own (e.g. a feature enabling dependency features)

A way to hide these features from user-facing configuration will make options
easier to understand and lowers the chance of library users accidentally using
unstable internal PAI.
unstable internal API.

# Guide-level explanation

Expand Down Expand Up @@ -92,20 +92,16 @@ Attempting to use a private feature in any of the forbidden cases should result
in an error. Exact details of how features work will likely be refined during
implementation and experimentation.

Two sample use cases for `public = false` include:

- `docs.rs` having a way to know which features should be hidden
- Features that are included in feature chains (feature `a` enables feature `b`)
but not meant for public consumption could be marked not public

This feature requires adjustments to the index for full support. This RFC
proposes that it would be acceptable for the first implementation to simply
strip private features from the manifest; this means that there will be no way
to `cfg` based on these features.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not clear what cfg means here. I assumed it is the cfg attribute and the cfg macro. Could you expand and link to their doc respectively?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I kind of forgot the exact context here, this comes from Ed's comment at #3416 (comment) and the two following comments. Also #3416 (comment).

Do you have any ideas for how to improve the wording?

Thank you for taking a look by the way

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we strip the private features then when cargo does a build, it won't tell rustc about private features and if you do #[cfg(feature = "private-foo")] then it will never evaluate to true


Full support does not need to happen immediately, since it will require this
information be present in the index. [Index changes] describes how this can take
place.
information be present in the index. The [`feature-deprecation`] RFC describes
a way to add attributes to features in a forward-compatible way under a
`features3` key, which would be suitible for any additional information needed
here.

# Drawbacks

Expand All @@ -114,7 +110,8 @@ place.
- Added complexity to Cargo. Parsing is trivial, but exact implementation
details do add test surface area
- Added Cargo arguments if escape hatches for `public` are created
- `public` uses may not be common enough to be worth including
- This adds confusion to the `cfg` diagnostics introduced in
<https://github.com/rust-lang/rust/pull/109005>

# Rationale and alternatives

Expand Down Expand Up @@ -165,3 +162,4 @@ place.
[`rustdoc-cargo-configuration`]: https://github.com/rust-lang/rfcs/pull/3421
[`tokio`]: https://docs.rs/crate/tokio/latest/features
[visibility attribute]: https://ant.apache.org/ivy/history/latest-milestone/ivyfile/conf.html
[`feature-deprecation`]: https://github.com/rust-lang/rfcs/pull/3486