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

Jump to bottom

beta backport: remove missed reference to workspace inheritance in unstable.md #11002

Merged
merged 1 commit into from
Aug 17, 2022
Merged

beta backport: remove missed reference to workspace inheritance in unstable.md #11002

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
182 changes: 0 additions & 182 deletions src/doc/src/reference/unstable.md
View file
Open in desktop
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