pub struct Workspace<'gctx> {Show 17 fields
gctx: &'gctx GlobalContext,
current_manifest: PathBuf,
packages: Packages<'gctx>,
root_manifest: Option<PathBuf>,
target_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,
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.
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.
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>
impl<'gctx> Workspace<'gctx>
sourcepub fn new(
manifest_path: &Path,
gctx: &'gctx GlobalContext,
) -> CargoResult<Workspace<'gctx>>
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.
fn new_default( current_manifest: PathBuf, gctx: &'gctx GlobalContext, ) -> Workspace<'gctx>
sourcepub fn ephemeral(
package: Package,
gctx: &'gctx GlobalContext,
target_dir: Option<Filesystem>,
require_optional_deps: bool,
) -> CargoResult<Workspace<'gctx>>
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
.
fn set_resolve_behavior(&mut self) -> CargoResult<()>
sourcepub fn current(&self) -> CargoResult<&Package>
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.
pub fn current_mut(&mut self) -> CargoResult<&mut Package>
pub fn current_opt(&self) -> Option<&Package>
pub fn current_opt_mut(&mut self) -> Option<&mut Package>
pub fn is_virtual(&self) -> bool
sourcepub fn gctx(&self) -> &'gctx GlobalContext
pub fn gctx(&self) -> &'gctx GlobalContext
Returns the GlobalContext
this workspace is associated with.
pub fn profiles(&self) -> Option<&TomlProfiles>
sourcepub fn root(&self) -> &Path
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.
sourcepub fn root_manifest(&self) -> &Path
pub fn root_manifest(&self) -> &Path
Returns the path of the Cargo.toml
which is the root of this
workspace.
sourcepub fn root_maybe(&self) -> &MaybePackage
pub fn root_maybe(&self) -> &MaybePackage
Returns the root Package or VirtualManifest.
pub fn target_dir(&self) -> Filesystem
fn default_target_dir(&self) -> Filesystem
sourcepub fn root_replace(&self) -> &[(PackageIdSpec, Dependency)]
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.
fn config_patch(&self) -> CargoResult<HashMap<Url, Vec<Dependency>>>
sourcepub fn root_patch(&self) -> CargoResult<HashMap<Url, Vec<Dependency>>>
pub fn root_patch(&self) -> CargoResult<HashMap<Url, Vec<Dependency>>>
Returns the root [patch]
section of this workspace.
This may be from a virtual crate or an actual crate.
sourcepub fn members(&self) -> impl Iterator<Item = &Package>
pub fn members(&self) -> impl Iterator<Item = &Package>
Returns an iterator over all packages in this workspace
sourcepub fn members_mut(&mut self) -> impl Iterator<Item = &mut Package>
pub fn members_mut(&mut self) -> impl Iterator<Item = &mut Package>
Returns a mutable iterator over all packages in this workspace
sourcepub fn default_members<'a>(&'a self) -> impl Iterator<Item = &Package>
pub fn default_members<'a>(&'a self) -> impl Iterator<Item = &Package>
Returns an iterator over default packages in this workspace
sourcepub fn default_members_mut(&mut self) -> impl Iterator<Item = &mut Package>
pub fn default_members_mut(&mut self) -> impl Iterator<Item = &mut Package>
Returns an iterator over default packages in this workspace
sourcepub fn is_member(&self, pkg: &Package) -> bool
pub fn is_member(&self, pkg: &Package) -> bool
Returns true if the package is a member of the workspace.
pub fn is_ephemeral(&self) -> bool
pub fn require_optional_deps(&self) -> bool
pub fn set_require_optional_deps( &mut self, require_optional_deps: bool, ) -> &mut Workspace<'gctx>
pub fn ignore_lock(&self) -> bool
pub fn set_ignore_lock(&mut self, ignore_lock: bool) -> &mut Workspace<'gctx>
sourcepub fn lock_root(&self) -> Filesystem
pub fn lock_root(&self) -> Filesystem
Returns the directory where the lockfile is in.
fn default_lock_root(&self) -> Filesystem
pub fn set_requested_lockfile_path(&mut self, path: Option<PathBuf>)
sourcepub fn rust_version(&self) -> Option<&RustVersion>
pub fn rust_version(&self) -> Option<&RustVersion>
Get the lowest-common denominator package.rust-version
within the workspace, if specified
anywhere
pub fn set_resolve_honors_rust_version( &mut self, honor_rust_version: Option<bool>, )
pub fn resolve_honors_rust_version(&self) -> bool
pub fn custom_metadata(&self) -> Option<&Value>
pub fn load_workspace_config( &mut self, ) -> CargoResult<Option<WorkspaceRootConfig>>
sourcefn find_root(&mut self, manifest_path: &Path) -> CargoResult<Option<PathBuf>>
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.
sourcefn find_members(&mut self) -> CargoResult<()>
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.
fn find_path_deps( &mut self, manifest_path: &Path, root_manifest: &Path, is_path_dep: bool, ) -> CargoResult<()>
sourcepub fn unstable_features(&self) -> &Features
pub fn unstable_features(&self) -> &Features
Returns the unstable nightly-only features enabled via cargo-features
in the manifest.
pub fn resolve_behavior(&self) -> ResolveBehavior
sourcepub fn allows_new_cli_feature_behavior(&self) -> bool
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.
sourcefn validate(&mut self) -> CargoResult<()>
fn validate(&mut self) -> CargoResult<()>
Validates a workspace, ensuring that a number of invariants are upheld:
- A workspace only has one root.
- All workspace members agree on this one root as the root.
- The current crate is a member of this workspace.
fn validate_unique_names(&self) -> CargoResult<()>
fn validate_workspace_roots(&self) -> CargoResult<()>
fn validate_members(&mut self) -> CargoResult<()>
fn error_if_manifest_not_in_members(&mut self) -> CargoResult<()>
fn validate_manifest(&mut self) -> CargoResult<()>
pub fn load(&self, manifest_path: &Path) -> CargoResult<Package>
sourcepub fn preload(&self, registry: &mut PackageRegistry<'gctx>)
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.
pub fn emit_warnings(&self) -> CargoResult<()>
pub fn emit_lints(&self, pkg: &Package, path: &Path) -> CargoResult<()>
pub fn set_target_dir(&mut self, target_dir: Filesystem)
sourcepub fn members_with_features(
&self,
specs: &[PackageIdSpec],
cli_features: &CliFeatures,
) -> CargoResult<Vec<(&Package, CliFeatures)>>
pub fn members_with_features( &self, specs: &[PackageIdSpec], cli_features: &CliFeatures, ) -> CargoResult<Vec<(&Package, CliFeatures)>>
Returns a Vec of (&Package, RequestedFeatures)
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.
sourcefn collect_matching_features(
member: &Package,
cli_features: &CliFeatures,
found_features: &mut BTreeSet<FeatureValue>,
) -> CliFeatures
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.
fn report_unknown_features_error( &self, specs: &[PackageIdSpec], cli_features: &CliFeatures, found_features: &BTreeSet<FeatureValue>, ) -> CargoResult<()>
sourcefn members_with_features_new(
&self,
specs: &[PackageIdSpec],
cli_features: &CliFeatures,
) -> CargoResult<Vec<(&Package, CliFeatures)>>
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
.
sourcefn members_with_features_old(
&self,
specs: &[PackageIdSpec],
cli_features: &CliFeatures,
) -> Vec<(&Package, CliFeatures)>
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
.
sourcepub fn unit_needs_doc_scrape(&self, unit: &Unit) -> bool
pub fn unit_needs_doc_scrape(&self, unit: &Unit) -> bool
Returns true if unit
should depend on the output of Docscrape units.
sourcepub fn add_local_overlay(&mut self, id: SourceId, registry_path: PathBuf)
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.
sourcepub fn package_registry(&self) -> CargoResult<PackageRegistry<'gctx>>
pub fn package_registry(&self) -> CargoResult<PackageRegistry<'gctx>>
Builds a package registry that reflects this workspace configuration.
sourcefn local_overlays(
&self,
) -> CargoResult<impl Iterator<Item = (SourceId, SourceId)>>
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§
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> !UnwindSafe for Workspace<'gctx>
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
§impl<T> Instrument for T
impl<T> Instrument for T
§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
§fn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
§impl<T> Pointable for T
impl<T> Pointable for T
§impl<T> WithSubscriber for T
impl<T> WithSubscriber for T
§fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>where
S: Into<Dispatch>,
fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>where
S: Into<Dispatch>,
§fn with_current_subscriber(self) -> WithDispatch<Self>
fn with_current_subscriber(self) -> WithDispatch<Self>
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: 400 bytes