1## Workspaces 2 3A *workspace* is a collection of one or more packages that share common 4dependency resolution (with a shared `Cargo.lock`), output directory, and 5various settings such as profiles. Packages that are part of a workspaces are 6called *workspace members*. There are two flavours of workspaces: as root 7package or as virtual manifest. 8 9### Root package 10 11A workspace can be created by adding a [`[workspace]` 12section](#the-workspace-section) to `Cargo.toml`. This can be added to a 13`Cargo.toml` that already defines a `[package]`, in which case the package is 14the *root package* of the workspace. The *workspace root* is the directory 15where the workspace's `Cargo.toml` is located. 16 17### Virtual manifest 18 19Alternatively, a `Cargo.toml` file can be created with a `[workspace]` section 20but without a [`[package]` section][package]. This is called a *virtual 21manifest*. This is typically useful when there isn't a "primary" package, or 22you want to keep all the packages organized in separate directories. 23 24### Key features 25 26The key points of workspaces are: 27 28* All packages share a common `Cargo.lock` file which resides in the 29 *workspace root*. 30* All packages share a common [output directory], which defaults to a 31 directory named `target` in the *workspace root*. 32* The [`[patch]`][patch], [`[replace]`][replace] and [`[profile.*]`][profiles] 33 sections in `Cargo.toml` are only recognized in the *root* manifest, and 34 ignored in member crates' manifests. 35 36### The `[workspace]` section 37 38The `[workspace]` table in `Cargo.toml` defines which packages are members of 39the workspace: 40 41```toml 42[workspace] 43members = ["member1", "path/to/member2", "crates/*"] 44exclude = ["crates/foo", "path/to/other"] 45``` 46 47All [`path` dependencies] residing in the workspace directory automatically 48become members. Additional members can be listed with the `members` key, which 49should be an array of strings containing directories with `Cargo.toml` files. 50 51The `members` list also supports [globs] to match multiple paths, using 52typical filename glob patterns like `*` and `?`. 53 54The `exclude` key can be used to prevent paths from being included in a 55workspace. This can be useful if some path dependencies aren't desired to be 56in the workspace at all, or using a glob pattern and you want to remove a 57directory. 58 59An empty `[workspace]` table can be used with a `[package]` to conveniently 60create a workspace with the package and all of its path dependencies. 61 62### Workspace selection 63 64When inside a subdirectory within the workspace, Cargo will automatically 65search the parent directories for a `Cargo.toml` file with a `[workspace]` 66definition to determine which workspace to use. The [`package.workspace`] 67manifest key can be used in member crates to point at a workspace's root to 68override this automatic search. The manual setting can be useful if the member 69is not inside a subdirectory of the workspace root. 70 71### Package selection 72 73In a workspace, package-related cargo commands like [`cargo build`] can use 74the `-p` / `--package` or `--workspace` command-line flags to determine which 75packages to operate on. If neither of those flags are specified, Cargo will 76use the package in the current working directory. If the current directory is 77a virtual workspace, it will apply to all members (as if `--workspace` were 78specified on the command-line). 79 80The optional `default-members` key can be specified to set the members to 81operate on when in the workspace root and the package selection flags are not 82used: 83 84```toml 85[workspace] 86members = ["path/to/member1", "path/to/member2", "path/to/member3/*"] 87default-members = ["path/to/member2", "path/to/member3/foo"] 88``` 89 90When specified, `default-members` must expand to a subset of `members`. 91 92### The `workspace.metadata` table 93 94The `workspace.metadata` table is ignored by Cargo and will not be warned 95about. This section can be used for tools that would like to store workspace 96configuration in `Cargo.toml`. For example: 97 98```toml 99[workspace] 100members = ["member1", "member2"] 101 102[workspace.metadata.webcontents] 103root = "path/to/webproject" 104tool = ["npm", "run", "build"] 105# ... 106``` 107 108There is a similar set of tables at the package level at 109[`package.metadata`][package-metadata]. While cargo does not specify a 110format for the content of either of these tables, it is suggested that 111external tools may wish to use them in a consistent fashion, such as referring 112to the data in `workspace.metadata` if data is missing from `package.metadata`, 113if that makes sense for the tool in question. 114 115[package]: manifest.md#the-package-section 116[package-metadata]: manifest.md#the-metadata-table 117[output directory]: ../guide/build-cache.md 118[patch]: overriding-dependencies.md#the-patch-section 119[replace]: overriding-dependencies.md#the-replace-section 120[profiles]: profiles.md 121[`path` dependencies]: specifying-dependencies.md#specifying-path-dependencies 122[`package.workspace`]: manifest.md#the-workspace-field 123[globs]: https://docs.rs/glob/0.3.0/glob/struct.Pattern.html 124[`cargo build`]: ../commands/cargo-build.md 125