Make the rust_icu crates available on docs.rs

[filmil]

The rust_icu build process is very specific, requiring a preinstalled ICU library or a docker container. docs.rs does not know about this and tries to build with vanilla cargo. This fails, and as result no documentation appears on docs.rs.

Example here:
https://docs.rs/crate/rust_icu_uenum/0.0.4/builds/211223

An example 'sys' crate that works is sodium-sys. It has a custom build.rs script.
https://github.com/rustyhorde/sodium-sys/blob/master/build.rs

[filmil]

Some advice given on rust-lang/docs.rs#655

[filmil]

Looks like I managed to make changes that will allow rust_icu to compile on docs.rs.
Instructions here: https://forge.rust-lang.org/docs-rs/add-dependencies.html

One potential issue, the compilation model requires a README.md file must be available, and not be a symlink.

Another, I'm seeing some flakiness in bindgen invocation, exemplified in errors like this, which sometimes happen:

2020/03/27 00:18:07 [INFO] rustwide::cmd: [stderr] /usr/include/x86_64-linux-gnu/gnu/stubs.h:7:11: fatal error: 'gnu/stubs-32.h' file not found

But, the upside, once the two changes land, we may be well positioned to have the docs compilation succeed.

[jyn514]

2020/03/27 00:18:07 [INFO] rustwide::cmd: [stderr] /usr/include/x86_64-linux-gnu/gnu/stubs.h:7:11: fatal error: 'gnu/stubs-32.h' file not found

This looks like you're trying to cross-compile for x86-unknown-linux-gnu (docs.rs builds all tier 1 targets by default). You can either request crates-build-env to install gcc-multilib (or the clang equivalent) in the build environment, or you can request docs.rs to only build for one target by putting targets = ["x86_64-unknown-linux-gnu"] in your Cargo.toml. See https://blog.rust-lang.org/2020/03/15/docs-rs-opt-into-fewer-targets.html for more details on the second option.

[filmil]

Thanks! Note, this is part of the `docs.rs` canned build environment from: https://forge.rust-lang.org/docs-rs/add-dependencies.html I noticed that the errors are for `*-msvc` cross-compilation target, as well as `i686`. I don't know why `docs.rs` attempts to cross-compile for the sake of building documentation, though it is a fair thing to want to do. F

…

On Thu, Mar 26, 2020 at 5:42 PM Joshua Nelson ***@***.***> wrote: 2020/03/27 00:18:07 [INFO] rustwide::cmd: [stderr] /usr/include/x86_64-linux-gnu/gnu/stubs.h:7:11: fatal error: 'gnu/stubs-32.h' file not found This looks like you're trying to cross-compile for x86-unknown-linux-gnu ( docs.rs builds all tier 1 targets by default). You can either request crates-build-env to install gcc-multilib (or the clang equivalent) in the build environment, or you can request docs.rs to only build for one target by putting targets = ["x86_64-unknown-linux-gnu"] in your Cargo.toml. See https://blog.rust-lang.org/2020/03/15/docs-rs-opt-into-fewer-targets.html for more details on the second option. — You are receiving this because you were assigned. Reply to this email directly, view it on GitHub <#41 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAB4GMDZOS7FL7ZHY3EVNV3RJPZADANCNFSM4KEQF43A> .

[jyn514]

Several crates have different documentation for different platforms, for example https://docs.rs/winapi/. In the past we've had multiple targets on by default, but we're considering making that opt-in in the future for exactly the reasons you've seen here: it sometimes doesn't work and in most cases the documentation is the same. However, we're keeping the targets on by default for now to avoid unnecessarily breaking builds.

[filmil]

Success! See here: https://docs.rs/rust_icu_sys/0.1.2/rust_icu_sys/

I have reasons to think that other crates will become viewable on docs.rs too.