]>
Commit | Line | Data |
---|---|---|
4d590f95 BE |
1 | ## The Manifest Format |
2 | ||
79d10021 BE |
3 | The `Cargo.toml` file for each package is called its *manifest*. Every manifest |
4 | file consists of one or more sections. | |
5 | ||
4d590f95 BE |
6 | ### The `[package]` section |
7 | ||
8 | The first section in a `Cargo.toml` is `[package]`. | |
9 | ||
10 | ```toml | |
11 | [package] | |
12 | name = "hello_world" # the name of the package | |
13 | version = "0.1.0" # the current version, obeying semver | |
14 | authors = ["you@example.com"] | |
15 | ``` | |
16 | ||
17 | All three of these fields are mandatory. | |
18 | ||
19 | #### The `version` field | |
20 | ||
21 | Cargo bakes in the concept of [Semantic | |
22 | Versioning](http://semver.org/), so make sure you follow some basic rules: | |
23 | ||
24 | * Before you reach 1.0.0, anything goes, but if you make breaking changes, | |
25 | increment the minor version. In Rust, breaking changes include adding fields to | |
26 | structs or variants to enums. | |
27 | * After 1.0.0, only make breaking changes when you increment the major version. | |
28 | Don’t break the build. | |
29 | * After 1.0.0, don’t add any new public API (no new `pub` anything) in tiny | |
30 | versions. Always increment the minor version if you add any new `pub` structs, | |
31 | traits, fields, types, functions, methods or anything else. | |
32 | * Use version numbers with three numeric parts such as 1.0.0 rather than 1.0. | |
33 | ||
34 | #### The `build` field (optional) | |
35 | ||
917c3634 | 36 | This field specifies a file in the project root which is a [build script][1] for |
4d590f95 BE |
37 | building native code. More information can be found in the build script |
38 | [guide][1]. | |
39 | ||
3f2d93e3 | 40 | [1]: reference/build-scripts.html |
4d590f95 BE |
41 | |
42 | ```toml | |
43 | [package] | |
44 | # ... | |
45 | build = "build.rs" | |
46 | ``` | |
47 | ||
48 | #### The `documentation` field (optional) | |
49 | ||
50 | This field specifies a URL to a website hosting the crate's documentation. | |
51 | If no URL is specified in the manifest file, [crates.io][cratesio] will | |
52 | automatically link your crate to the corresponding [docs.rs][docsrs] page. | |
53 | ||
54 | Documentation links from specific hosts are blacklisted. Hosts are added | |
55 | to the blacklist if they are known to not be hosting documentation and are | |
56 | possibly of malicious intent e.g. ad tracking networks. URLs from the | |
57 | following hosts are blacklisted: | |
917c3634 BE |
58 | |
59 | * rust-ci.org | |
4d590f95 BE |
60 | |
61 | Documentation URLs from blacklisted hosts will not appear on crates.io, and | |
62 | may be replaced by docs.rs links. | |
63 | ||
64 | [docsrs]: https://docs.rs/ | |
65 | [cratesio]: https://crates.io/ | |
66 | ||
67 | #### The `exclude` and `include` fields (optional) | |
68 | ||
69 | You can explicitly specify to Cargo that a set of [globs][globs] should be | |
70 | ignored or included for the purposes of packaging and rebuilding a package. The | |
71 | globs specified in the `exclude` field identify a set of files that are not | |
72 | included when a package is published as well as ignored for the purposes of | |
73 | detecting when to rebuild a package, and the globs in `include` specify files | |
74 | that are explicitly included. | |
75 | ||
76 | If a VCS is being used for a package, the `exclude` field will be seeded with | |
77 | the VCS’ ignore settings (`.gitignore` for git for example). | |
78 | ||
79 | ```toml | |
80 | [package] | |
81 | # ... | |
82 | exclude = ["build/**/*.o", "doc/**/*.html"] | |
83 | ``` | |
84 | ||
85 | ```toml | |
86 | [package] | |
87 | # ... | |
88 | include = ["src/**/*", "Cargo.toml"] | |
89 | ``` | |
90 | ||
91 | The options are mutually exclusive: setting `include` will override an | |
92 | `exclude`. Note that `include` must be an exhaustive list of files as otherwise | |
93 | necessary source files may not be included. | |
94 | ||
95 | [globs]: http://doc.rust-lang.org/glob/glob/struct.Pattern.html | |
96 | ||
97 | #### Migrating to `gitignore`-like pattern matching | |
98 | ||
99 | The current interpretation of these configs is based on UNIX Globs, as | |
100 | implemented in the [`glob` crate](https://crates.io/crates/glob). We want | |
101 | Cargo's `include` and `exclude` configs to work as similar to `gitignore` as | |
102 | possible. [The `gitignore` specification](https://git-scm.com/docs/gitignore) is | |
103 | also based on Globs, but has a bunch of additional features that enable easier | |
104 | pattern writing and more control. Therefore, we are migrating the interpretation | |
105 | for the rules of these configs to use the [`ignore` | |
106 | crate](https://crates.io/crates/ignore), and treat them each rule as a single | |
107 | line in a `gitignore` file. See [the tracking | |
108 | issue](https://github.com/rust-lang/cargo/issues/4268) for more details on the | |
109 | migration. | |
110 | ||
111 | #### The `publish` field (optional) | |
112 | ||
113 | The `publish` field can be used to prevent a package from being published to a | |
917c3634 | 114 | package registry (like *crates.io*) by mistake. |
4d590f95 BE |
115 | |
116 | ```toml | |
117 | [package] | |
118 | # ... | |
119 | publish = false | |
120 | ``` | |
121 | ||
122 | #### The `workspace` field (optional) | |
123 | ||
124 | The `workspace` field can be used to configure the workspace that this package | |
125 | will be a member of. If not specified this will be inferred as the first | |
126 | Cargo.toml with `[workspace]` upwards in the filesystem. | |
127 | ||
128 | ```toml | |
129 | [package] | |
130 | # ... | |
917c3634 | 131 | workspace = "path/to/workspace/root" |
4d590f95 BE |
132 | ``` |
133 | ||
134 | For more information, see the documentation for the workspace table below. | |
135 | ||
136 | #### Package metadata | |
137 | ||
138 | There are a number of optional metadata fields also accepted under the | |
139 | `[package]` section: | |
140 | ||
141 | ```toml | |
142 | [package] | |
143 | # ... | |
144 | ||
145 | # A short blurb about the package. This is not rendered in any format when | |
146 | # uploaded to crates.io (aka this is not markdown). | |
147 | description = "..." | |
148 | ||
917c3634 | 149 | # These URLs point to more information about the package. These are |
4d590f95 BE |
150 | # intended to be webviews of the relevant data, not necessarily compatible |
151 | # with VCS tools and the like. | |
152 | documentation = "..." | |
153 | homepage = "..." | |
154 | repository = "..." | |
155 | ||
917c3634 BE |
156 | # This points to a file under the package root (relative to this `Cargo.toml`). |
157 | # The contents of this file are stored and indexed in the registry. | |
5ccf654c | 158 | # crates.io will render this file and place the result on the crate's page. |
4d590f95 BE |
159 | readme = "..." |
160 | ||
161 | # This is a list of up to five keywords that describe this crate. Keywords | |
162 | # are searchable on crates.io, and you may choose any words that would | |
163 | # help someone find this crate. | |
164 | keywords = ["...", "..."] | |
165 | ||
166 | # This is a list of up to five categories where this crate would fit. | |
167 | # Categories are a fixed list available at crates.io/category_slugs, and | |
168 | # they must match exactly. | |
169 | categories = ["...", "..."] | |
170 | ||
7dee65fe TK |
171 | # This is an SPDX 2.1 license expression for this package. Currently |
172 | # crates.io will validate the license provided against a whitelist of | |
173 | # known license and exception identifiers from the SPDX license list | |
c89dd645 | 174 | # 2.4. Parentheses are not currently supported. |
7dee65fe TK |
175 | # |
176 | # Multiple licenses can be separated with a `/`, although that usage | |
177 | # is deprecated. Instead, use a license expression with AND and OR | |
178 | # operators to get more explicit semantics. | |
4d590f95 BE |
179 | license = "..." |
180 | ||
181 | # If a project is using a nonstandard license, then this key may be specified in | |
182 | # lieu of the above key and must point to a file relative to this manifest | |
183 | # (similar to the readme key). | |
184 | license-file = "..." | |
185 | ||
ec9fbd0d DB |
186 | # Optional specification of badges to be displayed on crates.io. |
187 | # | |
188 | # - The badges pertaining to build status that are currently available are | |
189 | # Appveyor, CircleCI, GitLab, and TravisCI. | |
190 | # - Available badges pertaining to code test coverage are Codecov and | |
191 | # Coveralls. | |
50d210c0 | 192 | # - There are also maintenance-related badges based on isitmaintained.com |
ec9fbd0d DB |
193 | # which state the issue resolution time, percent of open issues, and future |
194 | # maintenance intentions. | |
6d269548 | 195 | # |
94114d5d | 196 | # If a `repository` key is required, this refers to a repository in |
6d269548 | 197 | # `user/repo` format. |
4d590f95 | 198 | [badges] |
917c3634 | 199 | |
4d590f95 BE |
200 | # Appveyor: `repository` is required. `branch` is optional; default is `master` |
201 | # `service` is optional; valid values are `github` (default), `bitbucket`, and | |
bfb72c57 | 202 | # `gitlab`; `id` is optional; you can specify the appveyor project id if you |
ea42706d PM |
203 | # want to use that instead. `project_name` is optional; use when the repository |
204 | # name differs from the appveyor project name. | |
4d590f95 | 205 | appveyor = { repository = "...", branch = "master", service = "github" } |
917c3634 | 206 | |
1da7d17b | 207 | # Circle CI: `repository` is required. `branch` is optional; default is `master` |
917c3634 BE |
208 | circle-ci = { repository = "...", branch = "master" } |
209 | ||
4d590f95 BE |
210 | # GitLab: `repository` is required. `branch` is optional; default is `master` |
211 | gitlab = { repository = "...", branch = "master" } | |
917c3634 BE |
212 | |
213 | # Travis CI: `repository` in format "<user>/<project>" is required. | |
214 | # `branch` is optional; default is `master` | |
215 | travis-ci = { repository = "...", branch = "master" } | |
216 | ||
4d590f95 BE |
217 | # Codecov: `repository` is required. `branch` is optional; default is `master` |
218 | # `service` is optional; valid values are `github` (default), `bitbucket`, and | |
219 | # `gitlab`. | |
220 | codecov = { repository = "...", branch = "master", service = "github" } | |
917c3634 | 221 | |
4d590f95 BE |
222 | # Coveralls: `repository` is required. `branch` is optional; default is `master` |
223 | # `service` is optional; valid values are `github` (default) and `bitbucket`. | |
224 | coveralls = { repository = "...", branch = "master", service = "github" } | |
917c3634 BE |
225 | |
226 | # Is it maintained resolution time: `repository` is required. | |
227 | is-it-maintained-issue-resolution = { repository = "..." } | |
228 | ||
229 | # Is it maintained percentage of open issues: `repository` is required. | |
230 | is-it-maintained-open-issues = { repository = "..." } | |
231 | ||
232 | # Maintenance: `status` is required Available options are `actively-developed`, | |
233 | # `passively-maintained`, `as-is`, `none`, `experimental`, `looking-for-maintainer` | |
234 | # and `deprecated`. | |
235 | maintenance = { status = "..." } | |
4d590f95 BE |
236 | ``` |
237 | ||
238 | The [crates.io](https://crates.io) registry will render the description, display | |
239 | the license, link to the three URLs and categorize by the keywords. These keys | |
240 | provide useful information to users of the registry and also influence the | |
241 | search ranking of a crate. It is highly discouraged to omit everything in a | |
242 | published crate. | |
243 | ||
7dee65fe TK |
244 | SPDX 2.1 license expressions are documented |
245 | [here][spdx-2.1-license-expressions]. The current version of the | |
246 | license list is available [here][spdx-license-list], and version 2.4 | |
247 | is available [here][spdx-license-list-2.4]. | |
248 | ||
4d590f95 BE |
249 | #### The `metadata` table (optional) |
250 | ||
251 | Cargo by default will warn about unused keys in `Cargo.toml` to assist in | |
252 | detecting typos and such. The `package.metadata` table, however, is completely | |
253 | ignored by Cargo and will not be warned about. This section can be used for | |
254 | tools which would like to store project configuration in `Cargo.toml`. For | |
255 | example: | |
256 | ||
257 | ```toml | |
258 | [package] | |
259 | name = "..." | |
260 | # ... | |
261 | ||
262 | # Metadata used when generating an Android APK, for example. | |
263 | [package.metadata.android] | |
264 | package-name = "my-awesome-android-app" | |
265 | assets = "path/to/static" | |
266 | ``` | |
267 | ||
268 | ### Dependency sections | |
269 | ||
3f2d93e3 | 270 | See the [specifying dependencies page](reference/specifying-dependencies.html) for |
4d590f95 BE |
271 | information on the `[dependencies]`, `[dev-dependencies]`, |
272 | `[build-dependencies]`, and target-specific `[target.*.dependencies]` sections. | |
273 | ||
274 | ### The `[profile.*]` sections | |
275 | ||
276 | Cargo supports custom configuration of how rustc is invoked through profiles at | |
277 | the top level. Any manifest may declare a profile, but only the top level | |
278 | project’s profiles are actually read. All dependencies’ profiles will be | |
279 | overridden. This is done so the top-level project has control over how its | |
280 | dependencies are compiled. | |
281 | ||
282 | There are five currently supported profile names, all of which have the same | |
283 | configuration available to them. Listed below is the configuration available, | |
284 | along with the defaults for each profile. | |
285 | ||
286 | ```toml | |
287 | # The development profile, used for `cargo build`. | |
288 | [profile.dev] | |
289 | opt-level = 0 # controls the `--opt-level` the compiler builds with. | |
290 | # 0-1 is good for debugging. 2 is well-optimized. Max is 3. | |
291 | debug = true # include debug information (debug symbols). Equivalent to | |
292 | # `-C debuginfo=2` compiler flag. | |
293 | rpath = false # controls whether compiler should set loader paths. | |
294 | # If true, passes `-C rpath` flag to the compiler. | |
295 | lto = false # Link Time Optimization usually reduces size of binaries | |
296 | # and static libraries. Increases compilation time. | |
077feed5 AC |
297 | # If true, passes `-C lto` flag to the compiler, and if a |
298 | # string is specified like 'thin' then `-C lto=thin` will | |
e74ff4db | 299 | # be passed. |
4d590f95 BE |
300 | debug-assertions = true # controls whether debug assertions are enabled |
301 | # (e.g. debug_assert!() and arithmetic overflow checks) | |
0c46ede7 | 302 | codegen-units = 16 # if > 1 enables parallel code generation which improves |
4d590f95 | 303 | # compile times, but prevents some optimizations. |
50d210c0 | 304 | # Passes `-C codegen-units`. |
4d590f95 | 305 | panic = 'unwind' # panic strategy (`-C panic=...`), can also be 'abort' |
e0b4c582 | 306 | incremental = true # whether or not incremental compilation is enabled |
c4d4012d EH |
307 | overflow-checks = true # use overflow checks for integer arithmetic. |
308 | # Passes the `-C overflow-checks=...` flag to the compiler. | |
4d590f95 BE |
309 | |
310 | # The release profile, used for `cargo build --release`. | |
311 | [profile.release] | |
312 | opt-level = 3 | |
313 | debug = false | |
314 | rpath = false | |
e5539627 | 315 | lto = false |
4d590f95 | 316 | debug-assertions = false |
0c46ede7 | 317 | codegen-units = 16 |
4d590f95 | 318 | panic = 'unwind' |
e0b4c582 | 319 | incremental = false |
c4d4012d | 320 | overflow-checks = false |
4d590f95 BE |
321 | |
322 | # The testing profile, used for `cargo test`. | |
323 | [profile.test] | |
324 | opt-level = 0 | |
325 | debug = 2 | |
326 | rpath = false | |
327 | lto = false | |
328 | debug-assertions = true | |
0c46ede7 | 329 | codegen-units = 16 |
4d590f95 | 330 | panic = 'unwind' |
e0b4c582 | 331 | incremental = true |
c4d4012d | 332 | overflow-checks = true |
4d590f95 | 333 | |
4b8249f0 | 334 | # The benchmarking profile, used for `cargo bench` and `cargo test --release`. |
4d590f95 BE |
335 | [profile.bench] |
336 | opt-level = 3 | |
337 | debug = false | |
338 | rpath = false | |
e5539627 | 339 | lto = false |
4d590f95 | 340 | debug-assertions = false |
0c46ede7 | 341 | codegen-units = 16 |
4d590f95 | 342 | panic = 'unwind' |
e0b4c582 | 343 | incremental = false |
c4d4012d | 344 | overflow-checks = false |
4d590f95 BE |
345 | |
346 | # The documentation profile, used for `cargo doc`. | |
347 | [profile.doc] | |
348 | opt-level = 0 | |
349 | debug = 2 | |
350 | rpath = false | |
351 | lto = false | |
352 | debug-assertions = true | |
0c46ede7 | 353 | codegen-units = 16 |
4d590f95 | 354 | panic = 'unwind' |
e0b4c582 | 355 | incremental = true |
c4d4012d | 356 | overflow-checks = true |
4d590f95 BE |
357 | ``` |
358 | ||
359 | ### The `[features]` section | |
360 | ||
361 | Cargo supports features to allow expression of: | |
362 | ||
363 | * conditional compilation options (usable through `cfg` attributes); | |
364 | * optional dependencies, which enhance a package, but are not required; and | |
365 | * clusters of optional dependencies, such as `postgres`, that would include the | |
366 | `postgres` package, the `postgres-macros` package, and possibly other packages | |
367 | (such as development-time mocking libraries, debugging tools, etc.). | |
368 | ||
369 | A feature of a package is either an optional dependency, or a set of other | |
370 | features. The format for specifying features is: | |
371 | ||
372 | ```toml | |
373 | [package] | |
374 | name = "awesome" | |
375 | ||
376 | [features] | |
377 | # The default set of optional packages. Most people will want to use these | |
378 | # packages, but they are strictly optional. Note that `session` is not a package | |
379 | # but rather another feature listed in this manifest. | |
380 | default = ["jquery", "uglifier", "session"] | |
381 | ||
382 | # A feature with no dependencies is used mainly for conditional compilation, | |
383 | # like `#[cfg(feature = "go-faster")]`. | |
384 | go-faster = [] | |
385 | ||
386 | # The `secure-password` feature depends on the bcrypt package. This aliasing | |
387 | # will allow people to talk about the feature in a higher-level way and allow | |
388 | # this package to add more requirements to the feature in the future. | |
389 | secure-password = ["bcrypt"] | |
390 | ||
391 | # Features can be used to reexport features of other packages. The `session` | |
392 | # feature of package `awesome` will ensure that the `session` feature of the | |
393 | # package `cookie` is also enabled. | |
394 | session = ["cookie/session"] | |
395 | ||
396 | [dependencies] | |
397 | # These packages are mandatory and form the core of this package’s distribution. | |
398 | cookie = "1.2.0" | |
399 | oauth = "1.1.0" | |
400 | route-recognizer = "=2.1.0" | |
401 | ||
402 | # A list of all of the optional dependencies, some of which are included in the | |
403 | # above `features`. They can be opted into by apps. | |
404 | jquery = { version = "1.0.2", optional = true } | |
405 | uglifier = { version = "1.5.3", optional = true } | |
406 | bcrypt = { version = "*", optional = true } | |
407 | civet = { version = "*", optional = true } | |
408 | ``` | |
409 | ||
410 | To use the package `awesome`: | |
411 | ||
412 | ```toml | |
413 | [dependencies.awesome] | |
414 | version = "1.3.5" | |
415 | default-features = false # do not include the default features, and optionally | |
416 | # cherry-pick individual features | |
417 | features = ["secure-password", "civet"] | |
418 | ``` | |
419 | ||
420 | #### Rules | |
421 | ||
422 | The usage of features is subject to a few rules: | |
423 | ||
424 | * Feature names must not conflict with other package names in the manifest. This | |
425 | is because they are opted into via `features = [...]`, which only has a single | |
426 | namespace. | |
427 | * With the exception of the `default` feature, all features are opt-in. To opt | |
428 | out of the default feature, use `default-features = false` and cherry-pick | |
429 | individual features. | |
430 | * Feature groups are not allowed to cyclically depend on one another. | |
431 | * Dev-dependencies cannot be optional. | |
432 | * Features groups can only reference optional dependencies. | |
433 | * When a feature is selected, Cargo will call `rustc` with `--cfg | |
434 | feature="${feature_name}"`. If a feature group is included, it and all of its | |
435 | individual features will be included. This can be tested in code via | |
436 | `#[cfg(feature = "foo")]`. | |
437 | ||
438 | Note that it is explicitly allowed for features to not actually activate any | |
439 | optional dependencies. This allows packages to internally enable/disable | |
440 | features without requiring a new dependency. | |
441 | ||
442 | #### Usage in end products | |
443 | ||
444 | One major use-case for this feature is specifying optional features in | |
445 | end-products. For example, the Servo project may want to include optional | |
446 | features that people can enable or disable when they build it. | |
447 | ||
448 | In that case, Servo will describe features in its `Cargo.toml` and they can be | |
449 | enabled using command-line flags: | |
450 | ||
bc489e25 | 451 | ```console |
4d590f95 BE |
452 | $ cargo build --release --features "shumway pdf" |
453 | ``` | |
454 | ||
455 | Default features could be excluded using `--no-default-features`. | |
456 | ||
457 | #### Usage in packages | |
458 | ||
459 | In most cases, the concept of *optional dependency* in a library is best | |
460 | expressed as a separate package that the top-level application depends on. | |
461 | ||
462 | However, high-level packages, like Iron or Piston, may want the ability to | |
463 | curate a number of packages for easy installation. The current Cargo system | |
464 | allows them to curate a number of mandatory dependencies into a single package | |
465 | for easy installation. | |
466 | ||
467 | In some cases, packages may want to provide additional curation for optional | |
468 | dependencies: | |
469 | ||
470 | * grouping a number of low-level optional dependencies together into a single | |
471 | high-level feature; | |
472 | * specifying packages that are recommended (or suggested) to be included by | |
473 | users of the package; and | |
474 | * including a feature (like `secure-password` in the motivating example) that | |
475 | will only work if an optional dependency is available, and would be difficult | |
476 | to implement as a separate package (for example, it may be overly difficult to | |
477 | design an IO package to be completely decoupled from OpenSSL, with opt-in via | |
478 | the inclusion of a separate package). | |
479 | ||
480 | In almost all cases, it is an antipattern to use these features outside of | |
481 | high-level packages that are designed for curation. If a feature is optional, it | |
482 | can almost certainly be expressed as a separate package. | |
483 | ||
484 | ### The `[workspace]` section | |
485 | ||
486 | Projects can define a workspace which is a set of crates that will all share the | |
487 | same `Cargo.lock` and output directory. The `[workspace]` table can be defined | |
488 | as: | |
489 | ||
490 | ```toml | |
491 | [workspace] | |
492 | ||
74b4d0ff PM |
493 | # Optional key, inferred from path dependencies if not present. |
494 | # Additional non-path dependencies that should be included must be given here. | |
495 | # In particular, for a virtual manifest, all members have to be listed. | |
4d590f95 BE |
496 | members = ["path/to/member1", "path/to/member2", "path/to/member3/*"] |
497 | ||
74b4d0ff | 498 | # Optional key, empty if not present. |
4d590f95 BE |
499 | exclude = ["path1", "path/to/dir2"] |
500 | ``` | |
501 | ||
917c3634 | 502 | Workspaces were added to Cargo as part of [RFC 1525] and have a number of |
4d590f95 BE |
503 | properties: |
504 | ||
917c3634 BE |
505 | * A workspace can contain multiple crates where one of them is the *root crate*. |
506 | * The *root crate*'s `Cargo.toml` contains the `[workspace]` table, but is not | |
4d590f95 | 507 | required to have other configuration. |
917c3634 BE |
508 | * Whenever any crate in the workspace is compiled, output is placed in the |
509 | *workspace root*. i.e. next to the *root crate*'s `Cargo.toml`. | |
510 | * The lock file for all crates in the workspace resides in the *workspace root*. | |
2896e3f1 | 511 | * The `[patch]`, `[replace]` and `[profile.*]` sections in `Cargo.toml` |
512 | are only recognized | |
917c3634 | 513 | in the *root crate*'s manifest, and ignored in member crates' manifests. |
4d590f95 BE |
514 | |
515 | [RFC 1525]: https://github.com/rust-lang/rfcs/blob/master/text/1525-cargo-workspace.md | |
516 | ||
917c3634 BE |
517 | The *root crate* of a workspace, indicated by the presence of `[workspace]` in |
518 | its manifest, is responsible for defining the entire workspace. All `path` | |
4d590f95 BE |
519 | dependencies residing in the workspace directory become members. You can add |
520 | additional packages to the workspace by listing them in the `members` key. Note | |
521 | that members of the workspaces listed explicitly will also have their path | |
522 | dependencies included in the workspace. Sometimes a project may have a lot of | |
523 | workspace members and it can be onerous to keep up to date. The path dependency | |
524 | can also use [globs][globs] to match multiple paths. Finally, the `exclude` | |
525 | key can be used to blacklist paths from being included in a workspace. This can | |
526 | be useful if some path dependencies aren't desired to be in the workspace at | |
527 | all. | |
528 | ||
529 | The `package.workspace` manifest key (described above) is used in member crates | |
530 | to point at a workspace's root crate. If this key is omitted then it is inferred | |
531 | to be the first crate whose manifest contains `[workspace]` upwards in the | |
532 | filesystem. | |
533 | ||
534 | A crate may either specify `package.workspace` or specify `[workspace]`. That | |
535 | is, a crate cannot both be a root crate in a workspace (contain `[workspace]`) | |
536 | and also be a member crate of another workspace (contain `package.workspace`). | |
537 | ||
538 | Most of the time workspaces will not need to be dealt with as `cargo new` and | |
539 | `cargo init` will handle workspace configuration automatically. | |
540 | ||
917c3634 BE |
541 | #### Virtual Manifest |
542 | ||
543 | In workspace manifests, if the `package` table is present, the workspace root | |
06a6a40a | 544 | crate will be treated as a normal package, as well as a workspace. If the |
545 | `package` table is not present in a workspace manifest, it is called a *virtual | |
917c3634 BE |
546 | manifest*. |
547 | ||
27d4195d PM |
548 | #### Package selection |
549 | ||
550 | In a workspace, package-related cargo commands like `cargo build` apply to | |
551 | packages selected by `-p` / `--package` or `--all` command-line parameters. | |
552 | When neither is specified, the optional `default-members` configuration is used: | |
48b87407 PM |
553 | |
554 | ```toml | |
555 | [workspace] | |
556 | members = ["path/to/member1", "path/to/member2", "path/to/member3/*"] | |
27d4195d | 557 | default-members = ["path/to/member2", "path/to/member3/foo"] |
48b87407 | 558 | ``` |
917c3634 | 559 | |
27d4195d PM |
560 | When specified, `default-members` must expand to a subset of `members`. |
561 | ||
562 | When `default-members` is not specified, the default is the root manifest | |
563 | if it is a package, or every member manifest (as if `--all` were specified | |
564 | on the command-line) for virtual workspaces. | |
917c3634 | 565 | |
4d590f95 BE |
566 | #TODO: move this to a more appropriate place |
567 | ### The project layout | |
568 | ||
569 | If your project is an executable, name the main source file `src/main.rs`. If it | |
570 | is a library, name the main source file `src/lib.rs`. | |
571 | ||
572 | Cargo will also treat any files located in `src/bin/*.rs` as executables. If your | |
573 | executable consists of more than just one source file, you might also use a directory | |
574 | inside `src/bin` containing a `main.rs` file which will be treated as an executable | |
575 | with a name of the parent directory. | |
576 | Do note, however, once you add a `[[bin]]` section ([see | |
577 | below](#configuring-a-target)), Cargo will no longer automatically build files | |
578 | located in `src/bin/*.rs`. Instead you must create a `[[bin]]` section for | |
579 | each file you want to build. | |
580 | ||
581 | Your project can optionally contain folders named `examples`, `tests`, and | |
582 | `benches`, which Cargo will treat as containing examples, | |
999cba15 PM |
583 | integration tests, and benchmarks respectively. Analogous to `bin` targets, they |
584 | may be composed of single files or directories with a `main.rs` file. | |
4d590f95 | 585 | |
bc489e25 | 586 | ``` |
4d590f95 BE |
587 | ▾ src/ # directory containing source files |
588 | lib.rs # the main entry point for libraries and packages | |
589 | main.rs # the main entry point for projects producing executables | |
590 | ▾ bin/ # (optional) directory containing additional executables | |
591 | *.rs | |
592 | ▾ */ # (optional) directories containing multi-file executables | |
593 | main.rs | |
594 | ▾ examples/ # (optional) examples | |
595 | *.rs | |
999cba15 PM |
596 | ▾ */ # (optional) directories containing multi-file examples |
597 | main.rs | |
4d590f95 BE |
598 | ▾ tests/ # (optional) integration tests |
599 | *.rs | |
999cba15 PM |
600 | ▾ */ # (optional) directories containing multi-file tests |
601 | main.rs | |
4d590f95 BE |
602 | ▾ benches/ # (optional) benchmarks |
603 | *.rs | |
999cba15 PM |
604 | ▾ */ # (optional) directories containing multi-file benchmarks |
605 | main.rs | |
4d590f95 BE |
606 | ``` |
607 | ||
608 | To structure your code after you've created the files and folders for your | |
609 | project, you should remember to use Rust's module system, which you can read | |
610 | about in [the book](https://doc.rust-lang.org/book/crates-and-modules.html). | |
611 | ||
612 | ### Examples | |
613 | ||
614 | Files located under `examples` are example uses of the functionality provided by | |
615 | the library. When compiled, they are placed in the `target/examples` directory. | |
616 | ||
617 | They can compile either as executables (with a `main()` function) or libraries | |
618 | and pull in the library by using `extern crate <library-name>`. They are | |
619 | compiled when you run your tests to protect them from bitrotting. | |
620 | ||
621 | You can run individual executable examples with the command `cargo run --example | |
622 | <example-name>`. | |
623 | ||
c4d4012d EH |
624 | Specify `crate-type` to make an example be compiled as a library (additional |
625 | information about crate types is available in | |
fd4f8410 | 626 | [the Cargo reference](https://doc.rust-lang.org/reference/linkage.html)): |
4d590f95 BE |
627 | |
628 | ```toml | |
629 | [[example]] | |
630 | name = "foo" | |
631 | crate-type = ["staticlib"] | |
632 | ``` | |
633 | ||
634 | You can build individual library examples with the command `cargo build | |
635 | --example <example-name>`. | |
636 | ||
637 | ### Tests | |
638 | ||
639 | When you run `cargo test`, Cargo will: | |
640 | ||
641 | * compile and run your library’s unit tests, which are in the files reachable | |
642 | from `lib.rs` (naturally, any sections marked with `#[cfg(test)]` will be | |
643 | considered at this stage); | |
644 | * compile and run your library’s documentation tests, which are embedded inside | |
645 | of documentation blocks; | |
646 | * compile and run your library’s [integration tests](#integration-tests); and | |
647 | * compile your library’s examples. | |
648 | ||
649 | #### Integration tests | |
650 | ||
651 | Each file in `tests/*.rs` is an integration test. When you run `cargo test`, | |
652 | Cargo will compile each of these files as a separate crate. The crate can link | |
653 | to your library by using `extern crate <library-name>`, like any other code that | |
654 | depends on it. | |
655 | ||
656 | Cargo will not automatically compile files inside subdirectories of `tests`, but | |
657 | an integration test can import modules from these directories as usual. For | |
658 | example, if you want several integration tests to share some code, you can put | |
659 | the shared code in `tests/common/mod.rs` and then put `mod common;` in each of | |
660 | the test files. | |
661 | ||
662 | ### Configuring a target | |
663 | ||
664 | All of the `[[bin]]`, `[lib]`, `[[bench]]`, `[[test]]`, and `[[example]]` | |
665 | sections support similar configuration for specifying how a target should be | |
666 | built. The double-bracket sections like `[[bin]]` are array-of-table of | |
667 | [TOML](https://github.com/toml-lang/toml#array-of-tables), which means you can | |
668 | write more than one `[[bin]]` section to make several executables in your crate. | |
669 | ||
670 | The example below uses `[lib]`, but it also applies to all other sections | |
671 | as well. All values listed are the defaults for that option unless otherwise | |
672 | specified. | |
673 | ||
674 | ```toml | |
675 | [package] | |
676 | # ... | |
677 | ||
678 | [lib] | |
679 | # The name of a target is the name of the library that will be generated. This | |
680 | # is defaulted to the name of the package or project, with any dashes replaced | |
681 | # with underscores. (Rust `extern crate` declarations reference this name; | |
682 | # therefore the value must be a valid Rust identifier to be usable.) | |
683 | name = "foo" | |
684 | ||
685 | # This field points at where the crate is located, relative to the `Cargo.toml`. | |
686 | path = "src/lib.rs" | |
687 | ||
688 | # A flag for enabling unit tests for this target. This is used by `cargo test`. | |
689 | test = true | |
690 | ||
691 | # A flag for enabling documentation tests for this target. This is only relevant | |
692 | # for libraries, it has no effect on other sections. This is used by | |
693 | # `cargo test`. | |
694 | doctest = true | |
695 | ||
696 | # A flag for enabling benchmarks for this target. This is used by `cargo bench`. | |
697 | bench = true | |
698 | ||
699 | # A flag for enabling documentation of this target. This is used by `cargo doc`. | |
700 | doc = true | |
701 | ||
702 | # If the target is meant to be a compiler plugin, this field must be set to true | |
703 | # for Cargo to correctly compile it and make it available for all dependencies. | |
704 | plugin = false | |
705 | ||
706 | # If the target is meant to be a "macros 1.1" procedural macro, this field must | |
707 | # be set to true. | |
708 | proc-macro = false | |
709 | ||
710 | # If set to false, `cargo test` will omit the `--test` flag to rustc, which | |
711 | # stops it from generating a test harness. This is useful when the binary being | |
712 | # built manages the test runner itself. | |
713 | harness = true | |
714 | ``` | |
715 | ||
716 | #### The `required-features` field (optional) | |
717 | ||
718 | The `required-features` field specifies which features the target needs in order | |
719 | to be built. If any of the required features are not selected, the target will | |
720 | be skipped. This is only relevant for the `[[bin]]`, `[[bench]]`, `[[test]]`, | |
721 | and `[[example]]` sections, it has no effect on `[lib]`. | |
722 | ||
723 | ```toml | |
724 | [features] | |
725 | # ... | |
726 | postgres = [] | |
727 | sqlite = [] | |
728 | tools = [] | |
729 | ||
730 | [[bin]] | |
731 | # ... | |
732 | required-features = ["postgres", "tools"] | |
733 | ``` | |
734 | ||
735 | #### Building dynamic or static libraries | |
736 | ||
737 | If your project produces a library, you can specify which kind of library to | |
738 | build by explicitly listing the library in your `Cargo.toml`: | |
739 | ||
740 | ```toml | |
741 | # ... | |
742 | ||
743 | [lib] | |
744 | name = "..." | |
745 | crate-type = ["dylib"] # could be `staticlib` as well | |
746 | ``` | |
747 | ||
748 | The available options are `dylib`, `rlib`, `staticlib`, `cdylib`, and | |
749 | `proc-macro`. You should only use this option in a project. Cargo will always | |
750 | compile packages (dependencies) based on the requirements of the project that | |
751 | includes them. | |
752 | ||
753 | You can read more about the different crate types in the | |
754 | [Rust Reference Manual](https://doc.rust-lang.org/reference/linkage.html) | |
755 | ||
756 | ### The `[patch]` Section | |
757 | ||
758 | This section of Cargo.toml can be used to [override dependencies][replace] with | |
759 | other copies. The syntax is similar to the `[dependencies]` section: | |
760 | ||
761 | ```toml | |
762 | [patch.crates-io] | |
763 | foo = { git = 'https://github.com/example/foo' } | |
764 | bar = { path = 'my/local/bar' } | |
97555df8 PM |
765 | |
766 | [dependencies.baz] | |
767 | git = 'https://github.com/example/baz' | |
768 | ||
769 | [patch.'https://github.com/example/baz'] | |
97584002 | 770 | baz = { git = 'https://github.com/example/patched-baz', branch = 'my-branch' } |
4d590f95 BE |
771 | ``` |
772 | ||
773 | The `[patch]` table is made of dependency-like sub-tables. Each key after | |
774 | `[patch]` is a URL of the source that's being patched, or `crates-io` if | |
775 | you're modifying the https://crates.io registry. In the example above | |
776 | `crates-io` could be replaced with a git URL such as | |
97555df8 PM |
777 | `https://github.com/rust-lang-nursery/log`; the second `[patch]` |
778 | section in the example uses this to specify a source called `baz`. | |
4d590f95 BE |
779 | |
780 | Each entry in these tables is a normal dependency specification, the same as | |
781 | found in the `[dependencies]` section of the manifest. The dependencies listed | |
782 | in the `[patch]` section are resolved and used to patch the source at the | |
783 | URL specified. The above manifest snippet patches the `crates-io` source (e.g. | |
97555df8 PM |
784 | crates.io itself) with the `foo` crate and `bar` crate. It also |
785 | patches the `https://github.com/example/baz` source with a `my-branch` that | |
786 | comes from elsewhere. | |
4d590f95 BE |
787 | |
788 | Sources can be patched with versions of crates that do not exist, and they can | |
789 | also be patched with versions of crates that already exist. If a source is | |
790 | patched with a crate version that already exists in the source, then the | |
791 | source's original crate is replaced. | |
792 | ||
793 | More information about overriding dependencies can be found in the [overriding | |
794 | dependencies][replace] section of the documentation and [RFC 1969] for the | |
2c00108d | 795 | technical specification of this feature. |
4d590f95 BE |
796 | |
797 | [RFC 1969]: https://github.com/rust-lang/rfcs/pull/1969 | |
3f2d93e3 | 798 | [replace]: reference/specifying-dependencies.html#overriding-dependencies |
4d590f95 BE |
799 | |
800 | ### The `[replace]` Section | |
801 | ||
802 | This section of Cargo.toml can be used to [override dependencies][replace] with | |
803 | other copies. The syntax is similar to the `[dependencies]` section: | |
804 | ||
805 | ```toml | |
806 | [replace] | |
807 | "foo:0.1.0" = { git = 'https://github.com/example/foo' } | |
808 | "bar:1.0.2" = { path = 'my/local/bar' } | |
809 | ``` | |
810 | ||
811 | Each key in the `[replace]` table is a [package id | |
3f2d93e3 | 812 | specification](reference/pkgid-spec.html) which allows arbitrarily choosing a node in the |
4d590f95 BE |
813 | dependency graph to override. The value of each key is the same as the |
814 | `[dependencies]` syntax for specifying dependencies, except that you can't | |
815 | specify features. Note that when a crate is overridden the copy it's overridden | |
816 | with must have both the same name and version, but it can come from a different | |
817 | source (e.g. git or a local path). | |
818 | ||
819 | More information about overriding dependencies can be found in the [overriding | |
820 | dependencies][replace] section of the documentation. | |
7dee65fe TK |
821 | |
822 | [spdx-2.1-license-expressions]: https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60 | |
823 | [spdx-license-list]: https://spdx.org/licenses/ | |
824 | [spdx-license-list-2.4]: https://github.com/spdx/license-list-data/tree/v2.4 |