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