maliput docs in docs.rs is not working

[francocipollone]

Summary

Verify why documentation at https://docs.rs/crate/maliput/0.1.0 isn't building correctly

Definition of Done

docs.rs should host maliput documentation

[francocipollone]

https://docs.rs/crate/maliput/0.1.0/builds/1183671

It is failing because for building the docs it actually is building everything, that means that it is executing build.rs at maliput-sdk that brings maliput binaries via BCR.

• Is it possible to indicate prerequisites for that build? like for example bazel installation?
• Is it possible to build documentation of maliput package without actually building the dependencies (maliput-sdk)?

[francocipollone]

We can try to replicate locally the execution following this: https://forge.rust-lang.org/docs-rs/add-dependencies.html
We can docker pull that image and run the documentation generation as it is run for docs.rs and debug the issue.

Also note here that https://github.com/rust-lang/crates-build-env/blob/master/README.md#linux the docs are generated using an image based on Ubuntu 22.04 and we actually need to use Ubuntu 20 so it might be failing because of this

[francocipollone]

Tried using the docker image that is used for building the docs:

docker pull ghcr.io/rust-lang/crates-build-env/linux:latest

Then I run a container and tried installing cargo. This is the complete output:

oot@9f83b6e3cad2:/maliput-rs# RUST_BACKTRACE=full cargo build
   Compiling maliput-sdk v0.1.2 (/maliput-rs/maliput-sdk)
   Compiling link-cplusplus v1.0.9
   Compiling cxxbridge-macro v1.0.115
   Compiling cxx-build v1.0.115
error: failed to run custom build command for `maliput-sdk v0.1.2 (/maliput-rs/maliput-sdk)`
note: To improve backtraces for build dependencies, set the CARGO_PROFILE_DEV_BUILD_OVERRIDE_DEBUG=true environment variable to enable debug information generation.

Caused by:
  process didn't exit successfully: `/maliput-rs/target/debug/build/maliput-sdk-3a0bcfa66e231fae/build-script-build` (exit status: 101)
  --- stdout
  cargo:rerun-if-changed=src/lib.rs
  cargo:rerun-if-changed=BUILD.bazel
  cargo:rerun-if-changed=MODULE.bazel

  --- stderr
  thread 'main' panicked at maliput-sdk/build.rs:54:10:
  Failed to generate build script: Os { code: 2, kind: NotFound, message: "No such file or directory" }
  stack backtrace:
     0:     0x5bbb3cf61c66 - std::backtrace_rs::backtrace::libunwind::trace::hd6ffdc229294c06f
                                 at /rustc/25ef9e3d85d934b27d9dada2f9dd52b1dc63bb04/library/std/src/../../backtrace/src/backtrace/libunwind.rs:104:5
     1:     0x5bbb3cf61c66 - std::backtrace_rs::backtrace::trace_unsynchronized::h991f79b6e9960513
                                 at /rustc/25ef9e3d85d934b27d9dada2f9dd52b1dc63bb04/library/std/src/../../backtrace/src/backtrace/mod.rs:66:5
     2:     0x5bbb3cf61c66 - std::sys_common::backtrace::_print_fmt::hf4ebe716f7ccda10
                                 at /rustc/25ef9e3d85d934b27d9dada2f9dd52b1dc63bb04/library/std/src/sys_common/backtrace.rs:68:5
     3:     0x5bbb3cf61c66 - <std::sys_common::backtrace::_print::DisplayBacktrace as core::fmt::Display>::fmt::h410d4c66be4e37f9
                                 at /rustc/25ef9e3d85d934b27d9dada2f9dd52b1dc63bb04/library/std/src/sys_common/backtrace.rs:44:22
     4:     0x5bbb3cf84210 - core::fmt::rt::Argument::fmt::he0ff0e0e188c0db5
                                 at /rustc/25ef9e3d85d934b27d9dada2f9dd52b1dc63bb04/library/core/src/fmt/rt.rs:142:9
     5:     0x5bbb3cf84210 - core::fmt::write::he40921d4802ce2ac
                                 at /rustc/25ef9e3d85d934b27d9dada2f9dd52b1dc63bb04/library/core/src/fmt/mod.rs:1120:17
     6:     0x5bbb3cf5fadf - std::io::Write::write_fmt::h5de5a4e7037c9b20
                                 at /rustc/25ef9e3d85d934b27d9dada2f9dd52b1dc63bb04/library/std/src/io/mod.rs:1846:15
     7:     0x5bbb3cf61a44 - std::sys_common::backtrace::_print::hd8e2e3f655086663
                                 at /rustc/25ef9e3d85d934b27d9dada2f9dd52b1dc63bb04/library/std/src/sys_common/backtrace.rs:47:5
     8:     0x5bbb3cf61a44 - std::sys_common::backtrace::print::h11c067a88e3bdb22
                                 at /rustc/25ef9e3d85d934b27d9dada2f9dd52b1dc63bb04/library/std/src/sys_common/backtrace.rs:34:9
     9:     0x5bbb3cf62fa7 - std::panicking::default_hook::{{closure}}::h8c832ecb03fde8ea
    10:     0x5bbb3cf62d09 - std::panicking::default_hook::h1633e272b4150cf3
                                 at /rustc/25ef9e3d85d934b27d9dada2f9dd52b1dc63bb04/library/std/src/panicking.rs:292:9
    11:     0x5bbb3cf63438 - std::panicking::rust_panic_with_hook::hb164d19c0c1e71d4
                                 at /rustc/25ef9e3d85d934b27d9dada2f9dd52b1dc63bb04/library/std/src/panicking.rs:781:13
    12:     0x5bbb3cf63312 - std::panicking::begin_panic_handler::{{closure}}::h0369088c533c20e9
                                 at /rustc/25ef9e3d85d934b27d9dada2f9dd52b1dc63bb04/library/std/src/panicking.rs:659:13
    13:     0x5bbb3cf62166 - std::sys_common::backtrace::__rust_end_short_backtrace::hc11d910daf35ac2e
                                 at /rustc/25ef9e3d85d934b27d9dada2f9dd52b1dc63bb04/library/std/src/sys_common/backtrace.rs:171:18
    14:     0x5bbb3cf63064 - rust_begin_unwind
                                 at /rustc/25ef9e3d85d934b27d9dada2f9dd52b1dc63bb04/library/std/src/panicking.rs:647:5
    15:     0x5bbb3cf3a345 - core::panicking::panic_fmt::ha6effc2775a0749c
                                 at /rustc/25ef9e3d85d934b27d9dada2f9dd52b1dc63bb04/library/core/src/panicking.rs:72:14
    16:     0x5bbb3cf3a7b3 - core::result::unwrap_failed::ha188096f98826595
                                 at /rustc/25ef9e3d85d934b27d9dada2f9dd52b1dc63bb04/library/core/src/result.rs:1649:5
    17:     0x5bbb3cf3e8dc - core::result::Result<T,E>::expect::h9af71c6972d3c967
    18:     0x5bbb3cf3c82f - build_script_build::main::h7877877913c3d666
    19:     0x5bbb3cf3fc63 - core::ops::function::FnOnce::call_once::h49f93cdd862aa568
    20:     0x5bbb3cf3b9b6 - std::sys_common::backtrace::__rust_begin_short_backtrace::h3ef1c17603815405
    21:     0x5bbb3cf421a9 - std::rt::lang_start::{{closure}}::hd7d035f74d3d0fde
    22:     0x5bbb3cf5bc11 - core::ops::function::impls::<impl core::ops::function::FnOnce<A> for &F>::call_once::h3f2a75cbf4c937aa
                                 at /rustc/25ef9e3d85d934b27d9dada2f9dd52b1dc63bb04/library/core/src/ops/function.rs:284:13
    23:     0x5bbb3cf5bc11 - std::panicking::try::do_call::h8b4251a3ff07cb79
                                 at /rustc/25ef9e3d85d934b27d9dada2f9dd52b1dc63bb04/library/std/src/panicking.rs:554:40
    24:     0x5bbb3cf5bc11 - std::panicking::try::h7c5a033d33a17020
                                 at /rustc/25ef9e3d85d934b27d9dada2f9dd52b1dc63bb04/library/std/src/panicking.rs:518:19
    25:     0x5bbb3cf5bc11 - std::panic::catch_unwind::hb11e6d2bc85d3f56
                                 at /rustc/25ef9e3d85d934b27d9dada2f9dd52b1dc63bb04/library/std/src/panic.rs:142:14
    26:     0x5bbb3cf5bc11 - std::rt::lang_start_internal::{{closure}}::h0f4b130784f05f2d
                                 at /rustc/25ef9e3d85d934b27d9dada2f9dd52b1dc63bb04/library/std/src/rt.rs:148:48
    27:     0x5bbb3cf5bc11 - std::panicking::try::do_call::ha5e1e15d954bfd38
                                 at /rustc/25ef9e3d85d934b27d9dada2f9dd52b1dc63bb04/library/std/src/panicking.rs:554:40
    28:     0x5bbb3cf5bc11 - std::panicking::try::h1ebdd47dd0e39c8c
                                 at /rustc/25ef9e3d85d934b27d9dada2f9dd52b1dc63bb04/library/std/src/panicking.rs:518:19
    29:     0x5bbb3cf5bc11 - std::panic::catch_unwind::hbc815fbc36dbbcd0
                                 at /rustc/25ef9e3d85d934b27d9dada2f9dd52b1dc63bb04/library/std/src/panic.rs:142:14
    30:     0x5bbb3cf5bc11 - std::rt::lang_start_internal::h4d236095b69a230b
                                 at /rustc/25ef9e3d85d934b27d9dada2f9dd52b1dc63bb04/library/std/src/rt.rs:148:20
    31:     0x5bbb3cf42187 - std::rt::lang_start::h7df672f4a9055c7d
    32:     0x5bbb3cf3dd25 - main
    33:     0x7fadf6e78d90 - <unknown>
    34:     0x7fadf6e78e40 - __libc_start_main
    35:     0x5bbb3cf3aa75 - _start
    36:                0x0 - <unknown>
warning: build failed, waiting for other jobs to finish...

thread 'main' panicked at maliput-sdk/build.rs:54:10:

That's the line for running bazel build command.
So assumed that bazel isn't installed of course and then the build script fails.

Note: Important to note that the docker image is based on Jammy image (Ubuntu 22) meaning that most probably that it will fail maliput compilation (never tried on ubuntu 22)

[francocipollone]

I looked at https://github.com/tensorflow/rust/tree/master

They have:

• tensorflow-sys:
  A package that builds tensorflow using bazel. They have a feature called "private-docs-rs" that is passed to the docs.rs configuration.
  When that feature is enabled, they are not running bazel build.

• tensorflow-sys-runtime
  They create bindings in runtime using bindgen, when they do tensorflow::load they are then building the bindings. Not in compile time.

• tensorflow
  Relies on tensorflow-sys and tensorflow-sys-runtime and add a Rust API.

I tried to the same however in our case:

• maliput-sdk: When "private-docs-rs" is used we skip the build bazel part.
• maliput-sys: For building, it needs the header files for creating the bindings. This is done in build.rs, not in runtime. So we need maliput-sdk's binaries.
• maliput: Uses ffi bindings to create a rust API on top.

Sadly, we can't do the same for maliput packages unless we change to use the same approach when creating the bindings, which is not ideal at all.

[francocipollone]

Closing. After #75 is done the docs linked in crates.io for the creates will refer to our hosted documentation

• https://maliput.github.io/maliput-rs/