3 The `Cargo.toml` file for each package is called its *manifest*. Every manifest
4 file consists of one or more sections.
6 ### The `[package]` section
8 The first section in a `Cargo.toml` is `[package]`.
12 name = "hello_world" # the name of the package
13 version = "0.1.0" # the current version, obeying semver
14 authors = ["Alice <a@example.com>", "Bob <b@example.com>"]
19 The package name is an identifier used to refer to the package. It is used
20 when listed as a dependency in another package, and as the default name of
21 inferred lib and bin targets.
23 The name must not be empty, use only [alphanumeric] characters or `-` or `_`.
24 Note that `cargo new` and `cargo init` impose some additional restrictions on
25 the package name, such as enforcing that it is a valid Rust identifier and not
26 a keyword. [crates.io][cratesio] imposes even more restrictions, such as
27 enforcing only ASCII characters, not a reserved name, not a special Windows
28 name such as "nul", is not too long, etc.
30 [alphanumeric]: https://doc.rust-lang.org/std/primitive.char.html#method.is_alphanumeric
32 #### The `version` field
34 Cargo bakes in the concept of [Semantic
35 Versioning](https://semver.org/), so make sure you follow some basic rules:
37 * Before you reach 1.0.0, anything goes, but if you make breaking changes,
38 increment the minor version. In Rust, breaking changes include adding fields to
39 structs or variants to enums.
40 * After 1.0.0, only make breaking changes when you increment the major version.
41 Don’t break the build.
42 * After 1.0.0, don’t add any new public API (no new `pub` anything) in patch-level
43 versions. Always increment the minor version if you add any new `pub` structs,
44 traits, fields, types, functions, methods or anything else.
45 * Use version numbers with three numeric parts such as 1.0.0 rather than 1.0.
47 #### The `authors` field (optional)
49 The `authors` field lists people or organizations that are considered the
50 "authors" of the package. The exact meaning is open to interpretation — it may
51 list the original or primary authors, current maintainers, or owners of the
52 package. These names will be listed on the crate's page on
53 [crates.io][cratesio]. An optional email address may be included within angled
54 brackets at the end of each author.
56 #### The `edition` field (optional)
58 You can opt in to a specific Rust Edition for your package with the
59 `edition` key in `Cargo.toml`. If you don't specify the edition, it will
68 The `edition` key affects which edition your package is compiled with. Cargo
69 will always generate packages via `cargo new` with the `edition` key set to the
70 latest edition. Setting the `edition` key in `[package]` will affect all
71 targets/crates in the package, including test suites, benchmarks, binaries,
74 #### The `build` field (optional)
76 This field specifies a file in the package root which is a [build script][1] for
77 building native code. More information can be found in the build script
80 [1]: reference/build-scripts.html
88 #### The `links` field (optional)
90 This field specifies the name of a native library that is being linked to.
91 More information can be found in the [`links`][links] section of the build
94 [links]: reference/build-scripts.html#the-links-manifest-key
103 #### The `documentation` field (optional)
105 This field specifies a URL to a website hosting the crate's documentation.
106 If no URL is specified in the manifest file, [crates.io][cratesio] will
107 automatically link your crate to the corresponding [docs.rs][docsrs] page.
109 Documentation links from specific hosts are blacklisted. Hosts are added
110 to the blacklist if they are known to not be hosting documentation and are
111 possibly of malicious intent e.g. ad tracking networks. URLs from the
112 following hosts are blacklisted:
116 Documentation URLs from blacklisted hosts will not appear on crates.io, and
117 may be replaced by docs.rs links.
119 [docsrs]: https://docs.rs/
120 [cratesio]: https://crates.io/
122 #### The `exclude` and `include` fields (optional)
124 You can explicitly specify to Cargo that a set of [globs][globs] should be
125 ignored or included for the purposes of packaging and rebuilding a package. The
126 globs specified in the `exclude` field identify a set of files that are not
127 included when a package is published as well as ignored for the purposes of
128 detecting when to rebuild a package, and the globs in `include` specify files
129 that are explicitly included.
131 If a VCS is being used for a package, the `exclude` field will be seeded with
132 the VCS’ ignore settings (`.gitignore` for git for example).
137 exclude = ["build/**/*.o", "doc/**/*.html"]
143 include = ["src/**/*", "Cargo.toml"]
146 The options are mutually exclusive: setting `include` will override an
147 `exclude`. Note that `include` must be an exhaustive list of files as otherwise
148 necessary source files may not be included.
150 [globs]: https://docs.rs/glob/0.2.11/glob/struct.Pattern.html
152 #### Migrating to `gitignore`-like pattern matching
154 The current interpretation of these configs is based on UNIX Globs, as
155 implemented in the [`glob` crate](https://crates.io/crates/glob). We want
156 Cargo's `include` and `exclude` configs to work as similar to `gitignore` as
157 possible. [The `gitignore` specification](https://git-scm.com/docs/gitignore) is
158 also based on Globs, but has a bunch of additional features that enable easier
159 pattern writing and more control. Therefore, we are migrating the interpretation
160 for the rules of these configs to use the [`ignore`
161 crate](https://crates.io/crates/ignore), and treat them each rule as a single
162 line in a `gitignore` file. See [the tracking
163 issue](https://github.com/rust-lang/cargo/issues/4268) for more details on the
166 #### The `publish` field (optional)
168 The `publish` field can be used to prevent a package from being published to a
169 package registry (like *crates.io*) by mistake, for instance to keep a package
170 private in a company.
178 #### The `workspace` field (optional)
180 The `workspace` field can be used to configure the workspace that this package
181 will be a member of. If not specified this will be inferred as the first
182 Cargo.toml with `[workspace]` upwards in the filesystem.
187 workspace = "path/to/workspace/root"
190 For more information, see the documentation for the workspace table below.
192 #### Package metadata
194 There are a number of optional metadata fields also accepted under the
201 # A short blurb about the package. This is not rendered in any format when
202 # uploaded to crates.io (aka this is not markdown).
205 # These URLs point to more information about the package. These are
206 # intended to be webviews of the relevant data, not necessarily compatible
207 # with VCS tools and the like.
208 documentation = "..."
212 # This points to a file under the package root (relative to this `Cargo.toml`).
213 # The contents of this file are stored and indexed in the registry.
214 # crates.io will render this file and place the result on the crate's page.
217 # This is a list of up to five keywords that describe this crate. Keywords
218 # are searchable on crates.io, and you may choose any words that would
219 # help someone find this crate.
220 keywords = ["...", "..."]
222 # This is a list of up to five categories where this crate would fit.
223 # Categories are a fixed list available at crates.io/category_slugs, and
224 # they must match exactly.
225 categories = ["...", "..."]
227 # This is an SPDX 2.1 license expression for this package. Currently
228 # crates.io will validate the license provided against a whitelist of
229 # known license and exception identifiers from the SPDX license list
230 # 2.4. Parentheses are not currently supported.
232 # Multiple licenses can be separated with a `/`, although that usage
233 # is deprecated. Instead, use a license expression with AND and OR
234 # operators to get more explicit semantics.
237 # If a package is using a nonstandard license, then this key may be specified in
238 # lieu of the above key and must point to a file relative to this manifest
239 # (similar to the readme key).
242 # Optional specification of badges to be displayed on crates.io.
244 # - The badges pertaining to build status that are currently available are
245 # Appveyor, CircleCI, GitLab, and TravisCI.
246 # - Available badges pertaining to code test coverage are Codecov and
248 # - There are also maintenance-related badges based on isitmaintained.com
249 # which state the issue resolution time, percent of open issues, and future
250 # maintenance intentions.
252 # If a `repository` key is required, this refers to a repository in
253 # `user/repo` format.
256 # Appveyor: `repository` is required. `branch` is optional; default is `master`
257 # `service` is optional; valid values are `github` (default), `bitbucket`, and
258 # `gitlab`; `id` is optional; you can specify the appveyor project id if you
259 # want to use that instead. `project_name` is optional; use when the repository
260 # name differs from the appveyor project name.
261 appveyor = { repository = "...", branch = "master", service = "github" }
263 # Circle CI: `repository` is required. `branch` is optional; default is `master`
264 circle-ci = { repository = "...", branch = "master" }
266 # GitLab: `repository` is required. `branch` is optional; default is `master`
267 gitlab = { repository = "...", branch = "master" }
269 # Travis CI: `repository` in format "<user>/<project>" is required.
270 # `branch` is optional; default is `master`
271 travis-ci = { repository = "...", branch = "master" }
273 # Codecov: `repository` is required. `branch` is optional; default is `master`
274 # `service` is optional; valid values are `github` (default), `bitbucket`, and
276 codecov = { repository = "...", branch = "master", service = "github" }
278 # Coveralls: `repository` is required. `branch` is optional; default is `master`
279 # `service` is optional; valid values are `github` (default) and `bitbucket`.
280 coveralls = { repository = "...", branch = "master", service = "github" }
282 # Is it maintained resolution time: `repository` is required.
283 is-it-maintained-issue-resolution = { repository = "..." }
285 # Is it maintained percentage of open issues: `repository` is required.
286 is-it-maintained-open-issues = { repository = "..." }
288 # Maintenance: `status` is required. Available options are `actively-developed`,
289 # `passively-maintained`, `as-is`, `experimental`, `looking-for-maintainer`,
290 # `deprecated`, and the default `none`, which displays no badge on crates.io.
291 maintenance = { status = "..." }
294 The [crates.io](https://crates.io) registry will render the description, display
295 the license, link to the three URLs and categorize by the keywords. These keys
296 provide useful information to users of the registry and also influence the
297 search ranking of a crate. It is highly discouraged to omit everything in a
300 SPDX 2.1 license expressions are documented
301 [here][spdx-2.1-license-expressions]. The current version of the
302 license list is available [here][spdx-license-list], and version 2.4
303 is available [here][spdx-license-list-2.4].
305 #### The `metadata` table (optional)
307 Cargo by default will warn about unused keys in `Cargo.toml` to assist in
308 detecting typos and such. The `package.metadata` table, however, is completely
309 ignored by Cargo and will not be warned about. This section can be used for
310 tools which would like to store package configuration in `Cargo.toml`. For
318 # Metadata used when generating an Android APK, for example.
319 [package.metadata.android]
320 package-name = "my-awesome-android-app"
321 assets = "path/to/static"
324 ### Dependency sections
326 See the [specifying dependencies page](reference/specifying-dependencies.html) for
327 information on the `[dependencies]`, `[dev-dependencies]`,
328 `[build-dependencies]`, and target-specific `[target.*.dependencies]` sections.
330 ### The `[profile.*]` sections
332 Cargo supports custom configuration of how rustc is invoked through profiles at
333 the top level. Any manifest may declare a profile, but only the top level
334 package’s profiles are actually read. All dependencies’ profiles will be
335 overridden. This is done so the top-level package has control over how its
336 dependencies are compiled.
338 There are four currently supported profile names, all of which have the same
339 configuration available to them. Listed below is the configuration available,
340 along with the defaults for each profile.
343 # The development profile, used for `cargo build`.
345 opt-level = 0 # controls the `--opt-level` the compiler builds with.
346 # 0-1 is good for debugging. 2 is well-optimized. Max is 3.
347 # 's' attempts to reduce size, 'z' reduces size even more.
348 debug = true # (u32 or bool) Include debug information (debug symbols).
349 # Equivalent to `-C debuginfo=2` compiler flag.
350 rpath = false # controls whether compiler should set loader paths.
351 # If true, passes `-C rpath` flag to the compiler.
352 lto = false # Link Time Optimization usually reduces size of binaries
353 # and static libraries. Increases compilation time.
354 # If true, passes `-C lto` flag to the compiler, and if a
355 # string is specified like 'thin' then `-C lto=thin` will
357 debug-assertions = true # controls whether debug assertions are enabled
358 # (e.g. debug_assert!() and arithmetic overflow checks)
359 codegen-units = 16 # if > 1 enables parallel code generation which improves
360 # compile times, but prevents some optimizations.
361 # Passes `-C codegen-units`.
362 panic = 'unwind' # panic strategy (`-C panic=...`), can also be 'abort'
363 incremental = true # whether or not incremental compilation is enabled
364 overflow-checks = true # use overflow checks for integer arithmetic.
365 # Passes the `-C overflow-checks=...` flag to the compiler.
367 # The release profile, used for `cargo build --release` (and the dependencies
368 # for `cargo test --release`, including the local library or binary).
374 debug-assertions = false
378 overflow-checks = false
380 # The testing profile, used for `cargo test` (for `cargo test --release` see
381 # the `release` and `bench` profiles).
387 debug-assertions = true
391 overflow-checks = true
393 # The benchmarking profile, used for `cargo bench` (and the test targets and
394 # unit tests for `cargo test --release`).
400 debug-assertions = false
404 overflow-checks = false
407 ### The `[features]` section
409 Cargo supports features to allow expression of:
411 * conditional compilation options (usable through `cfg` attributes);
412 * optional dependencies, which enhance a package, but are not required; and
413 * clusters of optional dependencies, such as `postgres`, that would include the
414 `postgres` package, the `postgres-macros` package, and possibly other packages
415 (such as development-time mocking libraries, debugging tools, etc.).
417 A feature of a package is either an optional dependency, or a set of other
418 features. The format for specifying features is:
425 # The default set of optional packages. Most people will want to use these
426 # packages, but they are strictly optional. Note that `session` is not a package
427 # but rather another feature listed in this manifest.
428 default = ["jquery", "uglifier", "session"]
430 # A feature with no dependencies is used mainly for conditional compilation,
431 # like `#[cfg(feature = "go-faster")]`.
434 # The `secure-password` feature depends on the bcrypt package. This aliasing
435 # will allow people to talk about the feature in a higher-level way and allow
436 # this package to add more requirements to the feature in the future.
437 secure-password = ["bcrypt"]
439 # Features can be used to reexport features of other packages. The `session`
440 # feature of package `awesome` will ensure that the `session` feature of the
441 # package `cookie` is also enabled.
442 session = ["cookie/session"]
445 # These packages are mandatory and form the core of this package’s distribution.
448 route-recognizer = "=2.1.0"
450 # A list of all of the optional dependencies, some of which are included in the
451 # above `features`. They can be opted into by apps.
452 jquery = { version = "1.0.2", optional = true }
453 uglifier = { version = "1.5.3", optional = true }
454 bcrypt = { version = "*", optional = true }
455 civet = { version = "*", optional = true }
458 To use the package `awesome`:
461 [dependencies.awesome]
463 default-features = false # do not include the default features, and optionally
464 # cherry-pick individual features
465 features = ["secure-password", "civet"]
470 The usage of features is subject to a few rules:
472 * Feature names must not conflict with other package names in the manifest. This
473 is because they are opted into via `features = [...]`, which only has a single
475 * With the exception of the `default` feature, all features are opt-in. To opt
476 out of the default feature, use `default-features = false` and cherry-pick
478 * Feature groups are not allowed to cyclically depend on one another.
479 * Dev-dependencies cannot be optional.
480 * Features groups can only reference optional dependencies.
481 * When a feature is selected, Cargo will call `rustc` with `--cfg
482 feature="${feature_name}"`. If a feature group is included, it and all of its
483 individual features will be included. This can be tested in code via
484 `#[cfg(feature = "foo")]`.
486 Note that it is explicitly allowed for features to not actually activate any
487 optional dependencies. This allows packages to internally enable/disable
488 features without requiring a new dependency.
490 #### Usage in end products
492 One major use-case for this feature is specifying optional features in
493 end-products. For example, the Servo package may want to include optional
494 features that people can enable or disable when they build it.
496 In that case, Servo will describe features in its `Cargo.toml` and they can be
497 enabled using command-line flags:
500 $ cargo build --release --features "shumway pdf"
503 Default features could be excluded using `--no-default-features`.
505 #### Usage in packages
507 In most cases, the concept of *optional dependency* in a library is best
508 expressed as a separate package that the top-level application depends on.
510 However, high-level packages, like Iron or Piston, may want the ability to
511 curate a number of packages for easy installation. The current Cargo system
512 allows them to curate a number of mandatory dependencies into a single package
513 for easy installation.
515 In some cases, packages may want to provide additional curation for optional
518 * grouping a number of low-level optional dependencies together into a single
520 * specifying packages that are recommended (or suggested) to be included by
521 users of the package; and
522 * including a feature (like `secure-password` in the motivating example) that
523 will only work if an optional dependency is available, and would be difficult
524 to implement as a separate package (for example, it may be overly difficult to
525 design an IO package to be completely decoupled from OpenSSL, with opt-in via
526 the inclusion of a separate package).
528 In almost all cases, it is an antipattern to use these features outside of
529 high-level packages that are designed for curation. If a feature is optional, it
530 can almost certainly be expressed as a separate package.
532 ### The `[workspace]` section
534 Packages can define a workspace which is a set of crates that will all share the
535 same `Cargo.lock` and output directory. The `[workspace]` table can be defined
541 # Optional key, inferred from path dependencies if not present.
542 # Additional non-path dependencies that should be included must be given here.
543 # In particular, for a virtual manifest, all members have to be listed.
544 members = ["path/to/member1", "path/to/member2", "path/to/member3/*"]
546 # Optional key, empty if not present.
547 exclude = ["path1", "path/to/dir2"]
550 Workspaces were added to Cargo as part of [RFC 1525] and have a number of
553 * A workspace can contain multiple crates where one of them is the *root crate*.
554 * The *root crate*'s `Cargo.toml` contains the `[workspace]` table, but is not
555 required to have other configuration.
556 * Whenever any crate in the workspace is compiled, output is placed in the
557 *workspace root*. i.e. next to the *root crate*'s `Cargo.toml`.
558 * The lock file for all crates in the workspace resides in the *workspace root*.
559 * The `[patch]`, `[replace]` and `[profile.*]` sections in `Cargo.toml`
561 in the *root crate*'s manifest, and ignored in member crates' manifests.
563 [RFC 1525]: https://github.com/rust-lang/rfcs/blob/master/text/1525-cargo-workspace.md
565 The *root crate* of a workspace, indicated by the presence of `[workspace]` in
566 its manifest, is responsible for defining the entire workspace. All `path`
567 dependencies residing in the workspace directory become members. You can add
568 additional packages to the workspace by listing them in the `members` key. Note
569 that members of the workspaces listed explicitly will also have their path
570 dependencies included in the workspace. Sometimes a package may have a lot of
571 workspace members and it can be onerous to keep up to date. The path dependency
572 can also use [globs][globs] to match multiple paths. Finally, the `exclude`
573 key can be used to blacklist paths from being included in a workspace. This can
574 be useful if some path dependencies aren't desired to be in the workspace at
577 The `package.workspace` manifest key (described above) is used in member crates
578 to point at a workspace's root crate. If this key is omitted then it is inferred
579 to be the first crate whose manifest contains `[workspace]` upwards in the
582 A crate may either specify `package.workspace` or specify `[workspace]`. That
583 is, a crate cannot both be a root crate in a workspace (contain `[workspace]`)
584 and also be a member crate of another workspace (contain `package.workspace`).
586 Most of the time workspaces will not need to be dealt with as `cargo new` and
587 `cargo init` will handle workspace configuration automatically.
589 #### Virtual Manifest
591 In workspace manifests, if the `package` table is present, the workspace root
592 crate will be treated as a normal package, as well as a workspace. If the
593 `package` table is not present in a workspace manifest, it is called a *virtual
596 #### Package selection
598 In a workspace, package-related cargo commands like `cargo build` apply to
599 packages selected by `-p` / `--package` or `--all` command-line parameters.
600 When neither is specified, the optional `default-members` configuration is used:
604 members = ["path/to/member1", "path/to/member2", "path/to/member3/*"]
605 default-members = ["path/to/member2", "path/to/member3/foo"]
608 When specified, `default-members` must expand to a subset of `members`.
610 When `default-members` is not specified, the default is the root manifest
611 if it is a package, or every member manifest (as if `--all` were specified
612 on the command-line) for virtual workspaces.
614 ### The project layout
616 If your package is an executable, name the main source file `src/main.rs`. If it
617 is a library, name the main source file `src/lib.rs`.
619 Cargo will also treat any files located in `src/bin/*.rs` as executables. If your
620 executable consists of more than just one source file, you might also use a directory
621 inside `src/bin` containing a `main.rs` file which will be treated as an executable
622 with a name of the parent directory.
623 Do note, however, once you add a `[[bin]]` section ([see
624 below](#configuring-a-target)), Cargo will no longer automatically build files
625 located in `src/bin/*.rs`. Instead you must create a `[[bin]]` section for
626 each file you want to build.
628 Your package can optionally contain folders named `examples`, `tests`, and
629 `benches`, which Cargo will treat as containing examples,
630 integration tests, and benchmarks respectively. Analogous to `bin` targets, they
631 may be composed of single files or directories with a `main.rs` file.
634 ▾ src/ # directory containing source files
635 lib.rs # the main entry point for libraries and packages
636 main.rs # the main entry point for packages producing executables
637 ▾ bin/ # (optional) directory containing additional executables
639 ▾ */ # (optional) directories containing multi-file executables
641 ▾ examples/ # (optional) examples
643 ▾ */ # (optional) directories containing multi-file examples
645 ▾ tests/ # (optional) integration tests
647 ▾ */ # (optional) directories containing multi-file tests
649 ▾ benches/ # (optional) benchmarks
651 ▾ */ # (optional) directories containing multi-file benchmarks
655 To structure your code after you've created the files and folders for your
656 package, you should remember to use Rust's module system, which you can read
657 about in [the book](https://doc.rust-lang.org/book/crates-and-modules.html).
661 Files located under `examples` are example uses of the functionality provided by
662 the library. When compiled, they are placed in the `target/examples` directory.
664 They can compile either as executables (with a `main()` function) or libraries
665 and pull in the library by using `extern crate <library-name>`. They are
666 compiled when you run your tests to protect them from bitrotting.
668 You can run individual executable examples with the command `cargo run --example
671 Specify `crate-type` to make an example be compiled as a library (additional
672 information about crate types is available in
673 [The Rust Reference](https://doc.rust-lang.org/reference/linkage.html)):
678 crate-type = ["staticlib"]
681 You can build individual library examples with the command `cargo build
682 --example <example-name>`.
686 When you run `cargo test`, Cargo will:
688 * compile and run your library’s unit tests, which are in the files reachable
689 from `lib.rs` (naturally, any sections marked with `#[cfg(test)]` will be
690 considered at this stage);
691 * compile and run your library’s documentation tests, which are embedded inside
692 of documentation blocks;
693 * compile and run your library’s [integration tests](#integration-tests); and
694 * compile your library’s examples.
696 #### Integration tests
698 Each file in `tests/*.rs` is an integration test. When you run `cargo test`,
699 Cargo will compile each of these files as a separate crate. The crate can link
700 to your library by using `extern crate <library-name>`, like any other code that
703 Cargo will not automatically compile files inside subdirectories of `tests`, but
704 an integration test can import modules from these directories as usual. For
705 example, if you want several integration tests to share some code, you can put
706 the shared code in `tests/common/mod.rs` and then put `mod common;` in each of
709 ### Configuring a target
711 All of the `[[bin]]`, `[lib]`, `[[bench]]`, `[[test]]`, and `[[example]]`
712 sections support similar configuration for specifying how a target should be
713 built. The double-bracket sections like `[[bin]]` are array-of-table of
714 [TOML](https://github.com/toml-lang/toml#array-of-tables), which means you can
715 write more than one `[[bin]]` section to make several executables in your crate.
717 The example below uses `[lib]`, but it also applies to all other sections
718 as well. All values listed are the defaults for that option unless otherwise
726 # The name of a target is the name of the library that will be generated. This
727 # is defaulted to the name of the package, with any dashes replaced
728 # with underscores. (Rust `extern crate` declarations reference this name;
729 # therefore the value must be a valid Rust identifier to be usable.)
732 # This field points at where the crate is located, relative to the `Cargo.toml`.
735 # A flag for enabling unit tests for this target. This is used by `cargo test`.
738 # A flag for enabling documentation tests for this target. This is only relevant
739 # for libraries, it has no effect on other sections. This is used by
743 # A flag for enabling benchmarks for this target. This is used by `cargo bench`.
746 # A flag for enabling documentation of this target. This is used by `cargo doc`.
749 # If the target is meant to be a compiler plugin, this field must be set to true
750 # for Cargo to correctly compile it and make it available for all dependencies.
753 # If the target is meant to be a "macros 1.1" procedural macro, this field must
757 # If set to false, `cargo test` will omit the `--test` flag to rustc, which
758 # stops it from generating a test harness. This is useful when the binary being
759 # built manages the test runner itself.
762 # If set then a target can be configured to use a different edition than the
763 # `[package]` is configured to use, perhaps only compiling a library with the
764 # 2018 edition or only compiling one unit test with the 2015 edition. By default
765 # all targets are compiled with the edition specified in `[package]`.
768 # Here's an example of a TOML "array of tables" section, in this case specifying
769 # a binary target name and path.
771 name = "my-cool-binary"
772 path = "src/my-cool-binary.rs"
775 The `[package]` also includes the optional `autobins`, `autoexamples`,
776 `autotests`, and `autobenches` keys to explicitly opt-in or opt-out of
777 auto-discovering specific target kinds.
779 #### The `required-features` field (optional)
781 The `required-features` field specifies which features the target needs in order
782 to be built. If any of the required features are not selected, the target will
783 be skipped. This is only relevant for the `[[bin]]`, `[[bench]]`, `[[test]]`,
784 and `[[example]]` sections, it has no effect on `[lib]`.
795 required-features = ["postgres", "tools"]
798 #### Building dynamic or static libraries
800 If your package produces a library, you can specify which kind of library to
801 build by explicitly listing the library in your `Cargo.toml`:
808 crate-type = ["dylib"] # could be `staticlib` as well
811 The available options are `dylib`, `rlib`, `staticlib`, `cdylib`, and
814 You can read more about the different crate types in the
815 [Rust Reference Manual](https://doc.rust-lang.org/reference/linkage.html)
817 ### The `[patch]` Section
819 This section of Cargo.toml can be used to [override dependencies][replace] with
820 other copies. The syntax is similar to the `[dependencies]` section:
824 foo = { git = 'https://github.com/example/foo' }
825 bar = { path = 'my/local/bar' }
828 git = 'https://github.com/example/baz'
830 [patch.'https://github.com/example/baz']
831 baz = { git = 'https://github.com/example/patched-baz', branch = 'my-branch' }
834 The `[patch]` table is made of dependency-like sub-tables. Each key after
835 `[patch]` is a URL of the source that's being patched, or `crates-io` if
836 you're modifying the https://crates.io registry. In the example above
837 `crates-io` could be replaced with a git URL such as
838 `https://github.com/rust-lang-nursery/log`; the second `[patch]`
839 section in the example uses this to specify a source called `baz`.
841 Each entry in these tables is a normal dependency specification, the same as
842 found in the `[dependencies]` section of the manifest. The dependencies listed
843 in the `[patch]` section are resolved and used to patch the source at the
844 URL specified. The above manifest snippet patches the `crates-io` source (e.g.
845 crates.io itself) with the `foo` crate and `bar` crate. It also
846 patches the `https://github.com/example/baz` source with a `my-branch` that
847 comes from elsewhere.
849 Sources can be patched with versions of crates that do not exist, and they can
850 also be patched with versions of crates that already exist. If a source is
851 patched with a crate version that already exists in the source, then the
852 source's original crate is replaced.
854 More information about overriding dependencies can be found in the [overriding
855 dependencies][replace] section of the documentation and [RFC 1969] for the
856 technical specification of this feature.
858 [RFC 1969]: https://github.com/rust-lang/rfcs/pull/1969
859 [replace]: reference/specifying-dependencies.html#overriding-dependencies
861 ### The `[replace]` Section
863 This section of Cargo.toml can be used to [override dependencies][replace] with
864 other copies. The syntax is similar to the `[dependencies]` section:
868 "foo:0.1.0" = { git = 'https://github.com/example/foo' }
869 "bar:1.0.2" = { path = 'my/local/bar' }
872 Each key in the `[replace]` table is a [package id
873 specification](reference/pkgid-spec.html) which allows arbitrarily choosing a node in the
874 dependency graph to override. The value of each key is the same as the
875 `[dependencies]` syntax for specifying dependencies, except that you can't
876 specify features. Note that when a crate is overridden the copy it's overridden
877 with must have both the same name and version, but it can come from a different
878 source (e.g. git or a local path).
880 More information about overriding dependencies can be found in the [overriding
881 dependencies][replace] section of the documentation.
883 [spdx-2.1-license-expressions]: https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60
884 [spdx-license-list]: https://spdx.org/licenses/
885 [spdx-license-list-2.4]: https://github.com/spdx/license-list-data/tree/v2.4