Why is crate-type = ["cdylib"] enabled by default?

[elisw93]

In the "using Rust from Python" section from the PyO3 documentation it shows an example of using maturin init which puts this configuration in the Cargo.toml file:

# "cdylib" is necessary to produce a shared library for Python to import from.
#
# Downstream Rust code (including code in `bin/`, `examples/`, and `tests/`) will not be able
# to `use string_sum;` unless the "rlib" or "lib" crate type is also included, e.g.:
# crate-type = ["cdylib", "rlib"]
crate-type = ["cdylib"]

I have been working on a Rust extension module which has crate-type = ["cdylib", "rlib"] set in order to build tests and benchmarks. Recently while debugging some (unrelated) linking issues, I found that removing "cdylib" from crate-type has no effect on the build process whatsoever, for my purposes. It seems that Maturin doesn't care if "cdylib" is missing:

(.env) $ cat Cargo.toml
[package]
name = "maturintest"
version = "0.1.0"
edition = "2024"

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
[lib]
name = "maturintest"

[dependencies]
pyo3 = "0.28.2"

(.env) $ maturin develop
🔗 Found pyo3 bindings
🐍 Found CPython 3.11 at [...]
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.02s
📦 Built wheel for CPython 3.11 to [...]
✏️  Setting installed package as editable
🛠 Installed maturintest-0.1.0

(.env) $ python
>>> import maturintest
>>> maturintest.sum_as_string(3, 5)
'8'

Which left me wondering:

• Is it safe to remove crate-type = ["cdylib"] from my Cargo.toml if I'm always using maturin build/maturin develop to build my extension modules?
• Why is this included by default in the PyO3 documentation and by maturin init?

[cookesan]

Your result makes sense with current maturin, but I would still keep cdylib in the manifest.

It is not that maturin never cares. The current build path can recover when the Cargo target is a normal Rust library: if no cdylib target is declared, maturin looks for a lib-like target and, on Rust 1.64 or newer, invokes Cargo with --crate-type cdylib. That explains why maturin develop still worked in your test.

The manifest default is still useful because it makes the crate's intent explicit to Cargo and to tools that are not maturin. A plain cargo build will not otherwise produce the Python-loadable dynamic library artifact. Maturin's own packaging path also still expects to collect a cdylib artifact at the end.

For an extension module that also needs Rust tests, benches, examples, or downstream Rust imports, I would use:

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

That gives maturin the extension module artifact and keeps a Rust library artifact available for normal Rust tooling. I would only remove cdylib if you are deliberately relying on maturin as the only supported build path for the extension.

[elisw93]

Thanks, based on your comments I was able to go looking in the code and find this "lib-like target" heuristic:

maturin/src/compile.rs

Lines 134 to 141 in 1a8d72f

	// No `crate-type = ["cdylib"]` in `Cargo.toml`
	// Let's try compile one of the target with `--crate-type cdylib`
	let lib_target = root_pkg.targets.iter().find(|target| {
	target
	.crate_types
	.iter()
	.any(|crate_type| LIB_CRATE_TYPES.contains(crate_type))
	});

Looking around this file, there's also some hints that suggest removing "cdylib" will break universal2 builds on macos. Not sure about other edge cases.

maturin/src/compile.rs

Lines 213 to 217 in 1a8d72f

	if build_type == CrateType::CDyLib {
	anyhow!(
	"Cargo didn't build an aarch64 cdylib. Did you miss crate-type = [\"cdylib\"] \
	in the lib section of your Cargo.toml?",
	)

I don't build universal2 wheels, but I also don't want to break them for no good reason, so keeping "cdylib" in the configuration seems like a good idea for this reason alone.