# cargo-rbmt
Maintainer tools for Rust-based projects in the Bitcoin domain. Built with [xshell](https://github.com/matklad/xshell).
## Table of Contents
- [Environment Variables](#environment-variables)
- [Configuration](#configuration)
- [Format](#format)
- [Lint](#lint)
- [Test](#test)
- [no_std](#no_std)
- [Integration](#integration)
- [Prerelease](#prerelease)
- [Lock Files](#lock-files)
- [API](#api)
- [Toolchains](#toolchains)
- [Tools](#tools)
- [Workspace Integration](#workspace-integration)
- [1. Install on system](#1-install-on-system)
- [2. Add as a dev-dependency](#2-add-as-a-dev-dependency)
- [CI Actions](#ci-actions)
## Environment Variables
* `RBMT_LOG_LEVEL=quiet` - Suppress verbose output and reduce cargo noise.
## Configuration
Configuration for `rbmt` is stored in `[package.metadata.rbmt]` in a package's `Cargo.toml` manifest. Some configuration lives under `[workspace.metadata.rbmt]` in the root manifest of a workspace, but can fallback to `[package.metadata.rbmt]` if there is only one package in the repository.
> **NOTE:** Cargo reserves `[package.metadata]` and `[workspace.metadata]` as explicitly supported extension points for third-party tooling. Cargo itself ignores any keys nested under these tables, so they will never clash with a future built-in Cargo field. `[workspace.metadata]` was stabilized in Cargo 1.46 and `[package.metadata]` has been around much longer. The `rbmt` sub-key further namespaces the configuration to avoid collisions with other tools. If a repository only has one package and is not using any workspace features, use the `package` namespace because simply adding the `workspace.metadata` settings enables workspace features in cargo.
## Format
The `fmt` command formats all files in the workspace using `rustfmt` with the nightly toolchain, which is the convention in the rust-bitcoin ecosystem.
```bash
cargo rbmt fmt
cargo rbmt fmt --check
cargo rbmt fmt -p bitcoin
```
## Lint
The `lint` command detects duplicate dependencies, but some may be unavoidable (e.g., during dependency updates where transitive dependencies haven't caught up). Configure `[package.metadata.rbmt.lint]` to whitelist specific duplicates.
```toml
[package.metadata.rbmt.lint]
allowed_duplicates = [
"syn",
"bitcoin_hashes",
]
```
## Test
The `test` command runs feature matrix testing for your package. Every run unconditionally tests all features enabled, no features enabled, and each feature by itself. A package's features are auto-discovered. Randomly sampled feature subsets (number of sets grows with the number of package features) are tested per commit ID to try and catch interaction bugs without running massive matrices on every run.
The `--baseline <ref>` flag checks that every commit between `<ref>` and `HEAD` passes the test suite, ensuring the branch remains bisectable.
```toml
[package.metadata.rbmt.test]
# Examples to run with different feature configurations.
#
# Supported formats:
# * "name" - runs with default features.
# * "name:-" - runs with no-default-features.
# * "name:feature1 feature2" - runs with specific features.
examples = [
"bip32", # Default features
"bip32:-", # No default features
"bip32:serde rand", # Specific features
]
# Features to exclude from auto-discovery.
# Use for internal or alias features that should not be tested in isolation.
exclude_features = ["_internal", "default-features"]
# Always test specific feature combinations.
exact_features = [
["serde", "rand"], # Test serde and rand interaction.
["serde", "std"], # Assuming serde has a weak dependency on std, test interaction when enabled.
["rand", "std"], # Assuming rand has a weak dependency on std, test interaction when enabled.
["serde", "rand", "std"], # Test both with weak dependency interaction.
]
```
### no_std
When a package declares `#![no_std]` in its library source, `cargo-rbmt test` automatically performs an additional verification step on the `thumbv7m-none-eabi` target to try and detect unintentional std library usage.
## Integration
The `integration` command is designed to work with the [`corepc`](https://github.com/rust-bitcoin/corepc) integration testing framework, which provides Bitcoin Core binaries and testing infrastructure.
```toml
[package.metadata.rbmt.integration]
# Integration tests package name, defaults to "bitcoind-tests".
package = "bitcoind-tests"
# Versions to test. If omitted, tests all discovered versions from Cargo.toml.
versions = ["29_0", "28_2", "27_2"]
```
## Prerelease
The `prerelease` command performs readiness checks before releasing a package. Checks are opt-in and only run for packages with `enabled = true` that also have a version bump in `Cargo.toml` since the baseline ref.
```toml
[package.metadata.rbmt.prerelease]
enabled = true
# baseline = "master" # default
```
Use `--force` to run checks regardless of whether a version bump is detected.
```bash
cargo rbmt prerelease --force
```
## Lock Files
To ensure your package works with the full range of declared dependency versions, `cargo-rbmt` requires two lock files in your repository.
* `Cargo-minimal.lock` - Minimum versions that satisfy your dependency constraints.
* `Cargo-recent.lock` - Recent/updated versions of dependencies.
The `lock` command generates and maintains these files for you. You can then use `--lock-file` with any command to test against either version set.
```bash
cargo rbmt lock
```
1. Verify that direct dependency versions aren't being bumped by transitive dependencies.
2. Generate `Cargo-minimal.lock` with minimal versions across the entire dependency tree.
3. Update `Cargo-recent.lock` with conservatively updated dependencies.
```bash
# Test with minimal versions.
cargo rbmt --lock-file minimal test stable
# Test with recent versions.
cargo rbmt --lock-file recent test stable
# Works with any command.
cargo rbmt --lock-file minimal lint
cargo rbmt --lock-file minimal docs
```
When you specify `--lock-file`, the tool copies that lock file to `Cargo.lock` before running the command. This allows you to test your code against different dependency version constraints.
## API
The `api` command helps maintain API stability by generating public API snapshots and checking for breaking changes. It uses the [public-api](https://github.com/Enselic/cargo-public-api) crate to analyze a crate's public interface.
> **NOTE:** `api` has an implicit dependency on the version of the nightly toolchain since it relies on an unstable docsrs interface. Currently, it requires [*nightly-2025-08-02* or later](https://github.com/cargo-public-api/cargo-public-api/blob/main/README.md#compatibility-matrix).
```bash
cargo rbmt api
```
1. Generates API snapshots for feature configurations.
2. Validates that features are additive (enabling features only adds to the API, never removes).
3. Checks for uncommitted changes to API files.
The generated API files are stored in `api/<package-name>/`.
```bash
cargo rbmt api --baseline v0.1.0
```
Compares the current API against a baseline git reference (tag, branch, or commit) to detect breaking changes.
## Toolchains
The `toolchains` command installs the three required toolchains for `cargo-rbmt` commands, `nightly`, `stable`, and `MSRV`. `nightly` and `stable` Toolchain versions are read from the root manifest `Cargo.toml` of a repository. The `MSRV` is read from all the package manifests in a workspace. Workspaces must declare a single consistent MSRV across all packages. Workspaces with conflicting `rust-version` fields are not supported.
> **NOTE:** This command requires `rustup` on the system, which is not the case for all other `cargo-rbmt` commands.
Workspace enabled repositories should set the versions under the `workspace.metadata.rbmt.toolchains` namespace in the root `Cargo.toml`. If a repository is a single package without a workspace, use the `package.metadata.rbmt.toolchains` namespace instead.
```toml
[workspace.metadata.rbmt.toolchains]
nightly = "nightly-2026-03-13"
stable = "1.93.1"
```
The command prints `export` statements to stdout and all other output to stderr, so it can be used with `eval` to set toolchain version environment variables in the calling shell.
```bash
eval "$(cargo rbmt toolchains)"
cargo +$RBMT_NIGHTLY rbmt lint
cargo +$RBMT_STABLE rbmt test
cargo +$RBMT_MSRV rbmt test --toolchain msrv
```
The `--update-nightly` and `--update-stable` flags each install the corresponding floating toolchain, query its resolved version from `rustc`, and write the result to the appropriate version file before proceeding with the normal install and export.
## Tools
The `tools` command installs external cargo tools whose versions are pinned in the *root* `Cargo.toml` manifest. The preferred location is `[workspace.metadata.rbmt.tools]`.
```toml
[workspace.metadata.rbmt.tools]
cargo-semver-checks = "0.46.0"
cargo-public-api = "0.50.1"
```
For single-package repos with no explicit `[workspace]` table, `[package.metadata.rbmt.tools]` is supported as a fallback.
```bash
# Install all tools at their pinned versions.
cargo rbmt tools
# Install only a specific tool.
cargo rbmt tools cargo-semver-checks
# Install each tool at its latest version and update the pins in Cargo.toml.
cargo rbmt tools --update
# Update only a specific tool.
cargo rbmt tools --update cargo-public-api
```
The `--update` flag installs each tool without a version constraint, then reads the resolved version back from `cargo install --list` and writes it into `Cargo.toml`. The resulting diff can be reviewed and committed as a deliberate version bump.
> **Note:** Tools are installed via `cargo install`. Installing or updating a tool overwrites any previously installed version of that binary system-wide. If you rely on a specific version of a tool outside of this workflow, be aware that running `cargo rbmt tools` will replace it with the pinned version.
## Workspace Integration
`cargo-rbmt` can simply be installed globally on a system or added as a dev-dependency to a package.
### 1. Install on system
Install the tool globally on your system with `cargo install`.
```bash
cargo install cargo-rbmt@0.1.0
```
Then run from anywhere in your repository as a cargo subcommand. It can also be called directly as `cargo-rbmt`.
```bash
cargo rbmt lint
```
### 2. Add as a dev-dependency
Add as a dev-dependency to a workspace member. This pins the tool version in your lockfile for reproducible builds. But this also means that `cargo-rbmt` dependencies could influence version resolution for the workspace.
```toml
[dev-dependencies]
cargo-rbmt = "0.1.0"
```
Then run via cargo.
```bash
cargo run --bin cargo-rbmt -- lint
```
It might be worth wrapping in an [xtask](https://github.com/matklad/cargo-xtask) package for a clean interface.
## CI Actions
A composite action is provided to make it easy to use `cargo-rbmt` in Github/Forgejo Actions CI. For faster CI runs, consider adding cargo build caching to your workflow with something like `Swatinem/rust-cache`.
```yaml
steps:
- uses: actions/checkout@v6
- uses: Swatinem/rust-cache@v2
- uses: rust-bitcoin/rust-bitcoin-maintainer-tools/.github/actions/setup-rbmt@master
- run: cargo rbmt test
```
See the [action](../.github/actions/setup-rbmt/action.yml) for more details.