diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 2310b53284c..6fd7b56f5a2 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -232,7 +232,7 @@ jobs: - name: Install mdbook run: | mkdir mdbook - curl -Lf https://github.com/rust-lang/mdBook/releases/download/v0.4.27/mdbook-v0.4.27-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook + curl -Lf https://github.com/rust-lang/mdBook/releases/download/v0.4.31/mdbook-v0.4.31-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook echo `pwd`/mdbook >> $GITHUB_PATH - run: cd src/doc && mdbook build --dest-dir ../../target/doc - name: Run linkchecker.sh diff --git a/src/doc/src/reference/build-scripts.md b/src/doc/src/reference/build-scripts.md index 68e8d404f1f..73cf441c7c9 100644 --- a/src/doc/src/reference/build-scripts.md +++ b/src/doc/src/reference/build-scripts.md @@ -34,7 +34,7 @@ The sections below describe how build scripts work, and the [examples chapter](build-script-examples.md) shows a variety of examples on how to write scripts. -> Note: The [`package.build` manifest key](manifest.md#package-build) can be +> Note: The [`package.build` manifest key](manifest.md#the-build-field) can be > used to change the name of the build script, or disable it entirely. ### Life Cycle of a Build Script @@ -132,8 +132,7 @@ one detailed below. scripts. - -#### `cargo:rustc-link-arg=FLAG` +#### `cargo:rustc-link-arg=FLAG` {#rustc-link-arg} The `rustc-link-arg` instruction tells Cargo to pass the [`-C link-arg=FLAG` option][link-arg] to the compiler, but only when building supported targets @@ -143,8 +142,7 @@ linker script. [link-arg]: ../../rustc/codegen-options/index.md#link-arg - -#### `cargo:rustc-link-arg-bin=BIN=FLAG` +#### `cargo:rustc-link-arg-bin=BIN=FLAG` {#rustc-link-arg-bin} The `rustc-link-arg-bin` instruction tells Cargo to pass the [`-C link-arg=FLAG` option][link-arg] to the compiler, but only when building @@ -152,8 +150,7 @@ the binary target with name `BIN`. Its usage is highly platform specific. It is to set a linker script or other linker options. - -#### `cargo:rustc-link-arg-bins=FLAG` +#### `cargo:rustc-link-arg-bins=FLAG` {#rustc-link-arg-bins} The `rustc-link-arg-bins` instruction tells Cargo to pass the [`-C link-arg=FLAG` option][link-arg] to the compiler, but only when building a @@ -161,8 +158,7 @@ binary target. Its usage is highly platform specific. It is useful to set a linker script or other linker options. - -#### `cargo:rustc-link-lib=LIB` +#### `cargo:rustc-link-lib=LIB` {#rustc-link-lib} The `rustc-link-lib` instruction tells Cargo to link the given library using the compiler's [`-l` flag][option-link]. This is typically used to link a @@ -187,30 +183,26 @@ The optional `KIND` may be one of `dylib`, `static`, or `framework`. See the [FFI]: ../../nomicon/ffi.md - -#### `cargo:rustc-link-arg-tests=FLAG` +#### `cargo:rustc-link-arg-tests=FLAG` {#rustc-link-arg-tests} The `rustc-link-arg-tests` instruction tells Cargo to pass the [`-C link-arg=FLAG` option][link-arg] to the compiler, but only when building a tests target. - -#### `cargo:rustc-link-arg-examples=FLAG` +#### `cargo:rustc-link-arg-examples=FLAG` {#rustc-link-arg-examples} The `rustc-link-arg-examples` instruction tells Cargo to pass the [`-C link-arg=FLAG` option][link-arg] to the compiler, but only when building an examples target. - -#### `cargo:rustc-link-arg-benches=FLAG` +#### `cargo:rustc-link-arg-benches=FLAG` {#rustc-link-arg-benches} The `rustc-link-arg-benches` instruction tells Cargo to pass the [`-C link-arg=FLAG` option][link-arg] to the compiler, but only when building a benchmark target. - -#### `cargo:rustc-link-search=[KIND=]PATH` +#### `cargo:rustc-link-search=[KIND=]PATH` {#rustc-link-search} The `rustc-link-search` instruction tells Cargo to pass the [`-L` flag][option-search] to the compiler to add a directory to the library search @@ -228,16 +220,14 @@ is fine). [option-search]: ../../rustc/command-line-arguments.md#option-l-search-path - -#### `cargo:rustc-flags=FLAGS` +#### `cargo:rustc-flags=FLAGS` {#rustc-flags} The `rustc-flags` instruction tells Cargo to pass the given space-separated flags to the compiler. This only allows the `-l` and `-L` flags, and is equivalent to using [`rustc-link-lib`](#rustc-link-lib) and [`rustc-link-search`](#rustc-link-search). - -#### `cargo:rustc-cfg=KEY[="VALUE"]` +#### `cargo:rustc-cfg=KEY[="VALUE"]` {#rustc-cfg} The `rustc-cfg` instruction tells Cargo to pass the given value to the [`--cfg` flag][option-cfg] to the compiler. This may be used for compile-time @@ -258,8 +248,7 @@ identifier, the value should be a string. [conditional compilation]: ../../reference/conditional-compilation.md [option-cfg]: ../../rustc/command-line-arguments.md#option-cfg - -#### `cargo:rustc-env=VAR=VALUE` +#### `cargo:rustc-env=VAR=VALUE` {#rustc-env} The `rustc-env` instruction tells Cargo to set the given environment variable when compiling the package. The value can be then retrieved by the [`env!` @@ -279,8 +268,7 @@ Cargo][env-cargo]. [env-macro]: ../../std/macro.env.html [env-cargo]: environment-variables.md#environment-variables-cargo-sets-for-crates - -#### `cargo:rustc-cdylib-link-arg=FLAG` +#### `cargo:rustc-cdylib-link-arg=FLAG` {#rustc-cdylib-link-arg} The `rustc-cdylib-link-arg` instruction tells Cargo to pass the [`-C link-arg=FLAG` option][link-arg] to the compiler, but only when building a @@ -288,8 +276,7 @@ link-arg=FLAG` option][link-arg] to the compiler, but only when building a to set the shared library version or the runtime-path. - -#### `cargo:warning=MESSAGE` +#### `cargo:warning=MESSAGE` {#cargo-warning} The `warning` instruction tells Cargo to display a warning after the build script has finished running. Warnings are only shown for `path` dependencies @@ -334,8 +321,7 @@ FAQ](../faq.md#why-is-cargo-rebuilding-my-code). [`exclude` and `include` fields]: manifest.md#the-exclude-and-include-fields - -#### `cargo:rerun-if-changed=PATH` +#### `cargo:rerun-if-changed=PATH` {#rerun-if-changed} The `rerun-if-changed` instruction tells Cargo to re-run the build script if the file at the given path has changed. Currently, Cargo only uses the @@ -354,8 +340,7 @@ automatically handles whether or not the script itself needs to be recompiled, and of course the script will be re-run after it has been recompiled. Otherwise, specifying `build.rs` is redundant and unnecessary. - -#### `cargo:rerun-if-env-changed=NAME` +#### `cargo:rerun-if-env-changed=NAME` {#rerun-if-env-changed} The `rerun-if-env-changed` instruction tells Cargo to re-run the build script if the value of an environment variable of the given name has changed. diff --git a/src/doc/src/reference/manifest.md b/src/doc/src/reference/manifest.md index 5a3d60ccc35..5f9d29ff6e3 100644 --- a/src/doc/src/reference/manifest.md +++ b/src/doc/src/reference/manifest.md @@ -53,7 +53,6 @@ Every manifest file consists of the following sections: * [`[profile]`](profiles.md) --- Compiler settings and optimizations. * [`[workspace]`](workspaces.md) --- The workspace definition. - ### The `[package]` section The first section in a `Cargo.toml` is `[package]`. @@ -112,7 +111,6 @@ breaking change. [Resolver]: resolver.md [SemVer compatibility]: semver.md - #### The `authors` field The optional `authors` field lists in an array the people or organizations that are considered @@ -135,7 +133,6 @@ user interface. > field cannot be changed or removed in already-published versions of a > package. - #### The `edition` field The `edition` key is an optional key that affects which [Rust Edition] your package @@ -198,7 +195,6 @@ description = "A short description of my package" > **Note**: [crates.io] requires the `description` to be set. - #### The `documentation` field The `documentation` field specifies a URL to a website hosting the crate's @@ -326,7 +322,6 @@ categories = ["command-line-utilities", "development-tools::cargo-plugins"] > match one of the strings available at , and > must match exactly. - #### The `workspace` field The `workspace` field can be used to configure the workspace that this package @@ -347,8 +342,6 @@ table defined. That is, a crate cannot both be a root crate in a workspace For more information, see the [workspaces chapter](workspaces.md). - - #### The `build` field The `build` field specifies a file in the package root which is a [build @@ -368,7 +361,6 @@ The default is `"build.rs"`, which loads the script from a file named specify a path to a different file or `build = false` to disable automatic detection of the build script. - #### The `links` field The `links` field specifies the name of a native library that is being linked @@ -386,7 +378,6 @@ on Linux) may specify: links = "git2" ``` - #### The `exclude` and `include` fields The `exclude` and `include` fields can be used to explicitly specify which @@ -476,7 +467,6 @@ if any of those files change. [gitignore]: https://git-scm.com/docs/gitignore - #### The `publish` field The `publish` field can be used to prevent a package from being published to a @@ -501,7 +491,6 @@ publish = ["some-registry-name"] If publish array contains a single registry, `cargo publish` command will use it when `--registry` flag is not specified. - #### The `metadata` table Cargo by default will warn about unused keys in `Cargo.toml` to assist in @@ -624,6 +613,17 @@ more detail. "#the-patch-section": "overriding-dependencies.html#the-patch-section", "#using-patch-with-multiple-versions": "overriding-dependencies.html#using-patch-with-multiple-versions", "#the-replace-section": "overriding-dependencies.html#the-replace-section", + "#package-metadata": "manifest.html#the-package-section", + "#the-authors-field-optional": "manifest.html#the-authors-field", + "#the-edition-field-optional": "manifest.html#the-edition-field", + "#the-documentation-field-optional": "manifest.html#the-documentation-field", + "#the-workspace--field-optional": "manifest.html#the-workspace-field", + "#package-build": "manifest.html#the-build-field", + "#the-build-field-optional": "manifest.html#the-build-field", + "#the-links-field-optional": "manifest.html#the-links-field", + "#the-exclude-and-include-fields-optional": "manifest.html#the-exclude-and-include-fields", + "#the-publish--field-optional": "manifest.html#the-publish-field", + "#the-metadata-table-optional": "manifest.html#the-metadata-table", }; var target = fragments[window.location.hash]; if (target) { diff --git a/src/doc/src/reference/semver.md b/src/doc/src/reference/semver.md index 5a53a655464..86353f6bbd3 100644 --- a/src/doc/src/reference/semver.md +++ b/src/doc/src/reference/semver.md @@ -112,8 +112,7 @@ after it has been modified, and an example usage of the code that could appear in another project. In a minor change, the example usage should successfully build with both the before and after versions. - -### Major: renaming/moving/removing any public items +### Major: renaming/moving/removing any public items {#item-remove} The absence of a publicly exposed [item][items] will cause any uses of that item to fail to compile. @@ -145,8 +144,7 @@ Mitigating strategies: * Mark renamed items as [deprecated], and use a [`pub use`] item to re-export to the old name. - -### Minor: adding new public items +### Minor: adding new public items {#item-new} Adding new, public [items] is a minor change. @@ -206,8 +204,7 @@ This is not considered a major change because conventionally glob imports are a known forwards-compatibility hazard. Glob imports of items from external crates should be avoided. - -### Major: adding a private struct field when all current fields are public +### Major: adding a private struct field when all current fields are public {#struct-add-private-field-when-public} When a private field is added to a struct that previously had all public fields, this will break any code that attempts to construct it with a [struct literal]. @@ -241,8 +238,7 @@ Mitigation strategies: a struct to prevent users from using struct literal syntax, and instead provide a constructor method and/or [Default] implementation. - -### Major: adding a public field when no private field exists +### Major: adding a public field when no private field exists {#struct-add-public-field-when-no-private} When a public field is added to a struct that has all public fields, this will break any code that attempts to construct it with a [struct literal]. @@ -276,8 +272,7 @@ Mitigation strategies: a struct to prevent users from using struct literal syntax, and instead provide a constructor method and/or [Default] implementation. - -### Minor: adding or removing private fields when at least one already exists +### Minor: adding or removing private fields when at least one already exists {#struct-private-fields-with-private} It is safe to add or remove private fields from a struct when the struct already has at least one private field. @@ -335,8 +330,7 @@ fn main() { } ``` - -### Minor: going from a tuple struct with all private fields (with at least one field) to a normal struct, or vice versa +### Minor: going from a tuple struct with all private fields (with at least one field) to a normal struct, or vice versa {#struct-tuple-normal-with-private} Changing a tuple struct to a normal struct (or vice-versa) is safe if all fields are private. @@ -367,8 +361,7 @@ fn main() { This is safe because existing code cannot use a [struct literal] to construct it, nor match its contents. - -### Major: adding new enum variants (without `non_exhaustive`) +### Major: adding new enum variants (without `non_exhaustive`) {#enum-variant-new} It is a breaking change to add a new enum variant if the enum does not use the [`#[non_exhaustive]`][non_exhaustive] attribute. @@ -404,8 +397,7 @@ Mitigation strategies: * When introducing the enum, mark it as [`#[non_exhaustive]`][non_exhaustive] to force users to use [wildcard patterns] to catch new variants. - -### Major: adding new fields to an enum variant +### Major: adding new fields to an enum variant {#enum-fields-new} It is a breaking change to add new fields to an enum variant because all fields are public, and constructors and matching will fail to compile. @@ -457,8 +449,7 @@ Mitigation strategies: } ``` - -### Major: adding a non-defaulted trait item +### Major: adding a non-defaulted trait item {#trait-new-item-no-default} It is a breaking change to add a non-defaulted item to a trait. This will break any implementors of the trait. @@ -490,8 +481,7 @@ Mitigation strategies: * When introducing the trait, use the [sealed trait] technique to prevent users outside of the crate from implementing the trait. - -### Major: any change to trait item signatures +### Major: any change to trait item signatures {#trait-item-signature} It is a breaking change to make any change to a trait item signature. This can break external implementors of the trait. @@ -530,8 +520,7 @@ Mitigation strategies: * When introducing the trait, use the [sealed trait] technique to prevent users outside of the crate from implementing the trait. - -### Possibly-breaking: adding a defaulted trait item +### Possibly-breaking: adding a defaulted trait item {#trait-new-default-item} It is usually safe to add a defaulted trait item. However, this can sometimes cause a compile error. For example, this can introduce an ambiguity if a @@ -581,8 +570,7 @@ Mitigation strategies: to require downstream users to add [disambiguation syntax] to select the correct function when updating the dependency. - -### Major: adding a trait item that makes the trait non-object safe +### Major: adding a trait item that makes the trait non-object safe {#trait-object-safety} It is a breaking change to add a trait item that changes the trait to not be [object safe]. @@ -616,8 +604,7 @@ fn main() { It is safe to do the converse (making a non-object safe trait into a safe one). - -### Major: adding a type parameter without a default +### Major: adding a type parameter without a default {#trait-new-parameter-no-default} It is a breaking change to add a type parameter without a default to a trait. @@ -643,8 +630,7 @@ impl Trait for Foo {} // Error: missing generics Mitigating strategies: * See [adding a defaulted trait type parameter](#trait-new-parameter-default). - -### Minor: adding a defaulted trait type parameter +### Minor: adding a defaulted trait type parameter {#trait-new-parameter-default} It is safe to add a type parameter to a trait as long as it has a default. External implementors will use the default without needing to specify the @@ -669,8 +655,7 @@ struct Foo; impl Trait for Foo {} ``` - -### Possibly-breaking change: adding any inherent items +### Possibly-breaking change: adding any inherent items {#impl-item-new} Usually adding inherent items to an implementation should be safe because inherent items take priority over trait items. However, in some cases the @@ -719,8 +704,7 @@ Mitigation strategies: to require downstream users to add [disambiguation syntax] to select the correct function when updating the dependency. - -### Major: tightening generic bounds +### Major: tightening generic bounds {#generic-bounds-tighten} It is a breaking change to tighten generic bounds on a type since this can break users expecting the looser bounds. @@ -749,8 +733,7 @@ fn main() { } ``` - -### Minor: loosening generic bounds +### Minor: loosening generic bounds {#generic-bounds-loosen} It is safe to loosen the generic bounds on a type, as it only expands what is allowed. @@ -779,8 +762,7 @@ fn main() { } ``` - -### Minor: adding defaulted type parameters +### Minor: adding defaulted type parameters {#generic-new-default} It is safe to add a type parameter to a type as long as it has a default. All existing references will use the default without needing to specify the @@ -810,8 +792,7 @@ fn main() { } ``` - -### Minor: generalizing a type to use generics (with identical types) +### Minor: generalizing a type to use generics (with identical types) {#generic-generalize-identical} A struct or enum field can change from a concrete type to a generic type parameter, provided that the change results in an identical type for all @@ -840,8 +821,7 @@ fn main() { because existing uses of `Foo` are shorthand for `Foo` which yields the identical field type. - -### Major: generalizing a type to use generics (with possibly different types) +### Major: generalizing a type to use generics (with possibly different types) {#generic-generalize-different} Changing a struct or enum field from a concrete type to a generic type parameter can break if the type can change. @@ -866,8 +846,7 @@ fn main() { } ``` - -### Minor: changing a generic type to a more generic type +### Minor: changing a generic type to a more generic type {#generic-more-generic} It is safe to change a generic type to a more generic one. For example, the following adds a generic parameter that defaults to the original type, which @@ -894,8 +873,7 @@ fn main() { } ``` - -### Major: adding/removing function parameters +### Major: adding/removing function parameters {#fn-change-arity} Changing the arity of a function is a breaking change. @@ -924,8 +902,7 @@ Mitigating strategies: with the builder pattern. This allows new fields to be added to the struct in the future. - -### Possibly-breaking: introducing a new function type parameter +### Possibly-breaking: introducing a new function type parameter {#fn-generic-new} Usually, adding a non-defaulted type parameter is safe, but in some cases it can be a breaking change: @@ -955,8 +932,7 @@ other ways) that this breakage is usually acceptable. One should take into account how likely it is that the function in question is being called with explicit type arguments. - -### Minor: generalizing a function to use generics (supporting original type) +### Minor: generalizing a function to use generics (supporting original type) {#fn-generalize-compatible} The type of a parameter to a function, or its return value, can be *generalized* to use generics, including by introducing a new type parameter, @@ -1053,8 +1029,7 @@ fn main() { } ``` - -### Major: generalizing a function to use generics with type mismatch +### Major: generalizing a function to use generics with type mismatch {#fn-generalize-mismatch} It is a breaking change to change a function parameter or return type if the generic type constrains or changes the types previously allowed. For example, @@ -1081,8 +1056,7 @@ fn main() { } ``` - -### Minor: making an `unsafe` function safe +### Minor: making an `unsafe` function safe {#fn-unsafe-safe} A previously `unsafe` function can be made safe without breaking code. @@ -1122,8 +1096,7 @@ Making a previously `unsafe` associated function or method on structs / enums safe is also a minor change, while the same is not true for associated function on traits (see [any change to trait item signatures](#trait-item-signature)). - -### Major: switching from `no_std` support to requiring `std` +### Major: switching from `no_std` support to requiring `std` {#attr-no-std-to-std} If your library specifically supports a [`no_std`] environment, it is a breaking change to make a new release that requires `std`. @@ -1158,8 +1131,7 @@ Mitigation strategies: optionally enables `std` support, and when the feature is off, the library can be used in a `no_std` environment. - -### Major: adding `non_exhaustive` to an existing enum, variant, or struct with no private fields +### Major: adding `non_exhaustive` to an existing enum, variant, or struct with no private fields {#attr-adding-non-exhaustive} Making items [`#[non_exhaustive]`][non_exhaustive] changes how they may be used outside the crate where they are defined: @@ -1243,8 +1215,7 @@ Mitigation strategies: ## Tooling and environment compatibility - -### Possibly-breaking: changing the minimum version of Rust required +### Possibly-breaking: changing the minimum version of Rust required {#env-new-rust} Introducing the use of new features in a new release of Rust can break projects that are using older versions of Rust. This also includes using new @@ -1271,8 +1242,7 @@ Mitigation strategies: mechanism for new features. These are currently unstable and only available in the nightly channel. - -### Possibly-breaking: changing the platform and environment requirements +### Possibly-breaking: changing the platform and environment requirements {#env-change-requirements} There is a very wide range of assumptions a library makes about the environment that it runs in, such as the host platform, operating system @@ -1292,8 +1262,7 @@ Mitigation strategies: * Document the platforms and environments you specifically support. * Test your code on a wide range of environments in CI. - -### Minor: introducing new lints +### Minor: introducing new lints {#new-lints} Some changes to a library may cause new lints to be triggered in users of that library. This should generally be considered a compatible change. @@ -1348,8 +1317,7 @@ Mitigating strategies: ### Cargo - -#### Minor: adding a new Cargo feature +#### Minor: adding a new Cargo feature {#cargo-feature-add} It is usually safe to add new [Cargo features]. If the feature introduces new changes that cause a breaking change, this can cause difficulties for projects @@ -1371,8 +1339,7 @@ consequences of enabling the feature. std = [] ``` - -#### Major: removing a Cargo feature +#### Major: removing a Cargo feature {#cargo-feature-remove} It is usually a breaking change to remove [Cargo features]. This will cause an error for any project that enabled the feature. @@ -1398,8 +1365,7 @@ Mitigation strategies: functionality. Document that the feature is deprecated, and remove it in a future major SemVer release. - -#### Major: removing a feature from a feature list if that changes functionality or public items +#### Major: removing a feature from a feature list if that changes functionality or public items {#cargo-feature-remove-another} If removing a feature from another feature, this can break existing users if they are expecting that functionality to be available through that feature. @@ -1420,8 +1386,7 @@ default = [] # This may cause packages to fail if they are expecting std to be std = [] ``` - -#### Possibly-breaking: removing an optional dependency +#### Possibly-breaking: removing an optional dependency {#cargo-remove-opt-dep} Removing an optional dependency can break a project using your library because another project may be enabling that dependency via [Cargo features]. @@ -1454,8 +1419,7 @@ Mitigation strategies: optional dependencies necessary to implement "networking". Then document the "networking" feature. - -#### Minor: changing dependency features +#### Minor: changing dependency features {#cargo-change-dep-feature} It is usually safe to change the features on a dependency, as long as the feature does not introduce a breaking change. @@ -1475,8 +1439,7 @@ rand = { version = "0.7.3", features = ["small_rng"] } rand = "0.7.3" ``` - -#### Minor: adding dependencies +#### Minor: adding dependencies {#cargo-dep-add} It is usually safe to add new dependencies, as long as the new dependency does not introduce new requirements that result in a breaking change. diff --git a/src/doc/src/reference/workspaces.md b/src/doc/src/reference/workspaces.md index 21f8f08f8ca..5104a18a3d8 100644 --- a/src/doc/src/reference/workspaces.md +++ b/src/doc/src/reference/workspaces.md @@ -56,7 +56,6 @@ version = "0.1.0" # the current version, obeying semver authors = ["Alice ", "Bob "] ``` - #### Virtual workspace Alternatively, a `Cargo.toml` file can be created with a `[workspace]` section @@ -253,3 +252,17 @@ if that makes sense for the tool in question. [specifying-dependencies]: specifying-dependencies.md [features]: features.md [inheriting-a-dependency-from-a-workspace]: specifying-dependencies.md#inheriting-a-dependency-from-a-workspace + +