Home

Awesome

<h1 align="center"><img width="350" src="docs/logo.png" /></h1> <div align="center">

Donate Latest Version MIT docs

</div>

Potential unused, enabled feature flag finder and pruner.

This cargo tool allows you to find and prune enabled, but, potentially unused feature flags from your project.

Use unused-features --help to fetch more details about available subcommands and their configurations.

1. How to use

Run cargo install cargo-unused-features or download the library and build it yourself.

  1. Step Analyzing enabled unused features.

You can control the compilation by supplying --bin, --lib, --examples, --benches, --tests flags. By default, libraries and binaries are compiled. If you want tests, examples, benches, be compiled in the analysis, make sure to supply the corresponding tags.

cd C:/some_path/
unused-features analyze

After it finished running, check the report.json in the project directory and use this for the next two steps.

  1. Generating a HTML report. (optional)

You can generate a simple HTML report from the json to make it easier to inspect results.

<img src="docs/readme-1.jpg" />
unused-features build-report --input "C:/some_path/report.json"

After it finished running, check the report.html in the project directory. You can choose to manually fix your dependencies or use the command in the next step.

  1. Applying suggested removals of feature flags.

It is possible to auto-apply the findings of the first command. But keep in mind the disclaimers.

unused-features prune --input "C:/some_path/report.json"

2. How it Works

This library works for both workspaces and individual crates. In the context of a workspace it will just iterate each crate in the workspace-definition and run the same process it does for a single crate.

For a single crate it removes a feature of a dependency and then compiles the project to see if it still compiles. If it does, the feature flag can possibly be removed, but it can be a false-positve (disclaimers.). Yes, recompiling for every feature-flag implies some overhead. However, this is a one-time thing and if you have a large project, just let it run for a while. I personally have ran it on a project with over 50 crates and it finished within an hour. The compiler will not perform a complete clean rebuild which is in our favor.

Furthermore, This library uses cargo_toml to remove or add features. It loads a TOML file into memory, modifies the dependency features, serializes the Manifest, and writes it back to the toml-file. Then it starts compiling, and after it finishes running, the original content is written back as if nothing had happened.

But before doing all of that, we need to know which features to remove in the first case. This library uses cargo-metadata to collect all enabled features from the dependencies. Features can be enabled in several ways. Manually by features = ['x', 'y'] tag, or by the default-features=false/true tag. Also, features can enable 0-n other features e.g default=[x,y]. So, this library collects all enabled features, whether they are implicitly or explicitly enabled. After it collects all enabled features for a dependency, it will remove them one-by-one and compile the project as described above.

During the process, a json report is updated for each crate to ensure that if it crashes the progress is not lost. Use the cargo unused-features build-report command to visualize this report.

Finally, this library also has the option to apply all suggestions automatically by running cargo unused-features prune command. For this task, toml-edit is used because it doesn't mess with formatting, comments, and spaces, in the TOML-file.

3. Some things to keep in mind

4. Report Bug

This tool is very new, and one can expect problems. If you have problems, please do the following:

  1. Open an issue with the problematic Cargo.toml file.
  2. Provide the --log debug flag to the cargo-unused-features command and post the logs in the issue as well.

Future

Would be nice to find ways to be more certain about when a feature can be removed. Potentially we would need to do some regex matches with features in the dependency code base and see how the feature is used. And with that get a more precise assumption. If you have an idea, feel free to open an issue or reach out to me!