Struct Determinator

pub struct Determinator<'g, 'a> { /* private fields */ }

Determine target dependencies from changed files and packages in a workspace.

For more about how the determinator works, see the crate-level documentation.

This struct has two lifetime parameters:

• 'g stands for the lifetime of the new graph. The DeterminatorSet will be bound to this lifetime.
• 'a is the lifetime of the old graph, Cargo options, and changed paths. The DeterminatorSet will not be bound to this lifetime.

Implementations

impl<'g, 'a> Determinator<'g, 'a>

pub fn new(old: &'a PackageGraph, new: &'g PackageGraph) -> Self

Creates a new instance of Determinator with old and new package graphs.

pub fn add_changed_paths( &mut self, paths: impl IntoIterator<Item = &'a (impl AsRef<Utf8Path> + ?Sized + 'a)>, ) -> &mut Self

Adds a list of changed paths. This list is used as a source of information for the determinator.

This should consist of paths that are changed since the base revision. Paths on Windows may use either / or \\ as separators.

Utf8Paths0 in this crate provides a convenient way to handle null-separated paths as produced by source control systems.

Should you include untracked and ignored files?

For comparisons against the working directory, one may or may not wish to include untracked files. A few points to consider:

• If your code uses a library like datatest, simply creating a file in the right place is enough to add a new test. If untracked files are not included, the user may have to run git add before the determinator picks the change up.
• On the other hand, if a user wishes to include a new test in their PR, they’re going to have to run git add at some point anyway.
• Some users may have untracked files lying around in their repository for long periods of time, and those files may cause false positives.
• Git makes it surprisingly hard to list out untracked files, requiring git status --porcelain -z with some additional filtering on top to do so. git diff doesn’t have an option to list untracked files.
• This is generally moot in CI, since those workflows will likely be comparing against a commit.
• In most cases, ignored files should not be considered by the determinator, since they don’t affect CI builds.

On balance, only considering tracked files appears to be the right approach for most situations.

pub fn match_path( &self, path: impl AsRef<Utf8Path>, match_cb: impl FnMut(&'g PackageId), ) -> PathMatch

Returns what would happen if a given path was added to the changed set.

This does not add any path to the changed set, but indicates what would happen if a path is added.

This method may be used to ensure that all paths in a repository are covered by at least one rule if they don’t match a package.

match_cb is called for all package IDs that the path matches.

pub fn set_rules( &mut self, rules: &DeterminatorRules, ) -> Result<&mut Self, RulesError>

Processes and configures determinator rules.

Returns an error if the rules were invalid in some way.

pub fn set_cargo_options( &mut self, cargo_options: &'a CargoOptions<'a>, ) -> &mut Self

Configures Cargo options.

These options are used to determine if the build for a particular package has changed.

If no options are specified, the default CargoOptions, as specified by CargoOptions::new, are used, with one exception: dev-dependencies are built by default.

pub fn default_cargo_options() -> CargoOptions<'static>

Returns the default Cargo options used by the determinator.

These are the same as the defaults returned by CargoOptions::new, except:

• dev-dependencies are enabled
• the host and target platforms are set to the current platform

pub fn set_features_only<'b>( &mut self, workspace_names: impl IntoIterator<Item = &'b str>, features: StandardFeatures, ) -> Result<&mut Self, Error>

Configures features-only packages that are used in build simulations.

The packages and features will be used for feature unification. This is useful for pseudo-packages or workspace-hack packages, including those generated by tools like Hakari.

For more about features_only, see the documentation for CargoSet::new.

The package names are expected to be present in the new graph, but may not be present in the old PackageGraph.

• If a package name isn’t in the new graph, this method returns an error.
• If a package name isn’t in the old graph, it is ignored.

pub fn compute(&self) -> DeterminatorSet<'g>

Uses the old and new sets and the list of changed files to compute the list of projects that is affected.

Trait Implementations

impl<'g, 'a> Clone for Determinator<'g, 'a>

fn clone(&self) -> Determinator<'g, 'a>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'g, 'a> Debug for Determinator<'g, 'a>

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

Formats the value using the given formatter.