Direct users to crate-type=cdylib in crate-type=dylib documentation

[hanna-kruppe]

The dylib crate type is well known to be misleading and rarely useful (to put it politely) among rustc developers, but if a user reads about crate types in rustc --help, the reference, or the rustc book they won't get much indication of this. This probably contributes to the constant stream of users picking it or recommending it to each other when they really need cdylib. Generally this is only prevented if someone with "insider knowledge" is in the same room when the decision is made, and otherwise only corrected when something breaks and the user seeks help or files a bug report.

I still believe it would be best to deprecate the crate type entirely but since that probably involves more process and pushback, for now I propose to add a note to all the aforementioned documents that says something like:

As with lib, the file produced from a dylib crate can only be consumed by the same version of rustc and is not guaranteed to be in any particular format or contain any symbols that other programs could use. If you wish to produce a dynamic library to be loaded dynamically by Rust programs or linked against by other languages, you need to use the cdylib crate type.

[Mark-Simulacrum]

Should we consider making the stronger move of removing dylib from --help and similar documentation, and perhaps documenting it in a "advanced features" section or something of the rustc user guide book (note: not rustc compiler internals guide).

[hanna-kruppe]

I would not oppose that but I fear that the more aggressive we are about this, the more likely there will be blowback from people who are using it (whether their use case is supported or not) and thus it's more likely we'll need an FCP or something similarly slow. If someone is ready to push that process through to completion, please go ahead, but I can't make that kind of commitment, so I made a smaller proposal.

[Mark-Simulacrum]

I'm also happy with a more minimal solution, just wanted to make sure the idea was noted. I agree that the smaller step is good.