Skip to content

Commit

Permalink
docs(ref): Note MSRV for features in the docs
Browse files Browse the repository at this point in the history
I mostly focused on manifests and build scripts as those seemed the
highest priority.
I also went back only so far, assuming these would be the highest value
items.
  • Loading branch information
epage committed Jul 9, 2024
1 parent e98f702 commit 8d81db5
Show file tree
Hide file tree
Showing 5 changed files with 24 additions and 9 deletions.
17 changes: 8 additions & 9 deletions src/doc/src/reference/build-scripts.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,13 +77,6 @@ Build scripts communicate with Cargo by printing to stdout. Cargo will
interpret each line that starts with `cargo::` as an instruction that will
influence compilation of the package. All other lines are ignored.

> **Note:** The old invocation prefix `cargo:` (one colon only) is deprecated
> and won't get any new features. To migrate, use two-colons prefix `cargo::`,
> which was added in Rust 1.77. If you were using `cargo:KEY=VALUE` for
> arbitrary links manifest key-value pairs, it is encouraged to switch to
> `cargo::metadata=KEY=VALUE`. Stick to `cargo:` only if the support of Rust
> version older than 1.77 is required.
> The order of `cargo::` instructions printed by the build script *may*
> affect the order of arguments that `cargo` passes to `rustc`. In turn, the
> order of arguments passed to `rustc` may affect the order of arguments passed
Expand Down Expand Up @@ -140,6 +133,9 @@ one detailed below.
* [`cargo::metadata=KEY=VALUE`](#the-links-manifest-key) --- Metadata, used by `links`
scripts.

> **MSRV:** 1.77 is required for `cargo::KEY=VALUE` syntax.
> To support older versions, use the `cargo:KEY=VALUE` syntax.
### `cargo::rustc-link-arg=FLAG` {#rustc-link-arg}

The `rustc-link-arg` instruction tells Cargo to pass the [`-C link-arg=FLAG`
Expand Down Expand Up @@ -264,8 +260,6 @@ the _reachable_ cfg expressions with the [`unexpected_cfgs`][unexpected-cfgs] li
The syntax of `CHECK_CFG` mirrors the `rustc` [`--check-cfg` flag][option-check-cfg], see
[Checking conditional configurations][checking-conditional-configurations] for more details.

> Note: `cargo:rustc-check-cfg` (single-colon) can be used if your MSRV is below Rust 1.77
The instruction can be used like this:

```rust,no_run
Expand All @@ -286,6 +280,8 @@ avoid typos, missing check-cfg, stale cfgs...
See also the
[conditional compilation][conditional-compilation-example] example.

> **MSRV:** Respected as of 1.80
[checking-conditional-configurations]: ../../rustc/check-cfg.html
[option-check-cfg]: ../../rustc/command-line-arguments.md#option-check-cfg
[conditional-compilation-example]: build-script-examples.md#conditional-compilation
Expand Down Expand Up @@ -430,6 +426,9 @@ used.
Note that metadata is only passed to immediate dependents, not transitive
dependents.

> **MSRV:** 1.77 is required for `cargo::metadata=KEY=VALUE`.
> To support older versions, use `cargo:KEY=VAUE` (unsupported directives are assumed to be metadata keys).
[using-another-sys]: build-script-examples.md#using-another-sys-crate

## `*-sys` Packages
Expand Down
2 changes: 2 additions & 0 deletions src/doc/src/reference/external-tools.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,8 @@ details.
If you are using Rust, the [cargo_metadata] crate can be used to parse these
messages.

> **MSRV:** 1.77 is required for `package_id` to be a Package ID Specification. Before that, it was opaque.
[build command documentation]: ../commands/cargo-build.md
[cargo_metadata]: https://crates.io/crates/cargo_metadata
[Package ID Specifications]: ./pkgid-spec.md
Expand Down
6 changes: 6 additions & 0 deletions src/doc/src/reference/manifest.md
Original file line number Diff line number Diff line change
Expand Up @@ -111,6 +111,8 @@ breaking change.

This field is optional and defaults to `0.0.0`. The field is required for publishing packages.

> **MSRV:** Before 1.75, this field was required
[Resolver]: resolver.md
[SemVer compatibility]: semver.md

Expand Down Expand Up @@ -189,6 +191,8 @@ To find the minimum `rust-version` compatible with your project, you can use thi

When used on packages that get published, we recommend [verifying the `rust-version`](../guide/continuous-integration.md#verifying-rust-version).

> **MSRV:** Respected as of 1.56
### The `description` field

The description is a short blurb about the package. [crates.io] will display
Expand Down Expand Up @@ -589,6 +593,8 @@ Cargo only applies these to the current package and not to dependencies.
As for dependents, Cargo suppresses lints from non-path dependencies with features like
[`--cap-lints`](../../rustc/lints/levels.html#capping-lints).

> **MSRV:** Respected as of 1.74
## The `[badges]` section

The `[badges]` section is for specifying status badges that can be displayed
Expand Down
2 changes: 2 additions & 0 deletions src/doc/src/reference/profiles.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,8 @@ For more information on what each option does see `rustc`'s docs on [debuginfo].
You may wish to also configure the [`split-debuginfo`](#split-debuginfo) option
depending on your needs as well.

> **MSRV:** 1.71 is required for `none`, `limited`, `full`, `line-directives-only`, and `line-tables-only`
[`-C debuginfo` flag]: ../../rustc/codegen-options/index.html#debuginfo
[debuginfo]: ../../rustc/codegen-options/index.html#debuginfo
[profiling]: https://reviews.llvm.org/D46061
Expand Down
6 changes: 6 additions & 0 deletions src/doc/src/reference/workspaces.md
Original file line number Diff line number Diff line change
Expand Up @@ -191,6 +191,8 @@ description.workspace = true
documentation.workspace = true
```

> **MSRV:** Requires 1.74+
## The `dependencies` table

The `workspace.dependencies` table is where you define dependencies to be
Expand Down Expand Up @@ -230,6 +232,8 @@ cc.workspace = true
rand.workspace = true
```

> **MSRV:** Requires 1.74+
## The `lints` table

The `workspace.lints` table is where you define lint configuration to be inherited by members of a workspace.
Expand Down Expand Up @@ -257,6 +261,8 @@ version = "0.1.0"
workspace = true
```

> **MSRV:** Respected as of 1.74
## The `metadata` table

The `workspace.metadata` table is ignored by Cargo and will not be warned
Expand Down

0 comments on commit 8d81db5

Please sign in to comment.