How to publish a crate that links to a native library?

[KevinT3Hu]

I have a crate that needs to link to a native library to generate the ffi code, and those using the crate is expected to have this lib installed for it to properly build. But I could not figure out how to publish it and have the docs generated on docs.rs since the environment on docs.rs do not have the lib installed.

Also, to build the native lib itself requires downloading some dependencies online so it does not work by including it as a git submodule and compile it at build time.

[alice]

Some crates just have an option to build from source without having it installed and use that on docs.rs, but if that's not possible for you, then here's one way you can go about it:

First, ask docs.rs to set a flag when compiling your code. Add this to your Cargo.toml:

[package.metadata.docs.rs]
rustdoc-args = ["--cfg", "docsrs"]

Then, using your local install, you generate the bindings you want to show up on docs.rs and check it into your git repository. For example, you might have files src/lib.rs and src/docsrs_bindings.rs. After that, you use conditional compilation to use the special file on docs.rs like this:

// src/lib.rs
#![allow(non_upper_case_globals)]
#![allow(non_camel_case_types)]
#![allow(non_snake_case)]

#[cfg(not(docsrs))]
include!(concat!(env!("OUT_DIR"), "/bindings.rs"));

#[cfg(docsrs)]
include!("docsrs_bindings.rs");

You can apply a similar change to your build.rs to have it not run bindgen on docs.rs.

To build it locally, you can use

RUSTDOCFLAGS="--cfg docsrs" cargo doc

Note that there's also a RUSTFLAGS and rustc-args where you can pass the flag. Flags there are applied to dependences, whereas rustdoc flags are applied to the current crate. So crates that depend on the -sys crate may need to use rustc-args instead of rustdoc-args for it to work.

[KevinT3Hu]

In fact, docs.rs would automatically set the docsrs cfg and the env var DOCS_RS.
Anyway, this is a perfect solution for my problem.