1## The Manifest Format 2 3The `Cargo.toml` file for each package is called its *manifest*. It is written 4in the [TOML] format. Every manifest file consists of the following sections: 5 6* [`cargo-features`](unstable.md) — Unstable, nightly-only features. 7* [`[package]`](#the-package-section) — Defines a package. 8 * [`name`](#the-name-field) — The name of the package. 9 * [`version`](#the-version-field) — The version of the package. 10 * [`authors`](#the-authors-field) — The authors of the package. 11 * [`edition`](#the-edition-field) — The Rust edition. 12 * [`rust-version`](#the-rust-version-field) — The minimal supported Rust version. 13 * [`description`](#the-description-field) — A description of the package. 14 * [`documentation`](#the-documentation-field) — URL of the package documentation. 15 * [`readme`](#the-readme-field) — Path to the package's README file. 16 * [`homepage`](#the-homepage-field) — URL of the package homepage. 17 * [`repository`](#the-repository-field) — URL of the package source repository. 18 * [`license`](#the-license-and-license-file-fields) — The package license. 19 * [`license-file`](#the-license-and-license-file-fields) — Path to the text of the license. 20 * [`keywords`](#the-keywords-field) — Keywords for the package. 21 * [`categories`](#the-categories-field) — Categories of the package. 22 * [`workspace`](#the-workspace-field) — Path to the workspace for the package. 23 * [`build`](#the-build-field) — Path to the package build script. 24 * [`links`](#the-links-field) — Name of the native library the package links with. 25 * [`exclude`](#the-exclude-and-include-fields) — Files to exclude when publishing. 26 * [`include`](#the-exclude-and-include-fields) — Files to include when publishing. 27 * [`publish`](#the-publish-field) — Can be used to prevent publishing the package. 28 * [`metadata`](#the-metadata-table) — Extra settings for external tools. 29 * [`default-run`](#the-default-run-field) — The default binary to run by [`cargo run`]. 30 * [`autobins`](cargo-targets.md#target-auto-discovery) — Disables binary auto discovery. 31 * [`autoexamples`](cargo-targets.md#target-auto-discovery) — Disables example auto discovery. 32 * [`autotests`](cargo-targets.md#target-auto-discovery) — Disables test auto discovery. 33 * [`autobenches`](cargo-targets.md#target-auto-discovery) — Disables bench auto discovery. 34 * [`resolver`](resolver.md#resolver-versions) — Sets the dependency resolver to use. 35* Target tables: (see [configuration](cargo-targets.md#configuring-a-target) for settings) 36 * [`[lib]`](cargo-targets.md#library) — Library target settings. 37 * [`[[bin]]`](cargo-targets.md#binaries) — Binary target settings. 38 * [`[[example]]`](cargo-targets.md#examples) — Example target settings. 39 * [`[[test]]`](cargo-targets.md#tests) — Test target settings. 40 * [`[[bench]]`](cargo-targets.md#benchmarks) — Benchmark target settings. 41* Dependency tables: 42 * [`[dependencies]`](specifying-dependencies.md) — Package library dependencies. 43 * [`[dev-dependencies]`](specifying-dependencies.md#development-dependencies) — Dependencies for examples, tests, and benchmarks. 44 * [`[build-dependencies]`](specifying-dependencies.md#build-dependencies) — Dependencies for build scripts. 45 * [`[target]`](specifying-dependencies.md#platform-specific-dependencies) — Platform-specific dependencies. 46* [`[badges]`](#the-badges-section) — Badges to display on a registry. 47* [`[features]`](features.md) — Conditional compilation features. 48* [`[patch]`](overriding-dependencies.md#the-patch-section) — Override dependencies. 49* [`[replace]`](overriding-dependencies.md#the-replace-section) — Override dependencies (deprecated). 50* [`[profile]`](profiles.md) — Compiler settings and optimizations. 51* [`[workspace]`](workspaces.md) — The workspace definition. 52 53<a id="package-metadata"></a> 54### The `[package]` section 55 56The first section in a `Cargo.toml` is `[package]`. 57 58```toml 59[package] 60name = "hello_world" # the name of the package 61version = "0.1.0" # the current version, obeying semver 62authors = ["Alice <a@example.com>", "Bob <b@example.com>"] 63``` 64 65The only fields required by Cargo are [`name`](#the-name-field) and 66[`version`](#the-version-field). If publishing to a registry, the registry may 67require additional fields. See the notes below and [the publishing 68chapter][publishing] for requirements for publishing to [crates.io]. 69 70#### The `name` field 71 72The package name is an identifier used to refer to the package. It is used 73when listed as a dependency in another package, and as the default name of 74inferred lib and bin targets. 75 76The name must use only [alphanumeric] characters or `-` or `_`, and cannot be empty. 77Note that [`cargo new`] and [`cargo init`] impose some additional restrictions on 78the package name, such as enforcing that it is a valid Rust identifier and not 79a keyword. [crates.io] imposes even more restrictions, such as 80enforcing only ASCII characters, not a reserved name, not a special Windows 81name such as "nul", is not too long, etc. 82 83[alphanumeric]: ../../std/primitive.char.html#method.is_alphanumeric 84 85#### The `version` field 86 87Cargo bakes in the concept of [Semantic 88Versioning](https://semver.org/), so make sure you follow some basic rules: 89 90* Before you reach 1.0.0, anything goes, but if you make breaking changes, 91 increment the minor version. In Rust, breaking changes include adding fields to 92 structs or variants to enums. 93* After 1.0.0, only make breaking changes when you increment the major version. 94 Don’t break the build. 95* After 1.0.0, don’t add any new public API (no new `pub` anything) in patch-level 96 versions. Always increment the minor version if you add any new `pub` structs, 97 traits, fields, types, functions, methods or anything else. 98* Use version numbers with three numeric parts such as 1.0.0 rather than 1.0. 99 100See the [Resolver] chapter for more information on how Cargo uses versions to 101resolve dependencies, and for guidelines on setting your own version. See the 102[SemVer compatibility] chapter for more details on exactly what constitutes a 103breaking change. 104 105[Resolver]: resolver.md 106[SemVer compatibility]: semver.md 107 108<a id="the-authors-field-optional"></a> 109#### The `authors` field 110 111The optional `authors` field lists people or organizations that are considered 112the "authors" of the package. The exact meaning is open to interpretation — it 113may list the original or primary authors, current maintainers, or owners of the 114package. An optional email address may be included within angled brackets at 115the end of each author entry. 116 117This field is only surfaced in package metadata and in the `CARGO_PKG_AUTHORS` 118environment variable within `build.rs`. It is not displayed in the [crates.io] 119user interface. 120 121> **Warning**: Package manifests cannot be changed once published, so this 122> field cannot be changed or removed in already-published versions of a 123> package. 124 125<a id="the-edition-field-optional"></a> 126#### The `edition` field 127 128The `edition` key is an optional key that affects which [Rust Edition] your package 129is compiled with. Setting the `edition` key in `[package]` will affect all 130targets/crates in the package, including test suites, benchmarks, binaries, 131examples, etc. 132 133```toml 134[package] 135# ... 136edition = '2021' 137``` 138 139Most manifests have the `edition` field filled in automatically by [`cargo new`] 140with the latest stable edition. By default `cargo new` creates a manifest with 141the 2021 edition currently. 142 143If the `edition` field is not present in `Cargo.toml`, then the 2015 edition is 144assumed for backwards compatibility. Note that all manifests 145created with [`cargo new`] will not use this historical fallback because they 146will have `edition` explicitly specified to a newer value. 147 148#### The `rust-version` field 149 150The `rust-version` field is an optional key that tells cargo what version of the 151Rust language and compiler your package can be compiled with. If the currently 152selected version of the Rust compiler is older than the stated version, cargo 153will exit with an error, telling the user what version is required. 154 155The first version of Cargo that supports this field was released with Rust 1.56.0. 156In older releases, the field will be ignored, and Cargo will display a warning. 157 158```toml 159[package] 160# ... 161rust-version = "1.56" 162``` 163 164The Rust version must be a bare version number with two or three components; it 165cannot include semver operators or pre-release identifiers. Compiler pre-release 166identifiers such as -nightly will be ignored while checking the Rust version. 167The `rust-version` must be equal to or newer than the version that first 168introduced the configured `edition`. 169 170The `rust-version` may be ignored using the `--ignore-rust-version` option. 171 172Setting the `rust-version` key in `[package]` will affect all targets/crates in 173the package, including test suites, benchmarks, binaries, examples, etc. 174 175#### The `description` field 176 177The description is a short blurb about the package. [crates.io] will display 178this with your package. This should be plain text (not Markdown). 179 180```toml 181[package] 182# ... 183description = "A short description of my package" 184``` 185 186> **Note**: [crates.io] requires the `description` to be set. 187 188<a id="the-documentation-field-optional"></a> 189#### The `documentation` field 190 191The `documentation` field specifies a URL to a website hosting the crate's 192documentation. If no URL is specified in the manifest file, [crates.io] will 193automatically link your crate to the corresponding [docs.rs] page. 194 195```toml 196[package] 197# ... 198documentation = "https://docs.rs/bitflags" 199``` 200 201#### The `readme` field 202 203The `readme` field should be the path to a file in the package root (relative 204to this `Cargo.toml`) that contains general information about the package. 205This file will be transferred to the registry when you publish. [crates.io] 206will interpret it as Markdown and render it on the crate's page. 207 208```toml 209[package] 210# ... 211readme = "README.md" 212``` 213 214If no value is specified for this field, and a file named `README.md`, 215`README.txt` or `README` exists in the package root, then the name of that 216file will be used. You can suppress this behavior by setting this field to 217`false`. If the field is set to `true`, a default value of `README.md` will 218be assumed. 219 220#### The `homepage` field 221 222The `homepage` field should be a URL to a site that is the home page for your 223package. 224 225```toml 226[package] 227# ... 228homepage = "https://serde.rs/" 229``` 230 231#### The `repository` field 232 233The `repository` field should be a URL to the source repository for your 234package. 235 236```toml 237[package] 238# ... 239repository = "https://github.com/rust-lang/cargo/" 240``` 241 242#### The `license` and `license-file` fields 243 244The `license` field contains the name of the software license that the package 245is released under. The `license-file` field contains the path to a file 246containing the text of the license (relative to this `Cargo.toml`). 247 248[crates.io] interprets the `license` field as an [SPDX 2.1 license 249expression][spdx-2.1-license-expressions]. The name must be a known license 250from the [SPDX license list 3.11][spdx-license-list-3.11]. Parentheses are not 251currently supported. See the [SPDX site] for more information. 252 253SPDX license expressions support AND and OR operators to combine multiple 254licenses.[^slash] 255 256```toml 257[package] 258# ... 259license = "MIT OR Apache-2.0" 260``` 261 262Using `OR` indicates the user may choose either license. Using `AND` indicates 263the user must comply with both licenses simultaneously. The `WITH` operator 264indicates a license with a special exception. Some examples: 265 266* `MIT OR Apache-2.0` 267* `LGPL-2.1-only AND MIT AND BSD-2-Clause` 268* `GPL-2.0-or-later WITH Bison-exception-2.2` 269 270If a package is using a nonstandard license, then the `license-file` field may 271be specified in lieu of the `license` field. 272 273```toml 274[package] 275# ... 276license-file = "LICENSE.txt" 277``` 278 279> **Note**: [crates.io] requires either `license` or `license-file` to be set. 280 281[^slash]: Previously multiple licenses could be separated with a `/`, but that 282usage is deprecated. 283 284#### The `keywords` field 285 286The `keywords` field is an array of strings that describe this package. This 287can help when searching for the package on a registry, and you may choose any 288words that would help someone find this crate. 289 290```toml 291[package] 292# ... 293keywords = ["gamedev", "graphics"] 294``` 295 296> **Note**: [crates.io] has a maximum of 5 keywords. Each keyword must be 297> ASCII text, start with a letter, and only contain letters, numbers, `_` or 298> `-`, and have at most 20 characters. 299 300#### The `categories` field 301 302The `categories` field is an array of strings of the categories this package 303belongs to. 304 305```toml 306categories = ["command-line-utilities", "development-tools::cargo-plugins"] 307``` 308 309> **Note**: [crates.io] has a maximum of 5 categories. Each category should 310> match one of the strings available at <https://crates.io/category_slugs>, and 311> must match exactly. 312 313<a id="the-workspace--field-optional"></a> 314#### The `workspace` field 315 316The `workspace` field can be used to configure the workspace that this package 317will be a member of. If not specified this will be inferred as the first 318Cargo.toml with `[workspace]` upwards in the filesystem. Setting this is 319useful if the member is not inside a subdirectory of the workspace root. 320 321```toml 322[package] 323# ... 324workspace = "path/to/workspace/root" 325``` 326 327This field cannot be specified if the manifest already has a `[workspace]` 328table defined. That is, a crate cannot both be a root crate in a workspace 329(contain `[workspace]`) and also be a member crate of another workspace 330(contain `package.workspace`). 331 332For more information, see the [workspaces chapter](workspaces.md). 333 334<a id="package-build"></a> 335<a id="the-build-field-optional"></a> 336#### The `build` field 337 338The `build` field specifies a file in the package root which is a [build 339script] for building native code. More information can be found in the [build 340script guide][build script]. 341 342[build script]: build-scripts.md 343 344```toml 345[package] 346# ... 347build = "build.rs" 348``` 349 350The default is `"build.rs"`, which loads the script from a file named 351`build.rs` in the root of the package. Use `build = "custom_build_name.rs"` to 352specify a path to a different file or `build = false` to disable automatic 353detection of the build script. 354 355<a id="the-links-field-optional"></a> 356#### The `links` field 357 358The `links` field specifies the name of a native library that is being linked 359to. More information can be found in the [`links`][links] section of the build 360script guide. 361 362[links]: build-scripts.md#the-links-manifest-key 363 364```toml 365[package] 366# ... 367links = "foo" 368``` 369 370<a id="the-exclude-and-include-fields-optional"></a> 371#### The `exclude` and `include` fields 372 373The `exclude` and `include` fields can be used to explicitly specify which 374files are included when packaging a project to be [published][publishing], 375and certain kinds of change tracking (described below). 376The patterns specified in the `exclude` field identify a set of files that are 377not included, and the patterns in `include` specify files that are explicitly 378included. 379You may run [`cargo package --list`][`cargo package`] to verify which files will 380be included in the package. 381 382```toml 383[package] 384# ... 385exclude = ["/ci", "images/", ".*"] 386``` 387 388```toml 389[package] 390# ... 391include = ["/src", "COPYRIGHT", "/examples", "!/examples/big_example"] 392``` 393 394The default if neither field is specified is to include all files from the 395root of the package, except for the exclusions listed below. 396 397If `include` is not specified, then the following files will be excluded: 398 399* If the package is not in a git repository, all "hidden" files starting with 400 a dot will be skipped. 401* If the package is in a git repository, any files that are ignored by the 402 [gitignore] rules of the repository and global git configuration will be 403 skipped. 404 405Regardless of whether `exclude` or `include` is specified, the following files 406are always excluded: 407 408* Any sub-packages will be skipped (any subdirectory that contains a 409 `Cargo.toml` file). 410* A directory named `target` in the root of the package will be skipped. 411 412The following files are always included: 413 414* The `Cargo.toml` file of the package itself is always included, it does not 415 need to be listed in `include`. 416* A minimized `Cargo.lock` is automatically included if the package contains a 417 binary or example target, see [`cargo package`] for more information. 418* If a [`license-file`](#the-license-and-license-file-fields) is specified, it 419 is always included. 420 421The options are mutually exclusive; setting `include` will override an 422`exclude`. If you need to have exclusions to a set of `include` files, use the 423`!` operator described below. 424 425The patterns should be [gitignore]-style patterns. Briefly: 426 427- `foo` matches any file or directory with the name `foo` anywhere in the 428 package. This is equivalent to the pattern `**/foo`. 429- `/foo` matches any file or directory with the name `foo` only in the root of 430 the package. 431- `foo/` matches any *directory* with the name `foo` anywhere in the package. 432- Common glob patterns like `*`, `?`, and `[]` are supported: 433 - `*` matches zero or more characters except `/`. For example, `*.html` 434 matches any file or directory with the `.html` extension anywhere in the 435 package. 436 - `?` matches any character except `/`. For example, `foo?` matches `food`, 437 but not `foo`. 438 - `[]` allows for matching a range of characters. For example, `[ab]` 439 matches either `a` or `b`. `[a-z]` matches letters a through z. 440- `**/` prefix matches in any directory. For example, `**/foo/bar` matches the 441 file or directory `bar` anywhere that is directly under directory `foo`. 442- `/**` suffix matches everything inside. For example, `foo/**` matches all 443 files inside directory `foo`, including all files in subdirectories below 444 `foo`. 445- `/**/` matches zero or more directories. For example, `a/**/b` matches 446 `a/b`, `a/x/b`, `a/x/y/b`, and so on. 447- `!` prefix negates a pattern. For example, a pattern of `src/*.rs` and 448 `!foo.rs` would match all files with the `.rs` extension inside the `src` 449 directory, except for any file named `foo.rs`. 450 451The include/exclude list is also used for change tracking in some situations. 452For targets built with `rustdoc`, it is used to determine the list of files to 453track to determine if the target should be rebuilt. If the package has a 454[build script] that does not emit any `rerun-if-*` directives, then the 455include/exclude list is used for tracking if the build script should be re-run 456if any of those files change. 457 458[gitignore]: https://git-scm.com/docs/gitignore 459 460<a id="the-publish--field-optional"></a> 461#### The `publish` field 462 463The `publish` field can be used to prevent a package from being published to a 464package registry (like *crates.io*) by mistake, for instance to keep a package 465private in a company. 466 467```toml 468[package] 469# ... 470publish = false 471``` 472 473The value may also be an array of strings which are registry names that are 474allowed to be published to. 475 476```toml 477[package] 478# ... 479publish = ["some-registry-name"] 480``` 481 482If publish array contains a single registry, `cargo publish` command will use 483it when `--registry` flag is not specified. 484 485<a id="the-metadata-table-optional"></a> 486#### The `metadata` table 487 488Cargo by default will warn about unused keys in `Cargo.toml` to assist in 489detecting typos and such. The `package.metadata` table, however, is completely 490ignored by Cargo and will not be warned about. This section can be used for 491tools which would like to store package configuration in `Cargo.toml`. For 492example: 493 494```toml 495[package] 496name = "..." 497# ... 498 499# Metadata used when generating an Android APK, for example. 500[package.metadata.android] 501package-name = "my-awesome-android-app" 502assets = "path/to/static" 503``` 504 505There is a similar table at the workspace level at 506[`workspace.metadata`][workspace-metadata]. While cargo does not specify a 507format for the content of either of these tables, it is suggested that 508external tools may wish to use them in a consistent fashion, such as referring 509to the data in `workspace.metadata` if data is missing from `package.metadata`, 510if that makes sense for the tool in question. 511 512[workspace-metadata]: workspaces.md#the-workspacemetadata-table 513 514#### The `default-run` field 515 516The `default-run` field in the `[package]` section of the manifest can be used 517to specify a default binary picked by [`cargo run`]. For example, when there is 518both `src/bin/a.rs` and `src/bin/b.rs`: 519 520```toml 521[package] 522default-run = "a" 523``` 524 525### The `[badges]` section 526 527The `[badges]` section is for specifying status badges that can be displayed 528on a registry website when the package is published. 529 530> Note: [crates.io] previously displayed badges next to a crate on its 531> website, but that functionality has been removed. Packages should place 532> badges in its README file which will be displayed on [crates.io] (see [the 533> `readme` field](#the-readme-field)). 534 535```toml 536[badges] 537# The `maintenance` table indicates the status of the maintenance of 538# the crate. This may be used by a registry, but is currently not 539# used by crates.io. See https://github.com/rust-lang/crates.io/issues/2437 540# and https://github.com/rust-lang/crates.io/issues/2438 for more details. 541# 542# The `status` field is required. Available options are: 543# - `actively-developed`: New features are being added and bugs are being fixed. 544# - `passively-maintained`: There are no plans for new features, but the maintainer intends to 545# respond to issues that get filed. 546# - `as-is`: The crate is feature complete, the maintainer does not intend to continue working on 547# it or providing support, but it works for the purposes it was designed for. 548# - `experimental`: The author wants to share it with the community but is not intending to meet 549# anyone's particular use case. 550# - `looking-for-maintainer`: The current maintainer would like to transfer the crate to someone 551# else. 552# - `deprecated`: The maintainer does not recommend using this crate (the description of the crate 553# can describe why, there could be a better solution available or there could be problems with 554# the crate that the author does not want to fix). 555# - `none`: Displays no badge on crates.io, since the maintainer has not chosen to specify 556# their intentions, potential crate users will need to investigate on their own. 557maintenance = { status = "..." } 558``` 559 560### Dependency sections 561 562See the [specifying dependencies page](specifying-dependencies.md) for 563information on the `[dependencies]`, `[dev-dependencies]`, 564`[build-dependencies]`, and target-specific `[target.*.dependencies]` sections. 565 566### The `[profile.*]` sections 567 568The `[profile]` tables provide a way to customize compiler settings such as 569optimizations and debug settings. See [the Profiles chapter](profiles.md) for 570more detail. 571 572 573 574[`cargo init`]: ../commands/cargo-init.md 575[`cargo new`]: ../commands/cargo-new.md 576[`cargo package`]: ../commands/cargo-package.md 577[`cargo run`]: ../commands/cargo-run.md 578[crates.io]: https://crates.io/ 579[docs.rs]: https://docs.rs/ 580[publishing]: publishing.md 581[Rust Edition]: ../../edition-guide/index.html 582[spdx-2.1-license-expressions]: https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60 583[spdx-license-list-3.11]: https://github.com/spdx/license-list-data/tree/v3.11 584[SPDX site]: https://spdx.org/license-list 585[TOML]: https://toml.io/ 586 587<script> 588(function() { 589 var fragments = { 590 "#the-project-layout": "../guide/project-layout.html", 591 "#examples": "cargo-targets.html#examples", 592 "#tests": "cargo-targets.html#tests", 593 "#integration-tests": "cargo-targets.html#integration-tests", 594 "#configuring-a-target": "cargo-targets.html#configuring-a-target", 595 "#target-auto-discovery": "cargo-targets.html#target-auto-discovery", 596 "#the-required-features-field-optional": "cargo-targets.html#the-required-features-field", 597 "#building-dynamic-or-static-libraries": "cargo-targets.html#the-crate-type-field", 598 "#the-workspace-section": "workspaces.html#the-workspace-section", 599 "#virtual-manifest": "workspaces.html", 600 "#package-selection": "workspaces.html#package-selection", 601 "#the-features-section": "features.html#the-features-section", 602 "#rules": "features.html", 603 "#usage-in-end-products": "features.html", 604 "#usage-in-packages": "features.html", 605 "#the-patch-section": "overriding-dependencies.html#the-patch-section", 606 "#using-patch-with-multiple-versions": "overriding-dependencies.html#using-patch-with-multiple-versions", 607 "#the-replace-section": "overriding-dependencies.html#the-replace-section", 608 }; 609 var target = fragments[window.location.hash]; 610 if (target) { 611 var url = window.location.toString(); 612 var base = url.substring(0, url.lastIndexOf('/')); 613 window.location.replace(base + "/" + target); 614 } 615})(); 616</script> 617