Struct HakariBuilder

pub struct HakariBuilder<'g> { /* private fields */ }

Configures and constructs Hakari instances.

This struct provides a number of options that determine how Hakari instances are generated.

Implementations

impl<'g> HakariBuilder<'g>

pub fn manage_dep_ops( &self, workspace_set: &PackageSet<'g>, ) -> Option<WorkspaceOps<'g, '_>>

Returns the set of operations that need to be performed to add the workspace-hack dependency to the given set of workspace crates.

Also includes remove operations for the workspace-hack dependency from excluded crates.

Returns None if the hakari package wasn’t specified at construction time.

Requires the cli-support feature to be enabled.

pub fn add_dep_ops( &self, workspace_set: &PackageSet<'g>, force: bool, ) -> Option<WorkspaceOps<'g, '_>>

Returns the set of operations that need to be performed to add the workspace-hack dependency to the given set of workspace crates.

Returns None if the hakari package wasn’t specified at construction time.

Requires the cli-support feature to be enabled.

pub fn remove_dep_ops( &self, workspace_set: &PackageSet<'g>, force: bool, ) -> Option<WorkspaceOps<'g, '_>>

Returns the set of operations that need to be performed to remove the workspace-hack dependency from the given set of workspace crates.

Returns None if the hakari package wasn’t specified at construction time.

Requires the cli-support feature to be enabled.

impl<'g> HakariBuilder<'g>

pub fn from_summary( graph: &'g PackageGraph, summary: &HakariBuilderSummary, ) -> Result<Self, Error>

Constructs a HakariBuilder from a PackageGraph and a serialized summary.

Requires the cli-support feature to be enabled.

Returns an error if the summary references a package that’s not present, or if there was some other issue while creating a HakariBuilder from the summary.

impl<'g> HakariBuilder<'g>

pub fn new( graph: &'g PackageGraph, hakari_id: Option<&PackageId>, ) -> Result<Self, Error>

Creates a new HakariBuilder instance from a PackageGraph.

The Hakari package itself is usually present in the workspace. If so, specify its package ID, otherwise pass in None.

Returns an error if a Hakari package ID is specified but it isn’t known to the graph, or isn’t in the workspace.

pub fn graph(&self) -> &'g PackageGraph

Returns the PackageGraph used to construct this Hakari instance.

pub fn hakari_package(&self) -> Option<&PackageMetadata<'g>>

Returns the Hakari package, or None if it wasn’t passed into new.

pub fn read_toml(&self) -> Option<Result<HakariCargoToml, CargoTomlError>>

Reads the existing TOML file for the Hakari package from disk, returning a HakariCargoToml.

This can be used with Hakari::to_toml_string to manage the contents of the Hakari package’s TOML file on disk.

Returns an error if there was an issue reading the TOML file from disk, or None if this builder was created without a Hakari package.

pub fn set_platforms( &mut self, platforms: impl IntoIterator<Item = impl Into<Cow<'static, str>>>, ) -> Result<&mut Self, TargetSpecError>

Sets a list of platforms for hakari to use.

By default, hakari unifies features that are always enabled across all platforms. If builds are commonly performed on a few platforms, hakari can output platform-specific instructions for those builds.

This currently supports target triples only, without further customization around target features or flags. In the future, this may support cfg() expressions using an SMT solver.

Call set_platforms with an empty list to reset to default behavior.

Returns an error if a platform wasn’t known to target_spec, the library hakari uses to resolve platforms.

pub fn platforms(&self) -> impl ExactSizeIterator<Item = &str> + '_

Returns the platforms set through set_platforms, or an empty list if no platforms are set.

pub fn set_resolver(&mut self, resolver: CargoResolverVersion) -> &mut Self

Sets the Cargo resolver version.

By default, HakariBuilder uses version 2 of the Cargo resolver. For more about Cargo resolvers, see the documentation for CargoResolverVersion.

pub fn resolver(&self) -> CargoResolverVersion

Returns the current Cargo resolver version.

pub fn add_traversal_excludes<'b>( &mut self, excludes: impl IntoIterator<Item = &'b PackageId>, ) -> Result<&mut Self, Error>

Pretends that the provided packages don’t exist during graph traversals.

Users may wish to not consider certain packages while figuring out the unified feature set. Setting this option prevents those packages from being considered.

Practically, this means that:

• If a workspace package is specified, Cargo build simulations for it will not be run.
• If a third-party package is specified, it will not be present in the output, nor will any transitive dependencies or features enabled by it that aren’t enabled any other way. In other words, any packages excluded during traversal are also excluded from the final output.

Returns an error if any package IDs specified aren’t known to the graph.

pub fn traversal_excludes<'b>( &'b self, ) -> impl Iterator<Item = &'g PackageId> + 'b

Returns the packages currently excluded during graph traversals.

Also returns the Hakari package if specified. This is because the Hakari package is treated as excluded while performing unification.

pub fn is_traversal_excluded( &self, package_id: &PackageId, ) -> Result<bool, Error>

Returns true if a package ID is currently excluded during traversal.

Also returns true for the Hakari package if specified. This is because the Hakari package is treated as excluded by the algorithm.

Returns an error if this package ID isn’t known to the underlying graph.

pub fn add_final_excludes<'b>( &mut self, excludes: impl IntoIterator<Item = &'b PackageId>, ) -> Result<&mut Self, Error>

Adds packages to be removed from the final output.

Unlike traversal_excludes, these packages are considered during traversals, but removed at the end.

Returns an error if any package IDs specified aren’t known to the graph.

pub fn final_excludes<'b>(&'b self) -> impl Iterator<Item = &'g PackageId> + 'b

Returns the packages to be removed from the final output.

pub fn is_final_excluded(&self, package_id: &PackageId) -> Result<bool, Error>

Returns true if a package ID is currently excluded from the final output.

Returns an error if this package ID isn’t known to the underlying graph.

pub fn is_excluded(&self, package_id: &PackageId) -> Result<bool, Error>

Returns true if a package ID is excluded from either the traversal or the final output.

Also returns true for the Hakari package if specified. This is because the Hakari package is treated as excluded by the algorithm.

Returns an error if this package ID isn’t known to the underlying graph.

pub fn add_registries( &mut self, registries: impl IntoIterator<Item = (impl Into<String>, impl Into<String>)>, ) -> &mut Self

Add alternate registries by (name, URL) pairs.

This is a temporary workaround until Cargo issue #9052 is resolved.

pub fn set_unify_target_host( &mut self, unify_target_host: UnifyTargetHost, ) -> &mut Self

Whether and how to unify feature sets across target and host platforms.

This is an advanced feature that most users don’t need to set. For more information about this option, see the documentation for UnifyTargetHost.

pub fn unify_target_host(&self) -> UnifyTargetHost

Returns the current value of unify_target_host.

pub fn set_output_single_feature( &mut self, output_single_feature: bool, ) -> &mut Self

Whether to unify feature sets for all dependencies.

By default, Hakari only produces output for dependencies that are built with more than one feature set. If set to true, Hakari will produce outputs for all dependencies, including those that don’t need to be unified.

This is rarely needed in production, and is most useful for testing and debugging scenarios.

pub fn output_single_feature(&self) -> bool

Returns the current value of output_single_feature.

pub fn set_dep_format_version( &mut self, dep_format_version: DepFormatVersion, ) -> &mut Self

Version of hakari data to output.

For more, see the documentation for DepFormatVersion.

pub fn dep_format_version(&self) -> DepFormatVersion

Returns the current value of dep_format_version.

pub fn set_workspace_hack_line_style( &mut self, line_style: WorkspaceHackLineStyle, ) -> &mut Self

Kind of workspace-hack = ... lines to output.

For more, see the documentation for WorkspaceHackLineStyle.

pub fn workspace_hack_line_style(&self) -> WorkspaceHackLineStyle

Returns the current value of workspace_hack_line_style.

pub fn compute(self) -> Hakari<'g>

Computes the Hakari for this builder.

impl<'g> HakariBuilder<'g>

Helpers for property testing

The methods in this section allow random instances of a HakariBuilder to be generated, for use in property-based testing scenarios.

Requires the proptest1 feature to be enabled.

pub fn proptest1_strategy( graph: &'g PackageGraph, hakari_id_strategy: impl Strategy<Value = Option<&'g PackageId>> + 'g, ) -> impl Strategy<Value = HakariBuilder<'g>> + 'g

Returns a Strategy that generates random HakariBuilder instances based on this graph.

Requires the proptest1 feature to be enabled.

Panics

Panics if:

• there are no packages in this PackageGraph, or
• hakari_id is specified but it isn’t known to the graph, or isn’t in the workspace.

impl<'g> HakariBuilder<'g>

pub fn to_summary(&self) -> Result<HakariBuilderSummary, TargetSpecError>

Converts this HakariBuilder to a serializable summary.

Requires the cli-support feature to be enabled.

Returns an error if there are any custom platforms. Serializing custom platforms is currently unsupported.

impl<'g> HakariBuilder<'g>

pub fn verify(self) -> Result<(), VerifyErrors<'g>>

Verify that hakari worked properly.

Returns Ok(()) if only one version of every third-party dependency was built, or a list of errors if at least one third-party dependency had more than one version built.

For more about how this works, see the documentation for the verify module.

Trait Implementations

impl<'g> Clone for HakariBuilder<'g>

fn clone(&self) -> HakariBuilder<'g>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'g> Debug for HakariBuilder<'g>

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

Formats the value using the given formatter.