Advice/example on docs.rs strategy

[metasim]

I've just released my first cxx project, wrapping a geospatial C++ library called PDAL. As expected, my docs.rs build is failing because PDAL isn't in the build container. So I'm wondering if there are any good examples of projects that get around this problem without resulting to vendoring the source. Or perhaps that is the best practice here?

If I were just using bindgen I would save off a version of the generated bindings for this purpose, but because the Rust side of the generation happens in #[cxx::bridge] macro, I'm assuming this approach won't work.

The other thing I tried was to disable the build.rs of the -sys sub-crate with a feature flag, but then the non-sys crate doesn't have the definitions it needs.

Any other approaches I should consider, or is vendoring the only viable way. (Does vendoring introduce licensing concerns?).

Thanks!

[dtolnay]

Nothing in cxx_build has any impact on Rust metadata. It only does C++ stuff, which affects linkage but does not affect rustdoc because rustdoc uses metadata-only Rust builds.

You can skip the build script in docs.rs like this:

fn main() {
    println!("cargo:rerun-if-env-changed=DOCS_RS");
    if env::var_os("DOCS_RS").is_some() {
        return;
    }

    // cxx_build stuff
}

[metasim]

@dtolnay Thank you. I misunderstood, thinking that #[cxx::bridge] had to parse the files referenced by the include! directive. Thanks for the explanation.