diff --git a/src/doc/src/reference/unstable.md b/src/doc/src/reference/unstable.md index 6c329b6ec68..a04c51fdc76 100644 --- a/src/doc/src/reference/unstable.md +++ b/src/doc/src/reference/unstable.md @@ -1154,188 +1154,6 @@ with a warning. If you want to integrate with Cargo features, use `-Zcheck-cfg=features` instead of trying to do it manually with this option. -### workspace-inheritance - -* RFC: [#2906](https://github.com/rust-lang/rfcs/blob/master/text/2906-cargo-workspace-deduplicate.md) -* Tracking Issue: [#8415](https://github.com/rust-lang/cargo/issues/8415) -* [Status](https://github.com/rust-lang/cargo/issues/8415#issuecomment-1112618913) -* [Example Port](https://github.com/clap-rs/clap/pull/3719) - -### Testing notes - -Target audience for testing -* Maintainer who has a workspace -* *(optional)* Project depends on nightly toolchain - -In preparing to stabilize, we are wanting to better understand -* If there were any pain points in porting your project -* Any errors or bugs that you found in testing -* Performance concerns -* Gaps in documentation -* Thoughts on how you feel this feature will work in practice - -Please provide feedback on the [tracking issue](https://github.com/rust-lang/cargo/issues/8415) -or create an issue for any bugs encountered. - -To get started -1. Have a (recent) nightly version installed -2. Place `cargo-features = ["workspace-inheritance"]` at the top of any `Cargo.toml` you -plan to use this feature in -3. Create a `[workspace.package]` and `[workspace.dependencies]` in your workspace `Cargo.toml` -4. Move any package keys or dependencies you feel should be shared between crates to their -respective workspace table -5. Change any keys you want to inherit to `{key}.workspace = true` in the member `Cargo.toml` -6. run `cargo +nightly check` - -An example port has been made [in this PR](https://github.com/clap-rs/clap/pull/3719) as -a "real-life" guide. - -### The `workspace.package` table - -*Stabilization*: This would be in [`workspaces.md`][workspaces], under -[The `workspace.metadata` table][workspace-metadata-table] - -The `workspace.package` table is where you define keys that can be -inherited by members of a workspace. These keys can be inherited by -defining them in the member package with `{key}.workspace = true`. - -Keys that are supported: - -| | | -|----------------|-----------------| -| `authors` | `categories` | -| `description` | `documentation` | -| `edition` | `exclude` | -| `homepage` | `include` | -| `keywords` | `license` | -| `license-file` | `publish` | -| `readme` | `repository` | -| `rust-version` | `version` | - -- `license-file` and `readme` are relative to the workspace root -- `include` and `exclude` are relative to your package root - -Example: -```toml -# [PROJECT_DIR]/Cargo.toml -[workspace] -members = ["bar"] - -[workspace.package] -version = "1.2.3" -authors = ["Nice Folks"] -description = "..." -documentation = "https://example.github.io/example" -``` - -```toml -# [PROJECT_DIR]/bar/Cargo.toml -cargo-features = ["workspace-inheritance"] - -[package] -name = "bar" -version.workspace = true -authors.workspace = true -description.workspace = true -documentation.workspace = true -``` - - -### The `workspace.dependencies` table - -The `workspace.dependencies` table is where you define dependencies to be -inherited by members of a workspace. - -Specifying a workspace dependency is similar to [package dependencies][specifying-dependencies] except: -- Dependencies from this table cannot be declared as `optional` -- [`features`][features] declared in this table are additive with the `features` from `[dependencies]` - -You can then [inherit the workspace dependency as a package dependency][inheriting-a-dependency-from-a-workspace] - -Example: -```toml -# [PROJECT_DIR]/Cargo.toml -[workspace] -members = ["bar"] - -[workspace.dependencies] -dep = { version = "0.1", features = ["fancy"] } -dep-build = "0.8" -dep-dev = "0.5.2" -``` - -```toml -# [PROJECT_DIR]/bar/Cargo.toml -cargo-features = ["workspace-inheritance"] - -[project] -name = "bar" -version = "0.2.0" - -[dependencies] -dep = { workspace = true, features = ["dancy"] } - -[build-dependencies] -dep-build.workspace = true - -[dev-dependencies] -dep-dev.workspace = true -``` - -[inheriting-a-dependency-from-a-workspace]: #inheriting-a-dependency-from-a-workspace -[workspace-metadata-table]: workspaces.md#the-workspacemetadata-table -[workspaces]: workspaces.md - - -### Inheriting a dependency from a workspace - -*Stabilization*: This would be in [`specifying-dependencies.md`][specifying-dependencies], -under [Renaming dependencies in Cargo.toml][renaming-dependencies-in-cargotoml] - -Dependencies can be inherited from a workspace by specifying the -dependency in the workspace's [`[workspace.dependencies]`][workspace.dependencies] table. -After that add it to the `[dependencies]` table with `dep.workspace = true`. - -The `workspace` key can be defined with: -- [`optional`][optional]: Note that the`[workspace.dependencies]` table is not allowed to specify `optional`. -- [`features`][features]: These are additive with the features declared in the `[workspace.dependencies]` - -The `workspace` key cannot be defined with: - -| | | -|------------------|--------------------| -| `branch` | `default-features` | -| `git` | `package` | -| `path` | `registry` | -| `registry-index` | `rev` | -| `tag` | `version` | - - -Dependencies in the `[dependencies]`, `[dev-dependencies]`, `[build-dependencies]`, and -`[target."...".dependencies]` sections support the ability to reference the -`[workspace.dependencies]` definition of dependencies. - -Example: -```toml -[dependencies] -dep.workspace = true -dep2 = { workspace = true, features = ["fancy"] } -dep3 = { workspace = true, optional = true } -dep4 = { workspace = true, optional = true, features = ["fancy"] } - -[build-dependencies] -dep-build.workspace = true - -[dev-dependencies] -dep-dev.workspace = true -``` - -[features]: features.md -[optional]: features.md#optional-dependencies -[workspace.dependencies]: #the-workspacedependencies-table -[specifying-dependencies]: specifying-dependencies.md -[renaming-dependencies-in-cargotoml]: specifying-dependencies.md#renaming-dependencies-in-cargotoml - ## Stabilized and removed features ### Compile progress