34 releases
0.17.5 | Oct 6, 2024 |
---|---|
0.17.3 | Jul 29, 2024 |
0.17.2 | Feb 5, 2024 |
0.17.1 | Oct 4, 2023 |
0.3.0 | Mar 11, 2021 |
#279 in Development tools
137,812 downloads per month
Used in 7 crates
(6 directly)
790KB
14K
SLoC
hakari
hakari
is the library underlying cargo hakari
, a tool to
manage workspace-hack
packages.
Examples
use guppy::MetadataCommand;
use hakari::{HakariBuilder, HakariOutputOptions};
// Use this workspace's PackageGraph for these tests.
let package_graph = MetadataCommand::new()
.build_graph()
.expect("obtained cargo-guppy's PackageGraph");
// The second argument to HakariBuilder::new specifies a Hakari (workspace-hack) package.
// In this repository, the package is called "guppy-workspace-hack".
let hakari_package = package_graph.workspace().member_by_name("guppy-workspace-hack").unwrap().id();
let hakari_builder = HakariBuilder::new(&package_graph, Some(hakari_package))
.expect("HakariBuilder was constructed");
// HakariBuilder has a number of config options. For this example, use the defaults.
let hakari = hakari_builder.compute();
// hakari can be used to build a TOML representation that forms part of a Cargo.toml file.
// Existing Cargo.toml files can be managed using Hakari::read_toml.
let toml = hakari.to_toml_string(&HakariOutputOptions::default()).expect("TOML output was constructed");
// toml contains the Cargo.toml [dependencies] that would go in the Hakari package. It can be
// written out through `HakariCargoToml` (returned by Hakari::read_toml) or manually.
println!("Cargo.toml contents:\n{}", toml);
The cargo-guppy
repository uses a workspace-hack crate managed by cargo hakari
. See the
generated Cargo.toml
.
The cargo-guppy
repository also has a number of fixtures that demonstrate Hakari's output.
Here is an example.
How hakari
works
Hakari follows a three-step process.
1. Configuration
A HakariBuilder
provides options to configure how a Hakari computation is done. Options supported
include:
- the location of the
workspace-hack
package - platforms to simulate Cargo builds on
- the version of the Cargo resolver to use
- packages to be excluded during computation
- packages to be excluded from the final output
With the optional cli-support
feature, HakariBuilder
options can be
read from or written to
a file as TOML or some other format.
2. Computation
Once a HakariBuilder
is configured, its compute
method can be
called to create a Hakari
instance. The algorithm runs in three steps:
- Use guppy to simulate a Cargo build for every workspace package and every given platform, with no features, default features and all features. Collect the results into a map indexed by every dependency and the different sets of features it was built with.
- Scan through the map to figure out which dependencies are built with two or more different feature sets, collecting them into an output map.
- If one assumes that the output map will be written out to the
workspace-hack
package through step 3 below, it is possible that it causes some extra packages to be built with a second feature set. Look for such packages, add them to the output map, and iterate until a fixpoint is reached and no new packages are built more than one way.
This computation is done in a parallel fashion, using the Rayon library.
The result of this computation is a Hakari
instance.
3. Serialization
The last step is to serialize the contents of the output map into the workspace-hack
package's
Cargo.toml
file.
-
Hakari::read_toml
reads an existingCargo.toml
file on disk. This file is partially generated:[package] name = "workspace-hack" version = "0.1.0" # more options... ### BEGIN HAKARI SECTION ... ### END HAKARI SECTION
The contents outside the
BEGIN HAKARI SECTION
andEND HAKARI SECTION
lines may be edited by hand. The contents within this section are automatically generated.On success, a
HakariCargoToml
is returned. -
Hakari::to_toml_string
returns the new contents of the automatically generated section. -
HakariCargoToml::write_to_file
writes out the contents to disk.
HakariCargoToml
also supports serializing contents to memory and producing diffs.
Future work
hakari
is still missing a few features:
- Simulating cross-compilations
- Platform-specific excludes
- Only including a subset of packages in the final result (e.g. unifying core packages like
syn
but not any others)
These features will be added as time permits.
Contributing
See the CONTRIBUTING file for how to help out.
License
This project is available under the terms of either the Apache 2.0 license or the MIT license.
Dependencies
~9–19MB
~282K SLoC