Summary

Add a new crate type accepted by the compiler, called cdylib, which corresponds to exporting a C interface from a Rust dynamic library.

Motivation

Currently the compiler supports two modes of generating dynamic libraries:

  1. One form of dynamic library is intended for reuse with further compilations. This kind of library exposes all Rust symbols, links to the standard library dynamically, etc. I’ll refer to this mode as rdylib as it’s a Rust dynamic library talking to Rust.
  2. Another form of dynamic library is intended for embedding a Rust application into another. Currently the only difference from the previous kind of dynamic library is that it favors linking statically to other Rust libraries (bundling them inside). I’ll refer to this as a cdylib as it’s a Rust dynamic library exporting a C API.

Each of these flavors of dynamic libraries has a distinct use case. For examples rdylibs are used by the compiler itself to implement plugins, and cdylibs are used whenever Rust needs to be dynamically loaded from another language or application.

Unfortunately the balance of features is tilted a little bit too much towards the smallest use case, rdylibs. In practice because Rust is statically linked by default and has an unstable ABI, rdylibs are used quite rarely. There are a number of requirements they impose, however, which aren’t necessary for cdylibs:

  • Metadata is included in all dynamic libraries. If you’re just loading Rust into somewhere else, however, you have no need for the metadata!
  • Reachable symbols are exposed from dynamic libraries, but if you’re loading Rust into somewhere else then, like executables, only public non-Rust-ABI functions need to be exported. This can lead to unnecessarily large Rust dynamic libraries in terms of object size as well as missed optimization opportunities from knowing that a function is otherwise private.
  • We can’t run LTO for dylibs because those are intended for end products, not intermediate ones like (1) is.

The purpose of this RFC is to solve these drawbacks with a new crate-type to represent the more rarely used form of dynamic library (rdylibs).

Detailed design

A new crate type will be accepted by the compiler, cdylib, which can be passed as either --crate-type cdylib on the command line or via #![crate_type = "cdylib"] in crate attributes. This crate type will conceptually correspond to the cdylib use case described above, and today’s dylib crate-type will continue to correspond to the rdylib use case above. Note that the literal output artifacts of these two crate types (files, file names, etc) will be the same.

The two formats will differ in the parts listed in the motivation above, specifically:

  • Metadata - rdylibs will have a section of the library with metadata, whereas cdylibs will not.
  • Symbol visibility - rdylibs will expose all symbols as rlibs do, cdylibs will expose symbols as executables do. This means that pub fn foo() {} will not be an exported symbol, but #[no_mangle] pub extern fn foo() {} will be an exported symbol. Note that the compiler will also be at liberty to pass extra flags to the linker to actively hide exported Rust symbols from linked libraries.
  • LTO - this will disallowed for rdylibs, but enabled for cdylibs.
  • Linkage - rdylibs will link dynamically to one another by default, for example the standard library will be linked dynamically by default. On the other hand, cdylibs will link all Rust dependencies statically by default.

Drawbacks

Rust’s ephemeral and ill-defined “linkage model” is… well… ill defined and ephemeral. This RFC is an extension of this model, but it’s difficult to reason about extending that which is not well defined. As a result there could be unforeseen interactions between this output format and where it’s used.

Alternatives

  • Originally this RFC proposed adding a new crate type, rdylib, instead of adding a new crate type, cdylib. The existing dylib output type would be reinterpreted as a cdylib use-case. This is unfortunately, however, a breaking change and requires a somewhat complicated transition plan in Cargo for plugins. In the end it didn’t seem worth it for the benefit of “cdylib is probably what you want”.

Unresolved questions

  • Should the existing dylib format be considered unstable? (should it require a nightly compiler?). The use case for a Rust dynamic library is so limited, and so volatile, we may want to just gate access to it by default.