cargo-omnibus

A Cargo subcommand that creates an "omnibus" crate bundling multiple Rust libraries into a single compilation unit.

Statically linking multiple Rust-made .a files is unsupported. While most symbols compiled with rustc are mangled, some symbols in the Rust standard library are unmangled C symbols. If an application attempts to link two static libraries containing these symbols, it will (at best) get a duplicate symbol error, or (at worst) silently crash due to ODR violations.

Two approaches have emerged to mitigate this:

1. Create a single Rust library that depends on all Rust libraries in your build tree
2. Isolate each Rust library in a DLL/dylib, each with a stable C API

The second option leads to binary bloat (each dylib contains its own copy of the standard library). For this reason, mature C++/Rust hybrid projects like Firefox use the first approach via a "Rust unified library" crate that depends on all Rust libraries and re-exports their public symbols.

cargo-omnibus automates this pattern.

Installation

cargo install --path .

Or from crates.io (once published):

cargo install cargo-omnibus

Usage

Initialize an omnibus crate

# Create a new omnibus crate
cargo omnibus ./my-omnibus

# With a specific crate type (e.g., for C++/Rust FFI)
cargo omnibus ./my-omnibus --crate-type cdylib

# Multiple crate types
cargo omnibus ./my-omnibus --crate-type cdylib --crate-type rlib

# With additional cargo init flags
cargo omnibus ./my-omnibus --crate-type cdylib --edition 2021 --name my-unified-rust

Add passenger crates

Use standard cargo add:

cargo add --path ../rust-lib-a --manifest-path ./my-omnibus/Cargo.toml
cargo add --path ../rust-lib-b --manifest-path ./my-omnibus/Cargo.toml

Build

cd my-omnibus
cargo build --release

The generated build.rs automatically regenerates src/lib.rs from your Cargo.toml dependencies whenever you build.

How It Works

cargo omnibus creates a standard Rust crate with a special build.rs that:

1. Watches Cargo.toml for changes
2. Scans for path dependencies (local crates)
3. Generates src/lib.rs with pub use <crate>::*; re-exports

This means you can use standard cargo add and cargo build commands - the omnibus crate stays in sync automatically.

Configuration

Customize the generated lib.rs via [package.metadata.omnibus] in your Cargo.toml:

[package.metadata.omnibus]
lib-attrs = [
    "#![deny(ambiguous_glob_reexports)]",
    "#![doc = \"My unified Rust library\"]",
]

These attributes are prepended to the generated lib.rs.

Generated Output

After adding some dependencies:

Cargo.toml:

[package]
name = "my-omnibus"
version = "0.1.0"
edition = "2021"

[package.metadata.omnibus]
lib-attrs = ["#![deny(ambiguous_glob_reexports)]"]

[dependencies]
rust-lib-a = { path = "../rust-lib-a" }
rust-lib-b = { path = "../rust-lib-b" }

[build-dependencies]
toml = "0.8"

src/lib.rs (auto-generated on build):

//! AUTO-GENERATED by build.rs - DO NOT EDIT
//! Configure via [package.metadata.omnibus] in Cargo.toml

#![deny(ambiguous_glob_reexports)]

pub use rust_lib_a::*;
pub use rust_lib_b::*;

Common Use Cases

C++/Rust FFI

When embedding Rust in a C++ application, create a cdylib omnibus:

cargo omnibus ./my-omnibus --crate-type cdylib

Or add to an existing omnibus Cargo.toml:

[lib]
crate-type = ["cdylib"]

WebAssembly

Bundle multiple Rust libraries for WASM:

cargo omnibus ./my-wasm-omnibus --crate-type cdylib

# Build with:
cargo build --target wasm32-unknown-unknown --release

Recommended Reading

• Firefox's Rust unified library
• Rust static library linking issue
• C++/Rust Interop - CppCon talk

License

MIT OR Apache-2.0