Cbindgen Verify

cbindgen Verify

When a Rust crate exposes a C ABI for use by a C/C++ host (the audio driver, a JUCE plugin shell, an Emscripten-built worklet host), the C header is generated from the Rust source by cbindgen and committed to the repo so C consumers do not need Cargo installed.

This skill regenerates the header from the current Rust source and diffs it against the committed file. Any drift means the Rust ABI has been changed without updating the header — a class of bug that otherwise surfaces only when the C side fails to link or, worse, links against a stale header and produces UB at runtime.

Requirements

• cbindgen — install via cargo install --force cbindgen.
• A cbindgen.toml config file in the crate directory (cbindgen's standard convention).
• The committed C header to compare against.

Instructions

The arguments are in $ARGUMENTS. Pass them directly to the verify script:

bash "$(dirname "$0")/verify.sh" $ARGUMENTS

Argument 1 is the crate directory (containing Cargo.toml and cbindgen.toml). Argument 2 is the path to the committed header.

Output sections

| Section | What it reports | |---|---| | CBINDGEN | Whether cbindgen ran successfully | | DIFF | Unified diff between regenerated and committed headers, or PASS if identical |

Typical usage

# Verify a single crate's header
bash verify.sh ./rust/audio-dsp ./include/audio_dsp.h

# As a pre-commit hook
bash verify.sh ./rust/audio-dsp ./include/audio_dsp.h || {
  echo "C header out of date — regenerate with: cbindgen --config rust/audio-dsp/cbindgen.toml --crate audio-dsp --output include/audio_dsp.h"
  exit 1
}

What to look for

• DIFF showing added/removed functions — the Rust public ABI changed; either the change is intentional (regenerate and commit the new header, notify the c-audio-engineer) or accidental (revert the Rust change).
• DIFF showing changed signatures — a parameter type, return type, or struct field changed. This is a breaking change for the C side regardless of whether the new layout is binary-compatible. Coordinate with the c-audio-engineer before regenerating.
• DIFF showing only comment or whitespace changes — usually a cbindgen version mismatch between the developer who committed the header and the CI environment. Pin cbindgen's version in the project (e.g. cargo install --version X.Y.Z cbindgen) to eliminate the drift.

When to skip

Do not skip. The cost of running it is sub-second; the cost of a stale header is silent UB.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: gertsylvest
• Source: gertsylvest/meta-team
• License: MIT

Install and usage instructions live in the source repository linked above.