Workspace in cargo::core::workspace - Rust
Description: The core abstraction in Cargo for working with a workspace of crates.

Skip to main content

## Workspace

# Struct Workspace

Source

    pub struct Workspace<'gctx> {Show 20 fields
        gctx: &'gctx GlobalContext,
        current_manifest: PathBuf,
        packages: Packages<'gctx>,
        root_manifest: Option<PathBuf>,
        target_dir: Option<Filesystem>,
        build_dir: Option<Filesystem>,
        members: Vec<PathBuf>,
        member_ids: HashSet<PackageId>,
        default_members: Vec<PathBuf>,
        is_ephemeral: bool,
        require_optional_deps: bool,
        loaded_packages: RefCell<HashMap<PathBuf, Package>>,
        ignore_lock: bool,
        requested_lockfile_path: Option<PathBuf>,
        resolve_behavior: ResolveBehavior,
        resolve_honors_rust_version: bool,
        resolve_feature_unification: FeatureUnification,
        resolve_publish_time: Option<Timestamp>,
        custom_metadata: Option<Value>,
        local_overlays: HashMap<SourceId, PathBuf>,
    }

Expand description

The core abstraction in Cargo for working with a workspace of crates.

A workspace is often created very early on and then threaded through all other functions. It’s typically through this object that the current package is loaded and/or learned about.

## Fields§

§`gctx: &'gctx GlobalContext`

Cargo configuration information. See `GlobalContext`.

§`current_manifest: PathBuf`

This path is a path to where the current cargo subcommand was invoked from. That is the `--manifest-path` argument to Cargo, and points to the “main crate” that we’re going to worry about.

§`packages: Packages<'gctx>`

A list of packages found in this workspace. Always includes at least the package mentioned by `current_manifest`.

§`root_manifest: Option<PathBuf>`

If this workspace includes more than one crate, this points to the root of the workspace. This is `None` in the case that `[workspace]` is missing, `package.workspace` is missing, and no `Cargo.toml` above `current_manifest` was found on the filesystem with `[workspace]`.

§`target_dir: Option<Filesystem>`

Shared target directory for all the packages of this workspace. `None` if the default path of `root/target` should be used.

§`build_dir: Option<Filesystem>`

Shared build directory for intermediate build artifacts. This directory may be shared between multiple workspaces.

§`members: Vec<PathBuf>`

List of members in this workspace with a listing of all their manifest paths. The packages themselves can be looked up through the `packages` set above.

§`member_ids: HashSet<PackageId>`

Set of ids of workspace members

§`default_members: Vec<PathBuf>`

The subset of `members` that are used by the `build`, `check`, `test`, and `bench` subcommands when no package is selected with `--package` / `-p` and `--workspace` is not used.

This is set by the `default-members` config in the `[workspace]` section. When unset, this is the same as `members` for virtual workspaces (`--workspace` is implied) or only the root package for non-virtual workspaces.

§`is_ephemeral: bool`

`true` if this is a temporary workspace created for the purposes of the `cargo install` or `cargo package` commands.

§`require_optional_deps: bool`

`true` if this workspace should enforce optional dependencies even when not needed; false if this workspace should only enforce dependencies needed by the current configuration (such as in cargo install). In some cases `false` also results in the non-enforcement of dev-dependencies.

§`loaded_packages: RefCell<HashMap<PathBuf, Package>>`

A cache of loaded packages for particular paths which is disjoint from `packages` up above, used in the `load` method down below.

§`ignore_lock: bool`

If `true`, then the resolver will ignore any existing `Cargo.lock` file. This is set for `cargo install` without `--locked`.

§`requested_lockfile_path: Option<PathBuf>`

Requested path of the lockfile (i.e. passed as the cli flag)

§`resolve_behavior: ResolveBehavior`

The resolver behavior specified with the `resolver` field.

§`resolve_honors_rust_version: bool`

If `true`, then workspace `rust_version` would be used in `cargo resolve` and other places that use rust version. This is set based on the resolver version, config settings, and CLI flags.

§`resolve_feature_unification: FeatureUnification`

The feature unification mode used when building packages.

§`resolve_publish_time: Option<Timestamp>`

Latest publish time allowed for packages

§`custom_metadata: Option<Value>`

Workspace-level custom metadata

§`local_overlays: HashMap<SourceId, PathBuf>`

Local overlay configuration. See `crate::sources::overlay`.

## Implementations§

Source§

### impl<'gctx> Workspace<'gctx>

Source

#### pub fn new( manifest_path: &Path, gctx: &'gctx GlobalContext, ) -> CargoResult<Workspace<'gctx>>

Creates a new workspace given the target manifest pointed to by `manifest_path`.

This function will construct the entire workspace by determining the root and all member packages. It will then validate the workspace before returning it, so `Ok` is only returned for valid workspaces.

Source

#### fn new_default( current_manifest: PathBuf, gctx: &'gctx GlobalContext, ) -> Workspace<'gctx>

Source

#### pub fn ephemeral( package: Package, gctx: &'gctx GlobalContext, target_dir: Option<Filesystem>, require_optional_deps: bool, ) -> CargoResult<Workspace<'gctx>>

Creates a “temporary workspace” from one package which only contains that package.

This constructor will not touch the filesystem and only creates an in-memory workspace. That is, all configuration is ignored, it’s just intended for that one package.

This is currently only used in niche situations like `cargo install` or `cargo package`.

Source

#### pub fn reload( &self, gctx: &'gctx GlobalContext, ) -> CargoResult<Workspace<'gctx>>

Reloads the workspace.

This is useful if the workspace has been updated, such as with `cargo fix` modifying the `Cargo.toml` file.

Source

#### fn set_resolve_behavior(&mut self) -> CargoResult<()>

Source

#### pub fn current(&self) -> CargoResult<&Package>

Returns the current package of this workspace.

Note that this can return an error if it the current manifest is actually a “virtual Cargo.toml”, in which case an error is returned indicating that something else should be passed.

Source

#### pub fn current_mut(&mut self) -> CargoResult<&mut Package>

Source

#### pub fn current_opt(&self) -> Option<&Package>

Source

#### pub fn current_opt_mut(&mut self) -> Option<&mut Package>

Source

#### pub fn is_virtual(&self) -> bool

Source

#### pub fn gctx(&self) -> &'gctx GlobalContext

Returns the `GlobalContext` this workspace is associated with.

Source

#### pub fn profiles(&self) -> Option<&TomlProfiles>

Source

#### pub fn root(&self) -> &Path

Returns the root path of this workspace.

That is, this returns the path of the directory containing the `Cargo.toml` which is the root of this workspace.

Source

#### pub fn root_manifest(&self) -> &Path

Returns the path of the `Cargo.toml` which is the root of this workspace.

Source

#### pub fn root_maybe(&self) -> &MaybePackage

Returns the root Package or `VirtualManifest`.

Source

#### pub fn target_dir(&self) -> Filesystem

Source

#### pub fn build_dir(&self) -> Filesystem

Source

#### fn default_target_dir(&self) -> Filesystem

Source

#### fn default_build_dir(&self) -> Filesystem

Source

#### pub fn root_replace(&self) -> &[(PackageIdSpec, Dependency)]

Returns the root `[replace]` section of this workspace.

This may be from a virtual crate or an actual crate.

Source

#### fn config_patch(&self) -> CargoResult<HashMap<Url, Vec<Patch>>>

Source

#### pub fn root_patch(&self) -> CargoResult<HashMap<Url, Vec<Patch>>>

Returns the root `[patch]` section of this workspace.

This may be from a virtual crate or an actual crate.

Source

#### pub fn loaded_maybe(&self) -> impl Iterator<Item = &MaybePackage>

Returns an iterator over all loaded manifests

Source

#### pub fn members(&self) -> impl Iterator<Item = &Package>

Returns an iterator over all packages in this workspace

Source

#### pub fn members_mut(&mut self) -> impl Iterator<Item = &mut Package>

Returns a mutable iterator over all packages in this workspace

Source

#### pub fn default_members<'a>(&'a self) -> impl Iterator<Item = &'a Package>

Returns an iterator over default packages in this workspace

Source

#### pub fn default_members_mut(&mut self) -> impl Iterator<Item = &mut Package>

Returns an iterator over default packages in this workspace

Source

#### pub fn is_member(&self, pkg: &Package) -> bool

Returns true if the package is a member of the workspace.

Source

#### pub fn is_member_id(&self, package_id: PackageId) -> bool

Returns true if the given package_id is a member of the workspace.

Source

#### pub fn is_ephemeral(&self) -> bool

Source

#### pub fn require_optional_deps(&self) -> bool

Source

#### pub fn set_require_optional_deps( &mut self, require_optional_deps: bool, ) -> &mut Workspace<'gctx>

Source

#### pub fn ignore_lock(&self) -> bool

Source

#### pub fn set_ignore_lock(&mut self, ignore_lock: bool) -> &mut Workspace<'gctx>

Source

#### pub fn lock_root(&self) -> Filesystem

Returns the directory where the lockfile is in.

Source

#### fn default_lock_root(&self) -> Filesystem

Source

#### pub fn set_requested_lockfile_path(&mut self, path: Option<PathBuf>)

Source

#### pub fn requested_lockfile_path(&self) -> Option<&Path>

Source

#### pub fn lowest_rust_version(&self) -> Option<&RustVersion>

Get the lowest-common denominator `package.rust-version` within the workspace, if specified anywhere

Source

#### pub fn set_resolve_honors_rust_version( &mut self, honor_rust_version: Option<bool>, )

Source

#### pub fn resolve_honors_rust_version(&self) -> bool

Source

#### pub fn set_resolve_feature_unification( &mut self, feature_unification: FeatureUnification, )

Source

#### pub fn resolve_feature_unification(&self) -> FeatureUnification

Source

#### pub fn set_resolve_publish_time(&mut self, publish_time: Timestamp)

Source

#### pub fn resolve_publish_time(&self) -> Option<Timestamp>

Source

#### pub fn custom_metadata(&self) -> Option<&Value>

Source

#### pub fn load_workspace_config( &mut self, ) -> CargoResult<Option<WorkspaceRootConfig>>

Source

#### fn find_root(&mut self, manifest_path: &Path) -> CargoResult<Option<PathBuf>>

Finds the root of a workspace for the crate whose manifest is located at `manifest_path`.

This will parse the `Cargo.toml` at `manifest_path` and then interpret the workspace configuration, optionally walking up the filesystem looking for other workspace roots.

Returns an error if `manifest_path` isn’t actually a valid manifest or if some other transient error happens.

Source

#### fn find_members(&mut self) -> CargoResult<()>

After the root of a workspace has been located, probes for all members of a workspace.

If the `workspace.members` configuration is present, then this just verifies that those are all valid packages to point to. Otherwise, this will transitively follow all `path` dependencies looking for members of the workspace.

Source

#### fn find_path_deps( &mut self, manifest_path: &Path, root_manifest: &Path, is_path_dep: bool, ) -> CargoResult<()>

Source

#### pub fn unstable_features(&self) -> &Features

Returns the unstable nightly-only features enabled via `cargo-features` in the manifest.

Source

#### pub fn resolve_behavior(&self) -> ResolveBehavior

Source

#### pub fn allows_new_cli_feature_behavior(&self) -> bool

Returns `true` if this workspace uses the new CLI features behavior.

The old behavior only allowed choosing the features from the package in the current directory, regardless of which packages were chosen with the -p flags. The new behavior allows selecting features from the packages chosen on the command line (with -p or –workspace flags), ignoring whatever is in the current directory.

Source

#### fn validate(&mut self) -> CargoResult<()>

Validates a workspace, ensuring that a number of invariants are upheld:

1. A workspace only has one root.
2. All workspace members agree on this one root as the root.
3. The current crate is a member of this workspace.

Source

#### fn validate_unique_names(&self) -> CargoResult<()>

Source

#### fn validate_workspace_roots(&self) -> CargoResult<()>

Source

#### fn validate_members(&mut self) -> CargoResult<()>

Source

#### fn error_if_manifest_not_in_members(&mut self) -> CargoResult<()>

Source

#### fn validate_manifest(&mut self) -> CargoResult<()>

Source

#### pub fn load(&self, manifest_path: &Path) -> CargoResult<Package>

Source

#### pub fn preload(&self, registry: &mut PackageRegistry<'gctx>)

Preload the provided registry with already loaded packages.

A workspace may load packages during construction/parsing/early phases for various operations, and this preload step avoids doubly-loading and parsing crates on the filesystem by inserting them all into the registry with their in-memory formats.

Source

#### pub fn set_target_dir(&mut self, target_dir: Filesystem)

Source

#### pub fn members_with_features( &self, specs: &[PackageIdSpec], cli_features: &CliFeatures, ) -> CargoResult<Vec<(&Package, CliFeatures)>>

Returns a Vec of `(&Package, CliFeatures)` tuples that represent the workspace members that were requested on the command-line.

`specs` may be empty, which indicates it should return all workspace members. In this case, `requested_features.all_features` must be `true`. This is used for generating `Cargo.lock`, which must include all members with all features enabled.

Source

#### fn collect_matching_features( member: &Package, cli_features: &CliFeatures, found_features: &mut BTreeSet<FeatureValue>, ) -> CliFeatures

Returns the requested features for the given member. This filters out any named features that the member does not have.

Source

#### fn missing_feature_spelling_suggestions( &self, selected_members: &[&Package], cli_features: &CliFeatures, found_features: &BTreeSet<FeatureValue>, ) -> Vec<String>

Source

#### fn report_unknown_features_error( &self, specs: &[PackageIdSpec], cli_features: &CliFeatures, found_features: &BTreeSet<FeatureValue>, ) -> CargoResult<()>

Source

#### fn members_with_features_new( &self, specs: &[PackageIdSpec], cli_features: &CliFeatures, ) -> CargoResult<Vec<(&Package, CliFeatures)>>

New command-line feature selection behavior with resolver = “2” or the root of a virtual workspace. See `allows_new_cli_feature_behavior`.

Source

#### fn members_with_features_old( &self, specs: &[PackageIdSpec], cli_features: &CliFeatures, ) -> Vec<(&Package, CliFeatures)>

This is the “old” behavior for command-line feature selection. See `allows_new_cli_feature_behavior`.

Source

#### pub fn unit_needs_doc_scrape(&self, unit: &Unit) -> bool

Returns true if `unit` should depend on the output of Docscrape units.

Source

#### pub fn add_local_overlay(&mut self, id: SourceId, registry_path: PathBuf)

Adds a local package registry overlaying a `SourceId`.

See `crate::sources::overlay::DependencyConfusionThreatOverlaySource` for why you shouldn’t use this.

Source

#### pub fn package_registry(&self) -> CargoResult<PackageRegistry<'gctx>>

Builds a package registry that reflects this workspace configuration.

Source

#### fn local_overlays( &self, ) -> CargoResult<impl Iterator<Item = (SourceId, SourceId)>>

Returns all the configured local overlays, including the ones from our secret environment variable.

## Trait Implementations§

Source§

### impl<'gctx> Debug for Workspace<'gctx>

Source§

#### fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

## Auto Trait Implementations§

§

### impl<'gctx> !Freeze for Workspace<'gctx>

§

### impl<'gctx> !RefUnwindSafe for Workspace<'gctx>

§

### impl<'gctx> !Send for Workspace<'gctx>

§

### impl<'gctx> !Sync for Workspace<'gctx>

§

### impl<'gctx> Unpin for Workspace<'gctx>

§

### impl<'gctx> UnsafeUnpin for Workspace<'gctx>

§

### impl<'gctx> !UnwindSafe for Workspace<'gctx>

## Blanket Implementations§

Source§

### impl<T> Any for T
where T: 'static + ?Sized,

Source§

#### fn type_id(&self) -> TypeId

Gets the `TypeId` of `self`. Read more
Source§

### impl<T> Borrow<T> for T
where T: ?Sized,

Source§

#### fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

### impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

#### fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

### impl<T> From<T> for T

Source§

#### fn from(t: T) -> T

Returns the argument unchanged.

§

### impl<T> Instrument for T

§

#### fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided [`Span`], returning an `Instrumented` wrapper. Read more
§

#### fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current `Span`, returning an `Instrumented` wrapper. Read more
Source§

### impl<T, U> Into<U> for T
where U: From<T>,

Source§

#### fn into(self) -> U

Calls `U::from(self)`.

That is, this conversion is whatever the implementation of `From<T> for U` chooses to do.

Source§

### impl<T> IntoEither for T

Source§

#### fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts `self` into a `Left` variant of `Either<Self, Self>` if `into_left` is `true`. Converts `self` into a `Right` variant of `Either<Self, Self>` otherwise. Read more
Source§

#### fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts `self` into a `Left` variant of `Either<Self, Self>` if `into_left(&self)` returns `true`. Converts `self` into a `Right` variant of `Either<Self, Self>` otherwise. Read more
§

### impl<T> Pointable for T

§

#### const ALIGN: usize

The alignment of pointer.
§

#### type Init = T

The type for initializers.
§

#### unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
§

#### unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
§

#### unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
§

#### unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
Source§

### impl<T> Same for T

Source§

#### type Output = T

Should always be `Self`
Source§

### impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

#### type Error = Infallible

The type returned in the event of a conversion error.
Source§

#### fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

### impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

#### type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

#### fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

### impl<T> WithSubscriber for T

§

#### fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided `Subscriber` to this type, returning a [`WithDispatch`] wrapper. Read more
§

#### fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default `Subscriber` to this type, returning a [`WithDispatch`] wrapper. Read more

## Layout§

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain `repr(...)` attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: 496 bytes