Skip to content

Commit

Permalink
Auto merge of #11002 - Muscraft:fix-unstable-docs-1.64.0, r=weihanglo
Browse files Browse the repository at this point in the history
beta backport: remove missed reference to workspace inheritance in unstable.md

This is a beta backport of #11001

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 think I did this right. If I didn't please let me know!
  • Loading branch information
bors committed Aug 17, 2022
2 parents ded0899 + c83d734 commit 4bcb3c6
Showing 1 changed file with 0 additions and 182 deletions.
182 changes: 0 additions & 182 deletions src/doc/src/reference/unstable.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 4bcb3c6

Please sign in to comment.