cargo-rbmt

Maintainer tools for Rust-based projects in the Bitcoin domain. Built with xshell.

Table of Contents

• Environment Variables
• Configuration
• Format
• Lint
• Test
  • no_std
• Integration
• Prerelease
• Run
• Lock Files
• API
• Toolchains
• Tools
• Workspace Integration
  • 1. Install on system
  • 2. Add as a dev-dependency
• CI Actions

Environment Variables

• RBMT_LOG_LEVEL
  • verbose: [DEFAULT] Print out underlying cargo commands and all their output, good for CI.
  • quiet: Suppress both cargo and rbmt stderr to reduce all noise.
  • progress: Show rbmt stderr on a single line with a visual indicator, for interactive use.

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.

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.

[package.metadata.rbmt.lint]
allowed_duplicates = [
    "syn",
    "bitcoin_hashes",
]

NOTE: Linting is only enforced (through command failure) on the given nightly toolchain. It is possible for different versions of rust to have different lint rules and behaviour, so to keep things simple just the newest is considered fail worthy.

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.

[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 integration testing framework, which provides Bitcoin Core binaries and testing infrastructure.

[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.

[package.metadata.rbmt.prerelease]
enabled = true
# baseline = "master"  # default

Use --force to run checks regardless of whether a version bump is detected.

cargo rbmt prerelease --force

Run

The run command executes arbitrary cargo commands with the specified toolchain and lockfile.

cargo rbmt --lock-file minimal --toolchain nightly run -- <CARGO_COMMAND> [ARGS...]

The -- separator tells cargo-rbmt to stop parsing its own flags and pass everything after it to cargo.

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.

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.

# 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 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.

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>/.

cargo rbmt api --baseline v0.1.0

Compares the current API against a baseline git reference (tag, branch, or commit) to detect breaking changes.

#[doc(hidden)] policy

Items marked with #[doc(hidden)] are excluded from API snapshots and breaking change detection. #[doc(hidden)] is an escape hatch to allow API changes without triggering breaking change warnings in CI. While hiding documentation doesn't change the actual types or signatures, it signals that the item is not part of the public API contract and may be modified or removed without warning.

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.

[workspace.metadata.rbmt.toolchains]
nightly = "nightly-2026-03-13"
stable = "1.93.1"

The current versions can be queried with the --msrv, --stable, or --nightly flags.

cargo +$(cargo rbmt toolchains --nightly) test --features one-off

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].

[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.

# 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.

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.

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.

[dev-dependencies]
cargo-rbmt = "0.1.0"

Then run via cargo.

cargo run --bin cargo-rbmt -- lint

It might be worth wrapping in an 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. Although it might be easier to write a custom action per-repository.

For faster CI runs, consider adding cargo build caching to your workflow with something like Swatinem/rust-cache.

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 for more details.