diff --git a/README.md b/README.md index 7acea5d2..52ea3e22 100644 --- a/README.md +++ b/README.md @@ -9,18 +9,23 @@ Lint your crate API changes for semver violations. - [Quick Start](#quick-start) - [FAQ](#faq) - [Configuration](#configuration) +- [Troubleshooting](#troubleshooting) - [Contributing](https://github.com/obi1kenobi/cargo-semver-checks/blob/main/CONTRIBUTING.md) ## Quick Start ```sh +# If you already use `cargo-binstall` for faster tool installations: +$ cargo binstall cargo-semver-checks + +# Otherwise: $ cargo install cargo-semver-checks --locked -# Check whether it's safe to release the new version: +# Lint a new release for SemVer breakage before `cargo publish`: $ cargo semver-checks ``` -Or use as a [GitHub Action](https://github.com/obi1kenobi/cargo-semver-checks-action) (used in .github/workflows/ci.yml in this repo): +Or use as a [GitHub Action](https://github.com/obi1kenobi/cargo-semver-checks-action) (used in `.github/workflows/ci.yml` in this repo): ```yaml - name: Check semver @@ -435,6 +440,22 @@ When the `--manifest-path` option is used to specify the subject package's `Carg If `cargo-semver-checks` is executed in a way that skips reading the current manifest (such as with the `--current-rustdoc` flag), it is currently not possible to configure lints. Interest in, and progress toward resolving this limitation is tracked in [this issue](https://github.com/obi1kenobi/cargo-semver-checks/issues/827). +## Troubleshooting + +This section documents common issues and the best ways to resolve them. + +### Running `cargo install cargo-semver-checks --locked` produces an error + +**Recommendation**: use [`cargo-binstall`](https://github.com/cargo-bins/cargo-binstall) to download a prebuilt binary if one is available for your platform, rather than compiling from scratch. + +Specific errors and their resolutions: +- ["error: failed to run custom build command for `libz-ng-sys vX.Y.Z`"](https://github.com/obi1kenobi/cargo-semver-checks/issues/841) + - **Preferred resolution**: use a prebuilt binary to avoid this problem entirely. + - This error is caused by missing `cmake` on your system, which is required by a transitive dependency of `cargo-semver-checks`. `cargo` does not currently offer a mechanism for such a binary dependency to be declared as required, nor automatically installed when needed. + - You can usually install it via a command like `apt install cmake` or `brew install cmake`, depending on your platform. + +*** + ### Visual Design Logo by [NUMI](https://github.com/numi-hq/open-design):