Add guidance around sharing cdylibs between Rust crates?

[workingjubilee]

Publishers are likely to have an expectation that their crate is easy to use :: by other Rust authors. However publishing the cdylib crate type does not publish crates that are ready to be easily used by cargo without considerable more fuss than other crate types.

It is unlikely this is intentional. If people do not understand what they are doing, they should be prevented from doing this in their cargo publish command and offered some kind of option to --override if they do indeed have some sort of legitimate purpose.

This recently became visible in an attempt to use emgyrz/cubic_spline#2 so it is not an idle hypothesis that this is a problem.

I am willing to attempt drafting this feature if it is considered desirable.

[joshtriplett]

There are entirely legitimate reasons to publish a cdylib, though, such as providing a library with a C-compatible interface. (For instance, incrementally porting an existing C library to Rust.)

Perhaps we could detect if you're building a cdylib but you don't appear to export any C functions (e.g. non-mangled symbol names)? There are still legitimate reasons for such a cdylib, but that's rare enough that it wouldn't be unreasonable to warn people by default.

[workingjubilee]

That is why I did not recommend banning publishing cdylibs altogether. I should note that the crate that raised this question appears to have worked fine for its purposes (a wasm demo) but also appears to not export C functions.

And I had read the existing documentation about cdylibs before but had not come to the conclusion that it would be impossible to use such a crate in my own Rust applications (e.g. if it had some public function that remained useful purely in a Rust context), as it was not obvious to me that the compilation model for cdylibs would work the way it did for this person. I do not believe I would have made different conclusions.

So I do acknowledge there are reasons to do something, but I do not believe proper usage and understanding is discoverable at the current moment, so I believe discovery should be introduced as close as humanly possible to the actual publishing step.

[workingjubilee]

I have answered this exact same question again for someone else. This time, they were the author of both the using and original crate, so it was an easy fix, and I had experience with the problem, so it was quick, but I expect at least 20 other people have had this problem since it's really common for people to try to use Rust for wasm (for good reasons!).

I no longer believe "not exporting any functions" is going to be terribly useful as a heuristic since if I understand correctly, you DO export functions via wasm-bindgen. However, I think I got overly fixated on a single solution and provided an incomplete image of the problem. Allow me to attempt to respecify the problem:

1. Someone writes a crate, and then they annotate it with wasm_bindgen, to make it usable from wasm. These directions also prompt them to mark it as a cdylib. They may or may not understand the ramifications of doing so, even after reading the documentation so far on cdylibs, but they're told it has to be in order to be for it to be wasm'd, so they do it. They publish the crate or privately reuse it.
2. Someone, possibly including that same author, attempts to add the cdylib to their deps and then use the library in an ordinary Rusty fashion.
3. They run a cargo {build,check,test}.
4. Their build reports it successfully compiled the crate.
5. Yet their build fails, apparently mysteriously, with error[E0432]: unresolved import {crate}, even though so far they've done everything right to use a crate from Rust.

match get_help() {
   Some(HelpfulWasmer) => deps.patch["crate-type"] += ["rlib"],
   Some(HelpfulRustacean) => unimplemented!("oh, WASM? I don't know..."),
   _ => panic!("oh noooooooooooooooo"),
}

re: the Rust Reference documentation so far for cdylibs

s--crate-type=cdylib, #[crate_type = "cdylib"] - A dynamic system library will be produced. This is used when compiling a dynamic library to be loaded from another language. This output type will create *.so files on Linux, *.dylib files on macOS, and *.dll files on Windows.

This is somewhat opaque if dll is just a file type that breaks your software if it isn't there (which is probably fine for the reference but means this is pretty rough for less technical users who just want to quickly get to wasming...), and even if you know what a C ABI is, that doesn't mean you'll put together "so Rust doesn't have access to an rlib anymore" yourself, which is what you're used to since that is the default behavior in the absence of a crate-type key.