Allow crustls to be used as an rlib dependency

[sagebind]

We are interested in enabling the rustls TLS backend from within curl-rust, the Rust bindings for libcurl, so that Rust code that depends on curl can opt-in to using rustls as the TLS backend using a Cargo feature. One potential way for us to implement this is for the crustls crate to allow being built as an rlib dependency and to depend on it via Cargo in order to expose the appropriate symbols in the binary.

This PR adds the required metadata that we would need for this to work after some initial testing, but in order to publish this as a supported feature we would need crustls to itself also be published to Crates.io.

Is this unusual use-case something you would be willing to officially support in crustls? If so then crustls would need to have its releases published to Crates.io. If not then that's OK as well as we have other options for implementing this in curl-rust (though not quite as convenient). I'd totally understand if this isn't something you want to maintain. I also realize that this is all very early in curl+rustls support and it might be too early to make this decision.

Here is the corresponding curl-rust PR that demonstrates how this would be used: alexcrichton/curl-rust#374. For example, this exposes DEP_CRUSTLS_INCLUDE for curl-rust to access crustls.h to pass into the libcurl build.

[jsha]

Thanks for the pull request! Yep, I think supporting rust->curl->crustls->rustls in curl-rust would be great. Nice way to get a lot of the Rust ecosystem using rustls without too much work. I'll review this in a little bit.

[sagebind]

@jsha Any updates on this?

[jsha]

Thanks for the ping. I'm still interested in this, just need to find some time to read up on rlibs.

[jsha]

Reading up on the links manifest key:

When using the links key, the package must have a build script, and the build script should use the rustc-link-lib instruction to link the library.

I see the build script, but no rustc-link-lib. Why is that?

[sagebind]

This is a bit of a unique situation because crustls exposes a C API which doesn't use name mangling, so only one instance of crustls should exist in a dependency tree. This is effectively what links does, is it declares that the crate includes a non-mangled API of some sort. If Cargo tried to use more than one instance of crustls in a dependency tree somewhere, then you would get unclear link-time errors due to symbol names being used more than once.

This is most commonly used when writing Rust bindings to a C library -- you want to make sure that the C library is only linked once since it uses global symbol names. In this common scenario, you would use rustc-link-lib which is equivalent to passing -l to the compiler in order to link to the external library, and this would specify what to link to and how.

However we have a more rare situation here, C bindings to a Rust library, which is the opposite. Normally you wouldn't distribute such bindings via Cargo and you would use more C-oriented ways of doing things, but in this case we want to use Cargo to link two C libraries together.

I can't find many examples of doing this, but one example is how the curl-sys crate depends on ther openssl-sys crate; It does this purely so that it can pull in OpenSSL headers and support linking to it so that it is available for libcurl to use, which is built and linked by curl-sys. We're sort of using Cargo as a C dependency manager in this scenario.

The reason why we use links but without rustc-link-lib is because crustls is effectively a C library and should be treated as such for Cargo's resolution rules, but in fact is itself written in Rust and does not really need to link to a libcrustls.so; it provides the symbols itself.

[jsha]

Thanks for the PR, and for the extra details. Merging now; I'd like to check in with the rustls folks about naming before I push a crate. Will ping you when that's done.

[sagebind]

Awesome, thanks!