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