cargo-public-api
List and diff the public API of Rust library crates between releases and commits. Detect breaking API changes and semver violations via CI or a CLI. Relies on and automatically builds rustdoc JSON, for which a recent version of the Rust nightly toolchain must be installed.
Installation
Install the cargo public-api
subcommand with a recent regular stable Rust toolchain:
Ensure nightly-2024-10-18 or later is installed (does not need to be the active toolchain) so cargo public-api
can build rustdoc JSON for you:
Usage
List the Public API
This example lists the public API of the regex
crate. First we clone the repo:
;
Now we can list the public API of regex
by running
which will print the public API of regex
with one line per public item in the API:
Diff the Public API
… Against a Specific Published Version
To diff the public API of the regex
crate in the current directory against published version 1.6.0 on crates.io:
… Against the Latest Published Version
… Between Git Commits
… as a CI Check
With a regular cargo test
that you run in CI you will be able to
- prevent accidental changes to your public API
- review the public API diff of deliberate changes
First add the latest versions of the recommended libraries to your [dev-dependencies]
:
Then add the following test to your project. As the author of the below test code, I hereby associate it with CC0 and to the extent possible under law waive all copyright and related or neighboring rights to it:
Before you run the test the first time you need to bless the current public API:
UPDATE_EXPECT=1
This creates a tests/public-api.txt
file in your project that you git add
together with your other project files. Whenever you change the public API, you need to bless it again with the above command. If you forget to bless, the test will fail, together with instructions on how to bless.
Less Noisy Output
For completeness, items belonging to Blanket Implementations, Auto Trait Implementations, and Auto Derived Implementations, such as
impl<T, U> Into<U> for T where U: From<T>
impl Sync for ...
impl Debug for ...
/#[derive(Debug)]
are included in the list of public items by default. Use
--omit blanket-impls
--omit auto-trait-impls
--omit auto-derived-impls
respectively to omit such items from the output to make it much less noisy:
For convenience you can also use -s
(--simplified
) to achieve the same thing. This is a shorter form of the above command:
Compatibility Matrix
Version | Understands the rustdoc JSON output of |
---|---|
0.40.x — 0.42.x | nightly-2024-10-18 — |
0.39.x | nightly-2024-10-13 — nightly-2024-10-17 |
0.38.x | nightly-2024-09-10 — nightly-2024-10-12 |
0.37.x | nightly-2024-07-05 — nightly-2024-09-09 |
0.35.x — 0.36.x | nightly-2024-06-07 — nightly-2024-07-04 |
0.32.x — 0.34.x | nightly-2023-08-25 — nightly-2024-06-06 |
0.30.x — 0.31.x | nightly-2023-05-24 — nightly-2023-08-24 |
earlier versions | see here |
Changelog
See CHANGELOG.md.
Contributing
See CONTRIBUTING.md.
Maintainers
Trademark Notice
"Rust" and "Cargo" are trademarks of the Rust Foundation. This project is not affiliated with, endorsed by, or otherwise associated with the Rust Project or Rust Foundation.