Add build support for docs.rs

[jeffcharles]

What is the idea?

Add support for building quickjs-wasm-sys and everything depending on it to docs.rs.

What problem does it solve?

Docs.rs is a common place for viewing crate documentation, and at the moment, quickjs-wasm-sys and crates that depend on it like quickjs-wasm-rs do not build successfully on docs.rs.

[jeffcharles]

Surma's changes to the build script were made after the 1.0.0 release of the crate. We need to release a new version of the quickjs-wasm-sys crate to see if the crate will build successfully on docs.rs. If the new version of the crate builds successfully, we can update all of the other crates to use that version of quickjs-wasm-sys and they should build correctly on docs.rs.

[jeffcharles]

Opened #445 to bump quickjs-wasm-sys version in preparation for publishing

[jeffcharles]

quickjs-wasm-sys v1.1.0 has been published. I'm waiting for docs.rs to pick up the new version of the crate and to try building it to confirm it works. If it does, we can proceed with updating the versions of the other Javy crates to also fix their docs.rs pages.

[jeffcharles]

quickjs-wasm-sys v1.1.0 is still failing to build in docs.rs.

https://docs.rs/crate/quickjs-wasm-sys/1.1.0/builds/874424 shows the output. Relevant logs are:

[INFO] [stderr]    Compiling quickjs-wasm-sys v1.1.0 (/opt/rustwide/workdir)
[INFO] [stderr] error: failed to run custom build command for `quickjs-wasm-sys v1.1.0 (/opt/rustwide/workdir)`
[INFO] [stderr] 
[INFO] [stderr] Caused by:
[INFO] [stderr]   process didn't exit successfully: `/opt/rustwide/target/debug/build/quickjs-wasm-sys-07c92e724ddef2eb/build-script-build` (exit status: 1)
[INFO] [stderr]   --- stdout
[INFO] [stderr]   cargo:rerun-if-env-changed=QUICKJS_WASM_SYS_WASI_SDK_PATH
[INFO] [stderr]   cargo:rerun-if-env-changed=QUICKJS_WASM_SYS_WASI_SDK_MAJOR_VERSION
[INFO] [stderr]   cargo:rerun-if-env-changed=QUICKJS_WASM_SYS_WASI_SDK_MINOR_VERSION
[INFO] [stderr] 
[INFO] [stderr]   --- stderr
[INFO] [stderr]   Error: failed to lookup address information: Temporary failure in name resolution

That looks like a DNS failure error message to me. We'll need to do more work to resolve this.

[surma]

Docs.rs might just be blocking network access altogether to prevent abuse.

[jeffcharles]

Confirmed that docs.rs blocks network access, https://docs.rs/about/builds#hitting-resource-limits:

• Network access will not be enabled for any crate.

We can request for Ubuntu packages to be added to the build environment. There is one for wasi-libc. And it should be possible to configure a standard clang install to use that libc as a sysroot. That said, I'm having trouble compiling a basic C program in Ubuntu using upstream clang and wasi-libc. Currently getting a wasm-ld-14: error: unable to find library -lgcc. Not sure why it's calling out to GCC but I have GCC installed so I'm not sure how to resolve that right now.

There is also a disclaimer on the WASI SDK page:

One could also use a standard Clang installation, build a sysroot from the sources mentioned above, and compile with --target=wasm32-wasi --sysroot=/path/to/sysroot. In this scenario, one would also need the libclang_rt.builtins-wasm32.a objects available separately in the release downloads which must be extracted into $CLANG_INSTALL_DIR/$CLANG_VERSION/lib/wasi/.

I tried installing that archive file with no luck. Installing the archive file on the docs.rs build server would not be possible without copying the clang installation (which should be doable) since docs.rs will fail builds that try to write to locations outside the OUT_DIR. But, I'm not sure how to proceed given I can't get a barebones WASI build working on Ubuntu with upstream clang, wasi-libc, and the clang runtime archive installed.

[jeffcharles]

Opened rust-lang/crates-build-env#136 on the build environment to see if the upstream maintainers have any thoughts.

[jeffcharles]

I figured out a way to build WASI source code from C source code. I've opened rust-lang/crates-build-env#137 to add the requisite packages to docs.rs's build environment. We will also need to vendor libclang_rt.builtins-wasm32.a from the WASI SDK releases page (it's only ~100 KB). The clang invocation to get it to work on Ubuntu seems to be clang --target=wasm32-wasi --sysroot=/usr --rtlib=compiler-rt <file>. I'm also expecting we'll need to copy the system clang installation into an OUT_DIR subdirectory to install the clang runtime library since docs.rs forbids changing any files outside of that directory.

[jeffcharles]

I've got a work-in progress on https://github.com/bytecodealliance/javy/compare/jc.docsrs-support?expand=1. It seems to work on an Ubuntu docker container.

[jeffcharles]

rust-lang/crates-build-env#137 was merged but won't be deployed until next week. There is a docker container I can use to test but the setup looks like it may rely on docker-compose which we don't have access to due to Docker Desktop licensing changes. Depending on how other work goes, I might be able to try it later today. Otherwise I'll mark #453 as ready for review after I get back from vacation and we can try with a pre-release version to see if it builds the docs successfully.

[jeffcharles]

Merged #453. Will publish a pre-release of the crate after CI passes to see if docs.rs can build it.

[jeffcharles]

Looks like it worked! https://docs.rs/quickjs-wasm-sys/1.1.1-alpha.1/quickjs_wasm_sys/

Opened #474 to release new versions of all of our library crates.

[jeffcharles]

Merged #474 and published new versions of all crates. I've confirmed that documentation is now building successfully on docs.rs.