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
Add motivation and one alternative. Remove unused items, fix typos
  • Loading branch information
@tgross35
tgross35 committed Sep 15, 2023
commit 50fba0d19b592cdcc3c8bd76660ba82352518b2e
29 changes: 18 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 @@ -17,10 +17,19 @@ Please see the parent meta RFC for background information: [`feature-metadata`].

[motivation]: #motivation

WIP
Cargo feature gates are one of the main means to support optional build
tgross35 marked this conversation as resolved.
Show resolved Hide resolved
configuration in Rust crates. Often these are for configuration options that a
library user may want, but another common use case is hiding API that shouldn't
be available to downstream users. Examples include:

No way to hide unstable API such as testing-only features or internally enabled
features.
- 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

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.

# Guide-level explanation

Expand Down Expand Up @@ -91,7 +100,7 @@ Two sample use cases for `public = false` include:

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 meanss that there will be no way
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
Expand All @@ -111,7 +120,10 @@ place.

[rationale-and-alternatives]: #rationale-and-alternatives

TODO
- Currently, `docs.rs` will hide features from its autogenerated feature list
if they start with a leading underscore. This convention would work here, but
it would not be consistent with the Rust language (leading underscores indicate
unused variables, lang items are used to indicate visibility)

# Prior art

Expand All @@ -130,21 +142,16 @@ TODO
- Are the semantics of `public` proposed in this RFC suitable? Should private
features be usable in examples or integration tests without a `--features`
argument?
- Should there be a simple `--allow-private-features` flag that allows using all
features, such as for crater runs? This can be decided during implementation.
- Does `public` need to be in the index?

# Future possibilities

[future-possibilities]: #future-possibilities

- A `stable` field can be set false to indicate API-unstable or nightly-only
features (somethign such as `stable = 3.2` could be used to indicate when a
features (something such as `stable = 3.2` could be used to indicate when a
feature was stabilized). See also:
<https://github.com/rust-lang/cargo/issues/10882>
- A `rust-version` field that could indicate e.g. `rust-version = "nightly"` or
`rust-version = "1.65"` to specify a MSRV for that feature. See:
<https://github.com/rust-lang/rfcs/pull/3416#discussion_r1174478461>
- The `public` option could be used to allow optional dev dependencies. See:
<https://github.com/rust-lang/cargo/issues/1596>

Expand Down