From ff5954827af32025bd29d2b6d39d6c84480e74e1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ville=20Skytt=C3=A4?= Date: Sun, 9 Mar 2025 12:13:49 +0200 Subject: [PATCH] docs(reference): sort manifest package section keys per style guide https://doc.rust-lang.org/nightly/style-guide/cargo.html Sorting only, no content changes. --- src/doc/src/reference/manifest.md | 586 +++++++++++++++--------------- 1 file changed, 293 insertions(+), 293 deletions(-) diff --git a/src/doc/src/reference/manifest.md b/src/doc/src/reference/manifest.md index 3d0a6f1b1ba..b49d7d3255f 100644 --- a/src/doc/src/reference/manifest.md +++ b/src/doc/src/reference/manifest.md @@ -11,31 +11,31 @@ Every manifest file consists of the following sections: * [`name`](#the-name-field) --- The name of the package. * [`version`](#the-version-field) --- The version of the package. * [`authors`](#the-authors-field) --- The authors of the package. - * [`edition`](#the-edition-field) --- The Rust edition. - * [`rust-version`](rust-version.md) --- The minimal supported Rust version. - * [`description`](#the-description-field) --- A description of the package. + * [`autobenches`](cargo-targets.md#target-auto-discovery) --- Disables bench auto discovery. + * [`autobins`](cargo-targets.md#target-auto-discovery) --- Disables binary auto discovery. + * [`autoexamples`](cargo-targets.md#target-auto-discovery) --- Disables example auto discovery. + * [`autolib`](cargo-targets.md#target-auto-discovery) --- Disables library auto discovery. + * [`autotests`](cargo-targets.md#target-auto-discovery) --- Disables test auto discovery. + * [`build`](#the-build-field) --- Path to the package build script. + * [`categories`](#the-categories-field) --- Categories of the package. + * [`default-run`](#the-default-run-field) --- The default binary to run by [`cargo run`]. * [`documentation`](#the-documentation-field) --- URL of the package documentation. - * [`readme`](#the-readme-field) --- Path to the package's README file. + * [`edition`](#the-edition-field) --- The Rust edition. + * [`exclude`](#the-exclude-and-include-fields) --- Files to exclude when publishing. * [`homepage`](#the-homepage-field) --- URL of the package homepage. - * [`repository`](#the-repository-field) --- URL of the package source repository. + * [`include`](#the-exclude-and-include-fields) --- Files to include when publishing. + * [`keywords`](#the-keywords-field) --- Keywords for the package. * [`license`](#the-license-and-license-file-fields) --- The package license. * [`license-file`](#the-license-and-license-file-fields) --- Path to the text of the license. - * [`keywords`](#the-keywords-field) --- Keywords for the package. - * [`categories`](#the-categories-field) --- Categories of the package. - * [`workspace`](#the-workspace-field) --- Path to the workspace for the package. - * [`build`](#the-build-field) --- Path to the package build script. * [`links`](#the-links-field) --- Name of the native library the package links with. - * [`exclude`](#the-exclude-and-include-fields) --- Files to exclude when publishing. - * [`include`](#the-exclude-and-include-fields) --- Files to include when publishing. - * [`publish`](#the-publish-field) --- Can be used to prevent publishing the package. * [`metadata`](#the-metadata-table) --- Extra settings for external tools. - * [`default-run`](#the-default-run-field) --- The default binary to run by [`cargo run`]. - * [`autolib`](cargo-targets.md#target-auto-discovery) --- Disables library auto discovery. - * [`autobins`](cargo-targets.md#target-auto-discovery) --- Disables binary auto discovery. - * [`autoexamples`](cargo-targets.md#target-auto-discovery) --- Disables example auto discovery. - * [`autotests`](cargo-targets.md#target-auto-discovery) --- Disables test auto discovery. - * [`autobenches`](cargo-targets.md#target-auto-discovery) --- Disables bench auto discovery. + * [`publish`](#the-publish-field) --- Can be used to prevent publishing the package. + * [`readme`](#the-readme-field) --- Path to the package's README file. + * [`repository`](#the-repository-field) --- URL of the package source repository. * [`resolver`](resolver.md#resolver-versions) --- Sets the dependency resolver to use. + * [`rust-version`](rust-version.md) --- The minimal supported Rust version. + * [`workspace`](#the-workspace-field) --- Path to the workspace for the package. + * [`description`](#the-description-field) --- A description of the package. * Target tables: (see [configuration](cargo-targets.md#configuring-a-target) for settings) * [`[lib]`](cargo-targets.md#library) --- Library target settings. * [`[[bin]]`](cargo-targets.md#binaries) --- Binary target settings. @@ -135,47 +135,84 @@ authors = ["Graydon Hoare", "Fnu Lnu "] This field is surfaced in package metadata and in the `CARGO_PKG_AUTHORS` environment variable within `build.rs` for backwards compatibility. -### The `edition` field +## The `[badges]` section -The `edition` key is an optional key that affects which [Rust Edition] your package -is compiled with. Setting the `edition` key in `[package]` will affect all -targets/crates in the package, including test suites, benchmarks, binaries, -examples, etc. +The `[badges]` section is for specifying status badges that can be displayed +on a registry website when the package is published. + +> Note: [crates.io] previously displayed badges next to a crate on its +> website, but that functionality has been removed. Packages should place +> badges in its README file which will be displayed on [crates.io] (see [the +> `readme` field](#the-readme-field)). + +```toml +[badges] +# The `maintenance` table indicates the status of the maintenance of +# the crate. This may be used by a registry, but is currently not +# used by crates.io. See https://github.com/rust-lang/crates.io/issues/2437 +# and https://github.com/rust-lang/crates.io/issues/2438 for more details. +# +# The `status` field is required. Available options are: +# - `actively-developed`: New features are being added and bugs are being fixed. +# - `passively-maintained`: There are no plans for new features, but the maintainer intends to +# respond to issues that get filed. +# - `as-is`: The crate is feature complete, the maintainer does not intend to continue working on +# it or providing support, but it works for the purposes it was designed for. +# - `experimental`: The author wants to share it with the community but is not intending to meet +# anyone's particular use case. +# - `looking-for-maintainer`: The current maintainer would like to transfer the crate to someone +# else. +# - `deprecated`: The maintainer does not recommend using this crate (the description of the crate +# can describe why, there could be a better solution available or there could be problems with +# the crate that the author does not want to fix). +# - `none`: Displays no badge on crates.io, since the maintainer has not chosen to specify +# their intentions, potential crate users will need to investigate on their own. +maintenance = { status = "..." } +``` + +### The `build` field + +The `build` field specifies a file in the package root which is a [build +script] for building native code. More information can be found in the [build +script guide][build script]. + +[build script]: build-scripts.md ```toml [package] # ... -edition = '2024' +build = "build.rs" ``` -Most manifests have the `edition` field filled in automatically by [`cargo new`] -with the latest stable edition. By default `cargo new` creates a manifest with -the 2024 edition currently. +The default is `"build.rs"`, which loads the script from a file named +`build.rs` in the root of the package. Use `build = "custom_build_name.rs"` to +specify a path to a different file or `build = false` to disable automatic +detection of the build script. -If the `edition` field is not present in `Cargo.toml`, then the 2015 edition is -assumed for backwards compatibility. Note that all manifests -created with [`cargo new`] will not use this historical fallback because they -will have `edition` explicitly specified to a newer value. +### The `categories` field -### The `rust-version` field +The `categories` field is an array of strings of the categories this package +belongs to. -The `rust-version` field tells cargo what version of the -Rust toolchain you support for your package. -See [the Rust version chapter](rust-version.md) for more detail. +```toml +categories = ["command-line-utilities", "development-tools::cargo-plugins"] +``` -### The `description` field +> **Note**: [crates.io] has a maximum of 5 categories. Each category should +> match one of the strings available at , and +> must match exactly. -The description is a short blurb about the package. [crates.io] will display -this with your package. This should be plain text (not Markdown). +### The `default-run` field + +The `default-run` field in the `[package]` section of the manifest can be used +to specify a default binary picked by [`cargo run`]. For example, when there is +both `src/bin/a.rs` and `src/bin/b.rs`: ```toml [package] -# ... -description = "A short description of my package" +default-run = "a" ``` -> **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 @@ -191,24 +228,116 @@ documentation = "https://docs.rs/bitflags" [docs.rs queue]: https://docs.rs/releases/queue -### The `readme` field +### The `edition` field -The `readme` field should be the path to a file in the package root (relative -to this `Cargo.toml`) that contains general information about the package. -This file will be transferred to the registry when you publish. [crates.io] -will interpret it as Markdown and render it on the crate's page. +The `edition` key is an optional key that affects which [Rust Edition] your package +is compiled with. Setting the `edition` key in `[package]` will affect all +targets/crates in the package, including test suites, benchmarks, binaries, +examples, etc. ```toml [package] # ... -readme = "README.md" +edition = '2024' ``` -If no value is specified for this field, and a file named `README.md`, -`README.txt` or `README` exists in the package root, then the name of that -file will be used. You can suppress this behavior by setting this field to -`false`. If the field is set to `true`, a default value of `README.md` will -be assumed. +Most manifests have the `edition` field filled in automatically by [`cargo new`] +with the latest stable edition. By default `cargo new` creates a manifest with +the 2024 edition currently. + +If the `edition` field is not present in `Cargo.toml`, then the 2015 edition is +assumed for backwards compatibility. Note that all manifests +created with [`cargo new`] will not use this historical fallback because they +will have `edition` explicitly specified to a newer value. + +### The `exclude` and `include` fields + +The `exclude` and `include` fields can be used to explicitly specify which +files are included when packaging a project to be [published][publishing], +and certain kinds of change tracking (described below). +The patterns specified in the `exclude` field identify a set of files that are +not included, and the patterns in `include` specify files that are explicitly +included. +You may run [`cargo package --list`][`cargo package`] to verify which files will +be included in the package. + +```toml +[package] +# ... +exclude = ["/ci", "images/", ".*"] +``` + +```toml +[package] +# ... +include = ["/src", "COPYRIGHT", "/examples", "!/examples/big_example"] +``` + +The default if neither field is specified is to include all files from the +root of the package, except for the exclusions listed below. + +If `include` is not specified, then the following files will be excluded: + +* If the package is not in a git repository, all "hidden" files starting with + a dot will be skipped. +* If the package is in a git repository, any files that are ignored by the + [gitignore] rules of the repository and global git configuration will be + skipped. + +Regardless of whether `exclude` or `include` is specified, the following files +are always excluded: + +* Any sub-packages will be skipped (any subdirectory that contains a + `Cargo.toml` file). +* A directory named `target` in the root of the package will be skipped. + +The following files are always included: + +* The `Cargo.toml` file of the package itself is always included, it does not + need to be listed in `include`. +* A minimized `Cargo.lock` is automatically included. + See [`cargo package`] for more information. +* If a [`license-file`](#the-license-and-license-file-fields) is specified, it + is always included. + +The options are mutually exclusive; setting `include` will override an +`exclude`. If you need to have exclusions to a set of `include` files, use the +`!` operator described below. + +The patterns should be [gitignore]-style patterns. Briefly: + +- `foo` matches any file or directory with the name `foo` anywhere in the + package. This is equivalent to the pattern `**/foo`. +- `/foo` matches any file or directory with the name `foo` only in the root of + the package. +- `foo/` matches any *directory* with the name `foo` anywhere in the package. +- Common glob patterns like `*`, `?`, and `[]` are supported: + - `*` matches zero or more characters except `/`. For example, `*.html` + matches any file or directory with the `.html` extension anywhere in the + package. + - `?` matches any character except `/`. For example, `foo?` matches `food`, + but not `foo`. + - `[]` allows for matching a range of characters. For example, `[ab]` + matches either `a` or `b`. `[a-z]` matches letters a through z. +- `**/` prefix matches in any directory. For example, `**/foo/bar` matches the + file or directory `bar` anywhere that is directly under directory `foo`. +- `/**` suffix matches everything inside. For example, `foo/**` matches all + files inside directory `foo`, including all files in subdirectories below + `foo`. +- `/**/` matches zero or more directories. For example, `a/**/b` matches + `a/b`, `a/x/b`, `a/x/y/b`, and so on. +- `!` prefix negates a pattern. For example, a pattern of `src/*.rs` and + `!foo.rs` would match all files with the `.rs` extension inside the `src` + directory, except for any file named `foo.rs`. + +The include/exclude list is also used for change tracking in some situations. +For targets built with `rustdoc`, it is used to determine the list of files to +track to determine if the target should be rebuilt. If the package has a +[build script] that does not emit any `rerun-if-*` directives, then the +include/exclude list is used for tracking if the build script should be re-run +if any of those files change. + +[gitignore]: https://git-scm.com/docs/gitignore ### The `homepage` field @@ -225,17 +354,22 @@ A value should only be set for `homepage` if there is a dedicated website for the crate other than the source repository or API documentation. Do not make `homepage` redundant with either the `documentation` or `repository` values. -### The `repository` field +### The `keywords` field -The `repository` field should be a URL to the source repository for your -package. +The `keywords` field is an array of strings that describe this package. This +can help when searching for the package on a registry, and you may choose any +words that would help someone find this crate. ```toml [package] # ... -repository = "https://github.com/rust-lang/cargo" +keywords = ["gamedev", "graphics"] ``` +> **Note**: [crates.io] allows a maximum of 5 keywords. Each keyword must be +> ASCII text, have at most 20 characters, start with an alphanumeric character, +> and only contain letters, numbers, `_`, `-` or `+`. + ### The `license` and `license-file` fields The `license` field contains the name of the software license that the package @@ -278,79 +412,11 @@ license-file = "LICENSE.txt" [^slash]: Previously multiple licenses could be separated with a `/`, but that usage is deprecated. -### The `keywords` field +### The `links` field -The `keywords` field is an array of strings that describe this package. This -can help when searching for the package on a registry, and you may choose any -words that would help someone find this crate. - -```toml -[package] -# ... -keywords = ["gamedev", "graphics"] -``` - -> **Note**: [crates.io] allows a maximum of 5 keywords. Each keyword must be -> ASCII text, have at most 20 characters, start with an alphanumeric character, -> and only contain letters, numbers, `_`, `-` or `+`. - -### The `categories` field - -The `categories` field is an array of strings of the categories this package -belongs to. - -```toml -categories = ["command-line-utilities", "development-tools::cargo-plugins"] -``` - -> **Note**: [crates.io] has a maximum of 5 categories. Each category should -> 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 -will be a member of. If not specified this will be inferred as the first -Cargo.toml with `[workspace]` upwards in the filesystem. Setting this is -useful if the member is not inside a subdirectory of the workspace root. - -```toml -[package] -# ... -workspace = "path/to/workspace/root" -``` - -This field cannot be specified if the manifest already has a `[workspace]` -table defined. That is, a crate cannot both be a root crate in a workspace -(contain `[workspace]`) and also be a member crate of another workspace -(contain `package.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 -script] for building native code. More information can be found in the [build -script guide][build script]. - -[build script]: build-scripts.md - -```toml -[package] -# ... -build = "build.rs" -``` - -The default is `"build.rs"`, which loads the script from a file named -`build.rs` in the root of the package. Use `build = "custom_build_name.rs"` to -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 -to. More information can be found in the [`links`][links] section of the build -script guide. +The `links` field specifies the name of a native library that is being linked +to. More information can be found in the [`links`][links] section of the build +script guide. [links]: build-scripts.md#the-links-manifest-key @@ -363,117 +429,52 @@ on Linux) may specify: links = "git2" ``` -### The `exclude` and `include` fields - -The `exclude` and `include` fields can be used to explicitly specify which -files are included when packaging a project to be [published][publishing], -and certain kinds of change tracking (described below). -The patterns specified in the `exclude` field identify a set of files that are -not included, and the patterns in `include` specify files that are explicitly -included. -You may run [`cargo package --list`][`cargo package`] to verify which files will -be included in the package. +## The `[lints]` section +Override the default level of lints from different tools by assigning them to a new level in a +table, for example: ```toml -[package] -# ... -exclude = ["/ci", "images/", ".*"] +[lints.rust] +unsafe_code = "forbid" ``` +This is short-hand for: ```toml -[package] -# ... -include = ["/src", "COPYRIGHT", "/examples", "!/examples/big_example"] +[lints.rust] +unsafe_code = { level = "forbid", priority = 0 } ``` -The default if neither field is specified is to include all files from the -root of the package, except for the exclusions listed below. - -If `include` is not specified, then the following files will be excluded: - -* If the package is not in a git repository, all "hidden" files starting with - a dot will be skipped. -* If the package is in a git repository, any files that are ignored by the - [gitignore] rules of the repository and global git configuration will be - skipped. - -Regardless of whether `exclude` or `include` is specified, the following files -are always excluded: - -* Any sub-packages will be skipped (any subdirectory that contains a - `Cargo.toml` file). -* A directory named `target` in the root of the package will be skipped. - -The following files are always included: - -* The `Cargo.toml` file of the package itself is always included, it does not - need to be listed in `include`. -* A minimized `Cargo.lock` is automatically included. - See [`cargo package`] for more information. -* If a [`license-file`](#the-license-and-license-file-fields) is specified, it - is always included. - -The options are mutually exclusive; setting `include` will override an -`exclude`. If you need to have exclusions to a set of `include` files, use the -`!` operator described below. - -The patterns should be [gitignore]-style patterns. Briefly: - -- `foo` matches any file or directory with the name `foo` anywhere in the - package. This is equivalent to the pattern `**/foo`. -- `/foo` matches any file or directory with the name `foo` only in the root of - the package. -- `foo/` matches any *directory* with the name `foo` anywhere in the package. -- Common glob patterns like `*`, `?`, and `[]` are supported: - - `*` matches zero or more characters except `/`. For example, `*.html` - matches any file or directory with the `.html` extension anywhere in the - package. - - `?` matches any character except `/`. For example, `foo?` matches `food`, - but not `foo`. - - `[]` allows for matching a range of characters. For example, `[ab]` - matches either `a` or `b`. `[a-z]` matches letters a through z. -- `**/` prefix matches in any directory. For example, `**/foo/bar` matches the - file or directory `bar` anywhere that is directly under directory `foo`. -- `/**` suffix matches everything inside. For example, `foo/**` matches all - files inside directory `foo`, including all files in subdirectories below - `foo`. -- `/**/` matches zero or more directories. For example, `a/**/b` matches - `a/b`, `a/x/b`, `a/x/y/b`, and so on. -- `!` prefix negates a pattern. For example, a pattern of `src/*.rs` and - `!foo.rs` would match all files with the `.rs` extension inside the `src` - directory, except for any file named `foo.rs`. - -The include/exclude list is also used for change tracking in some situations. -For targets built with `rustdoc`, it is used to determine the list of files to -track to determine if the target should be rebuilt. If the package has a -[build script] that does not emit any `rerun-if-*` directives, then the -include/exclude list is used for tracking if the build script should be re-run -if any of those files change. +`level` corresponds to the [lint levels](https://doc.rust-lang.org/rustc/lints/levels.html) in `rustc`: +- `forbid` +- `deny` +- `warn` +- `allow` -[gitignore]: https://git-scm.com/docs/gitignore +`priority` is a signed integer that controls which lints or lint groups override other lint groups: +- lower (particularly negative) numbers have lower priority, being overridden + by higher numbers, and show up first on the command-line to tools like + `rustc` -### The `publish` field +To know which table under `[lints]` a particular lint belongs under, it is the part before `::` in the lint +name. If there isn't a `::`, then the tool is `rust`. For example a warning +about `unsafe_code` would be `lints.rust.unsafe_code` but a lint about +`clippy::enum_glob_use` would be `lints.clippy.enum_glob_use`. -The `publish` field can be used to control which registries names the package -may be published to: +For example: ```toml -[package] -# ... -publish = ["some-registry-name"] -``` +[lints.rust] +unsafe_code = "forbid" -To prevent a package from being published to a registry (like crates.io) by mistake, -for instance to keep a package private in a company, -you can omit the [`version`](#the-version-field) field. -If you'd like to be more explicit, you can disable publishing: -```toml -[package] -# ... -publish = false +[lints.clippy] +enum_glob_use = "deny" ``` -If publish array contains a single registry, `cargo publish` command will use -it when `--registry` flag is not specified. +Generally, these will only affect local development of the current package. +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 `metadata` table @@ -507,99 +508,98 @@ if that makes sense for the tool in question. [workspace-metadata]: workspaces.md#the-metadata-table -### The `default-run` field +### The `publish` field -The `default-run` field in the `[package]` section of the manifest can be used -to specify a default binary picked by [`cargo run`]. For example, when there is -both `src/bin/a.rs` and `src/bin/b.rs`: +The `publish` field can be used to control which registries names the package +may be published to: +```toml +[package] +# ... +publish = ["some-registry-name"] +``` +To prevent a package from being published to a registry (like crates.io) by mistake, +for instance to keep a package private in a company, +you can omit the [`version`](#the-version-field) field. +If you'd like to be more explicit, you can disable publishing: ```toml [package] -default-run = "a" +# ... +publish = false ``` -## The `[lints]` section +If publish array contains a single registry, `cargo publish` command will use +it when `--registry` flag is not specified. + +### The `readme` field + +The `readme` field should be the path to a file in the package root (relative +to this `Cargo.toml`) that contains general information about the package. +This file will be transferred to the registry when you publish. [crates.io] +will interpret it as Markdown and render it on the crate's page. -Override the default level of lints from different tools by assigning them to a new level in a -table, for example: ```toml -[lints.rust] -unsafe_code = "forbid" +[package] +# ... +readme = "README.md" ``` -This is short-hand for: +If no value is specified for this field, and a file named `README.md`, +`README.txt` or `README` exists in the package root, then the name of that +file will be used. You can suppress this behavior by setting this field to +`false`. If the field is set to `true`, a default value of `README.md` will +be assumed. + +### The `repository` field + +The `repository` field should be a URL to the source repository for your +package. + ```toml -[lints.rust] -unsafe_code = { level = "forbid", priority = 0 } +[package] +# ... +repository = "https://github.com/rust-lang/cargo" ``` -`level` corresponds to the [lint levels](https://doc.rust-lang.org/rustc/lints/levels.html) in `rustc`: -- `forbid` -- `deny` -- `warn` -- `allow` +### The `rust-version` field -`priority` is a signed integer that controls which lints or lint groups override other lint groups: -- lower (particularly negative) numbers have lower priority, being overridden - by higher numbers, and show up first on the command-line to tools like - `rustc` +The `rust-version` field tells cargo what version of the +Rust toolchain you support for your package. +See [the Rust version chapter](rust-version.md) for more detail. -To know which table under `[lints]` a particular lint belongs under, it is the part before `::` in the lint -name. If there isn't a `::`, then the tool is `rust`. For example a warning -about `unsafe_code` would be `lints.rust.unsafe_code` but a lint about -`clippy::enum_glob_use` would be `lints.clippy.enum_glob_use`. +### The `workspace` field -For example: -```toml -[lints.rust] -unsafe_code = "forbid" +The `workspace` field can be used to configure the workspace that this package +will be a member of. If not specified this will be inferred as the first +Cargo.toml with `[workspace]` upwards in the filesystem. Setting this is +useful if the member is not inside a subdirectory of the workspace root. -[lints.clippy] -enum_glob_use = "deny" +```toml +[package] +# ... +workspace = "path/to/workspace/root" ``` -Generally, these will only affect local development of the current package. -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 +This field cannot be specified if the manifest already has a `[workspace]` +table defined. That is, a crate cannot both be a root crate in a workspace +(contain `[workspace]`) and also be a member crate of another workspace +(contain `package.workspace`). -## The `[badges]` section +For more information, see the [workspaces chapter](workspaces.md). -The `[badges]` section is for specifying status badges that can be displayed -on a registry website when the package is published. +### The `description` field -> Note: [crates.io] previously displayed badges next to a crate on its -> website, but that functionality has been removed. Packages should place -> badges in its README file which will be displayed on [crates.io] (see [the -> `readme` field](#the-readme-field)). +The description is a short blurb about the package. [crates.io] will display +this with your package. This should be plain text (not Markdown). ```toml -[badges] -# The `maintenance` table indicates the status of the maintenance of -# the crate. This may be used by a registry, but is currently not -# used by crates.io. See https://github.com/rust-lang/crates.io/issues/2437 -# and https://github.com/rust-lang/crates.io/issues/2438 for more details. -# -# The `status` field is required. Available options are: -# - `actively-developed`: New features are being added and bugs are being fixed. -# - `passively-maintained`: There are no plans for new features, but the maintainer intends to -# respond to issues that get filed. -# - `as-is`: The crate is feature complete, the maintainer does not intend to continue working on -# it or providing support, but it works for the purposes it was designed for. -# - `experimental`: The author wants to share it with the community but is not intending to meet -# anyone's particular use case. -# - `looking-for-maintainer`: The current maintainer would like to transfer the crate to someone -# else. -# - `deprecated`: The maintainer does not recommend using this crate (the description of the crate -# can describe why, there could be a better solution available or there could be problems with -# the crate that the author does not want to fix). -# - `none`: Displays no badge on crates.io, since the maintainer has not chosen to specify -# their intentions, potential crate users will need to investigate on their own. -maintenance = { status = "..." } +[package] +# ... +description = "A short description of my package" ``` +> **Note**: [crates.io] requires the `description` to be set. + ## Dependency sections See the [specifying dependencies page](specifying-dependencies.md) for