skip to content

In a Cargo.toml [lib] table, what do crate-type values lib, rlib, cdylib and staticlib produce, and what breaks when only cdylib is listed?

level: middleimportance: should knowfreq 35%

answer

  1. who will link this artifact
  2. Rust consumers read metadata
  3. C callers want a system library
  4. your own binaries are Rust consumers too
  5. doctests quietly disappear

basics

~20 s

lib (the default) and rlib emit a Rust library for Rust crates; cdylib a shared library for other languages; staticlib an archive bundling every dependency. Listing only cdylib leaves the package's own binaries and tests nothing to link.

solid answer

~40 s

`crate-type` says which artifacts the library target emits. The default, `"lib"`, is the compiler-recommended Rust library, today an `.rlib`; `"rlib"` asks for that format explicitly. `"cdylib"` builds a system dynamic library (`.so`, `.dylib`, `.dll`) for loading from C or another language, `"staticlib"` builds a `.a` or `.lib` that bundles the crate, its dependencies and std for linking into a non-Rust program, and a procedural-macro library uses `proc-macro = true`. The values stack. The trap: with `crate-type = ["cdylib"]` alone there is no Rust library left, so the package's own binaries and integration tests fail with E0433 on `geo_tiles` and `cargo test` runs no doctests. Write `["cdylib", "rlib"]`.

code

toml · 7 lines
toml
[package]
name = "geo-tiles"
version = "0.4.2"
edition = "2024"

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

go deeper

for a junior

Recall that a library builds as a Rust library by default, and that cdylib and staticlib exist for code called from other languages.

for a middle

Explain what each value emits and who links it, and why a cdylib-only list breaks the package's own binaries, integration tests and doctests.

for a senior

Spot the silent failure: a cdylib-only change can pass review while doctests stop running, so pair cdylib with rlib whenever Rust code in the package uses the library.

for a principal

When a crate serves foreign hosts, weigh shipping cdylib from the main crate against a thin binding crate that keeps the Rust API and the foreign ABI separate.

## What `crate-type` controls A library target is compiled once, but rustc can write it out in several **crate types**, each suited to a different consumer. In Cargo you choose them with the `crate-type` array in `[lib]` (or in an `[[example]]` table, the only other place the key is allowed; binaries, tests and benches are always the `bin` type). Without the key, a library gets `["lib"]`. | Value | Artifact on macOS / Linux / Windows | Who consumes it | |---|---|---| | `lib` (default) | the compiler-recommended Rust library, today `libgeo_tiles.rlib` | other Rust crates via Cargo | | `rlib` | `libgeo_tiles.rlib` | other Rust crates; carries metadata rustc reads | | `cdylib` | `.dylib` / `.so` / `.dll` | C, C++, Python or JavaScript hosts loading a shared library | | `staticlib` | `.a` / `.a` / `.lib` (MSVC) | a non-Rust program linked statically | | `dylib` | `.dylib` / `.so` / `.dll` | Rust programs that link Rust code dynamically; rarely wanted | | `proc-macro` | left unspecified by the Rust Reference | rustc itself; declare with `proc-macro = true` | Key points behind the table: - An **rlib** is a static Rust library plus the metadata rustc needs to type-check code against it. Everything Rust that depends on your library, inside the package or outside it, links this form. - A **cdylib** is a system dynamic library meant to be loaded from another language. rustc links Rust crates only against the rlib or dylib forms, so Rust code cannot compile against a cdylib. It is also the type a WebAssembly library built for `wasm32-unknown-unknown` uses, which the WebAssembly material covers. - A **staticlib** contains your crate and every upstream dependency, standard library included, so a C build can link one archive. Any system libraries it needs still have to be added to the final link by hand. - For a procedural-macro crate, Cargo wants `proc-macro = true`; writing `crate-type = ["proc-macro"]` builds but warns that the library should only specify `proc-macro = true` instead of setting `crate-type`. ## Stacking values The array lists every artifact to emit from one compilation. A crate that a C++ game engine loads and that also ships Rust tools in the same package writes: ```toml [lib] crate-type = ["cdylib", "rlib"] ``` `cargo build` then leaves both `libgeo_tiles.dylib` and `libgeo_tiles.rlib` in `target/debug` on macOS, and adding `"staticlib"` adds `libgeo_tiles.a`. ## What breaks with `cdylib` alone Setting `crate-type = ["cdylib"]` **replaces** the default instead of adding to it. No rlib is produced, and every Rust consumer inside the package loses its library: 1. Each binary in `src/main.rs` or `src/bin/` fails with `error[E0433]: cannot find module or crate geo_tiles in this scope`, because there is no Rust library to link. 2. Each integration test in `tests/` fails the same way. 3. `cargo test` still runs the library's own unit tests, but it runs **no doctests**: there is no Rust library for rustdoc to link the examples against, and the `Doc-tests` section simply vanishes from the output. 4. Another Rust package that depends on it gets the warning that the package provides no linkable target, then the same E0433. The fix is to list `"rlib"` (or `"lib"`) beside `"cdylib"`. The first three symptoms show up in the package's own CI; the doctest loss is silent, which is why it survives review. ## `crate-type` outside `[lib]` - An `[[example]]` table may set `crate-type` too, for instance `crate-type = ["staticlib"]` to show how a C program links the library; such an example is built with `cargo build --example NAME` rather than run. - Binaries, integration tests and benches are always the `bin` type; on a `[[bin]]` table Cargo rejects the key, reporting that the target is a binary and can't have any crate-types set. - One package still has only one library target, so a crate that needs a Rust API and a separate foreign ABI with different dependencies is usually split into two packages instead of stacking more values. ## Choosing in practice 1. A crate for Rust users only: leave `crate-type` out. 2. A plugin or binding loaded by another language at run time: `["cdylib"]`, plus `"rlib"` whenever the package also has Rust binaries, integration tests or doctests. 3. A library linked into an existing C or C++ executable: `["staticlib"]`, again with `"rlib"` if Rust code in the package uses it. 4. A procedural macro: `proc-macro = true`, nothing else. Which symbols a `cdylib` actually exports (`pub extern "C"` functions marked `#[unsafe(no_mangle)]`) is a language and FFI question; the manifest only decides which files come out.

  • Why does cargo test report no doctests after switching to cdylib?
    Doctests are compiled as small programs that link the library as a Rust crate. A cdylib-only library produces no rlib to link, so Cargo runs the unit tests and skips the doctests without an error. Adding "rlib" to `crate-type` brings them back.
  • What extra work does a staticlib push onto the C side of the build?
    The archive bundles your crate, its Rust dependencies and std, but not the system libraries those need. The C link line must add them; rustc's `--print=native-static-libs` lists them. Exported symbols may also need limiting when the archive goes into a shared library.

  • crate-type = ["cdylib"] adds a shared library on top of the normal Rust library.
  • Binaries in the same package link the library directly from source, whatever its crate-type.
  • A staticlib contains only the crate's own code, not its dependencies.
  • A proc-macro crate should set crate-type = ["proc-macro"] in [lib].
  • crate-type can be set on a [[bin]] table to build a binary as a library.