mirror of
https://github.com/rust-lang/cargo
synced 2024-08-28 11:50:23 +00:00
Auto merge of #11001 - Muscraft:fix-unstable-docs, r=weihanglo
remove missed reference to workspace inheritance in unstable.md Currently on the nightly docs, workspace inheritance is [under the stable table](https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#workspace-inheritance-1) and the [unstable table](https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#workspace-inheritance). It looks like I forgot to remove it from the unstable table when working on stabilization. I am not sure if it is worth a beta backport but I will happily open a PR for it if needed.
This commit is contained in:
bors
commit
3b4df5a54a
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in a new issue