Rust supports a number of crate types to control whether we are building a binary or a library, and what kind of library. The dylib and staticlib crate types are named very similarly, so it is easy to assume that they also behave in a similar way, with the only difference between dynamic vs static linking. However, this is far from true: staticlib creates a C-style static library that can be deployed as an artifact and linked without any further rustc involvement; dylib is basically a dynamic rlib, i.e., it still needs a bunch of Rust-specific processing until it becomes a regular C-style dynamic library (or static library, or binary). The dynamic-linking equivalent to staticlib is cdylib. Overall, the main library crate types are arranged as follows:

(* @bjorn3 points out that rlib isn't fully the same as a Rust-style staticlib, so take this table with a grain of salt... it may be a good thing that rlib is not called rstaticlib.)

Needless to say, this is quite confusing. See https://rust-lang.github.io/rfcs/1510-cdylib.html for some history of how we got here. Also note that lib is essentially an alias for rlib (but not deprecated). The documentation just says that it's the most suitable library format for the current target, which makes sense -- it's the bin vs lib distinction. In that sense, the most confusing name among them all is staticlib as it is the only one where the lack of a c/r prefix somehow means "C-style". OTOH, in the "do what I want" sense, dylib is confusing for the reasons spelled out in the RFC. Ultimately I think the only recourse here is to be more explicit: if you care about the actual linking details (and not just about "bin" vs "lib"), then please just spell out whether you want something that behaves like a normal C-style library (cdylib, cstaticlib) or not. In practice, you'll almost certainly want a C-style library, but due to dylib existing (and to a lesser extent due to lib existing), that can't be the meaning of "no prefix".

I think we should clean this up, by renaming dylib to rdylib and staticlib to cstaticlib. (We did a straw poll for whether we should do only some of the renames, and the results were fairly clear, see Zulip.) Concretely, the plan would be:

1. Introduce the new names as aliases: the new name rdylib behaves like the existing dylib, and the new name cstaticlib behaves like the existing staticlib.
2. Write a blog post announcing the general plan, and update the docs to prefer the new names.
3. [only after a long time has passed, if ever] show a deprecation warning when using the old names.
   • By far the name with the biggest misuse risk is dylib, for the reasons spelled out above and in the aforementioned RFC. cstaticlib only exists for consistency. So maybe we should only warn against dylib. I don't think we have to fully commit to a concrete plan for this yet, it's going to be at least a year until we actually deprecate anything anyway.

With all of this done, the table would look like

Much better :)

This is a pretty big change so I expect it will need FCP (with t-compiler and t-lang).