Rust and native dependencies

Rust & Native Dependencies

When to Use

Use when upgrading Rust crates (Cargo.toml / Cargo.lock), Tauri/NAPI-RS/PyO3 native bridges, WebAssembly toolchains (wasm-bindgen), or C/C++ native addons (node-gyp, prebuild, -sys crates).

Cargo Semver, Feature Flags & Lockfile Discipline

1. Understand Cargo Semver & 0.x Rules

• In Cargo, bare version strings ("1.2.3") mean ^1.2.3 (semver-compatible).
• For 0.x.y crates (where x > 0), 0.2.0 $\rightarrow$ 0.3.0 is a breaking major bump in Cargo's resolver! Updating a 0.x crate frequently introduces duplicate versions in Cargo.lock if sibling crates still depend on the older 0.x minor.
• Use cargo update -p <crate> (or cargo update -p <crate>@<old> --precise <new>) to update specific crates in Cargo.lock without moving the entire dependency tree.

2. Detect & Eliminate Duplicate Crate Resolutions

• Run cargo tree -d after every Cargo.toml edit.
• Duplicate versions of core ecosystem crates (tokio, serde, rand, http, bytes, syn, windows-sys, rustls, sqlx) bloat compile times, increase binary size, and—critically—cause type incompatibility errors when one crate returns http::Request (from http 0.2) and another expects http::Request (from http 1.0).
• Upgrade coupled crate ecosystems together:
  • axum + tower-http + hyper + http + tokio
  • serde + serde_json + serde_with
  • tracing + tracing-subscriber + opentelemetry
  • tauri + tauri-build + tauri-plugin-* (plus matching @tauri-apps/api and @tauri-apps/plugin-* JS packages!)
  • wasm-bindgen crate in Cargo.lock must match the exact version of the wasm-bindgen-cli binary used in build scripts.

3. MSRV (Minimum Supported Rust Version) & Toolchain Checks

• Check rust-version in Cargo.toml, rust-toolchain.toml (channel = "1.xx.0"), and CI / Dockerfile Rust images.
• Transitive crates frequently bump their MSRV in minor or patch releases (cargo update pulls a latest transitive version requiring Rust 1.82+ when CI runs 1.78).
• If constrained by an older MSRV, use cargo update -p <transitive-crate> --precise <msrv-compatible-version> or Cargo's MSRV-aware resolver (resolver = "2" / "3" with cargo +<msrv> check).

4. Feature Unification & default-features = false

• Cargo unifies features across all workspace members unless isolated. Inspect cargo tree -e features -i <crate> to see which dependency enabled an unwanted feature (e.g., pulling native-tls / OpenSSL when the project standardizes on rustls-tls).
• When upgrading -sys crates (openssl-sys, libsqlite3-sys, zstd-sys, ring, aws-lc-rs), check whether vendored / bundled features or system pkg-config / cmake / clang build tools are required across macOS, Linux (gnu vs musl), and Windows (msvc).

5. Native Addons in Node / Python / Desktop Apps

• For Node native modules (better-sqlite3, sharp, bcrypt, keytar, node-pty, @swc/core, @rollup/rollup-*, esbuild):
  • Check prebuilt binary availability (N-API version, node-pre-gyp, prebuild-install, or platform-specific optionalDependencies).
  • Ensure package-lock.json / pnpm-lock.yaml retains all platform optionalDependencies (darwin-arm64, darwin-x64, linux-x64-gnu, linux-arm64-gnu, win32-x64-msvc) so developing on macOS does not strip Linux/Windows entries needed in CI or Docker.
  • In Electron/Tauri apps, verify electron-rebuild / @electron/rebuild compatibility against the bundled Electron ABI (process.versions.modules).