docs.rs fails in 0.9.2,0.9.3

[akiradeveloper]

https://docs.rs/crate/lol-core/0.9.2

# build log
[INFO] running `Command { std: "docker" "create" "-v" "/home/cratesfyi/workspace/builds/lol-core-0.9.2/target:/opt/rustwide/target:rw,Z" "-v" "/home/cratesfyi/workspace/builds/lol-core-0.9.2/source:/opt/rustwide/workdir:ro,Z" "-v" "/home/cratesfyi/workspace/cargo-home:/opt/rustwide/cargo-home:ro,Z" "-v" "/home/cratesfyi/workspace/rustup-home:/opt/rustwide/rustup-home:ro,Z" "-e" "SOURCE_DIR=/opt/rustwide/workdir" "-e" "CARGO_TARGET_DIR=/opt/rustwide/target" "-e" "DOCS_RS=1" "-e" "CARGO_HOME=/opt/rustwide/cargo-home" "-e" "RUSTUP_HOME=/opt/rustwide/rustup-home" "-w" "/opt/rustwide/workdir" "-m" "3221225472" "--cpus" "3" "--user" "1001:1001" "--network" "none" "ghcr.io/rust-lang/crates-build-env/linux@sha256:bb5b0feb4f87116a4ea905b7ff5bf5b85913db05e9f0fbc1abdd3168928d9075" "/opt/rustwide/cargo-home/bin/cargo" "+nightly" "rustdoc" "--lib" "-Zrustdoc-map" "--all-features" "-Z" "unstable-options" "--config" "build.rustdocflags=[\"--cfg\", \"docsrs\", \"-Z\", \"unstable-options\", \"--emit=invocation-specific\", \"--resource-suffix\", \"-20221207-1.67.0-nightly-01fbc5ae7\", \"--static-root-path\", \"/-/rustdoc.static/\", \"--cap-lints\", \"warn\", \"--disable-per-crate-search\", \"--extern-html-root-takes-precedence\"]" "--offline" "-Zunstable-options" "--config=doc.extern-map.registries.crates-io=\"https://docs.rs/{pkg_name}/{version}/x86_64-unknown-linux-gnu\"" "-j3" "--target" "x86_64-unknown-linux-gnu", kill_on_drop: false }`
[INFO] [stderr] WARNING: Your kernel does not support swap limit capabilities or the cgroup is not mounted. Memory limited without swap.
[INFO] [stdout] 112a11e350b2d8f21b243eaeae6afaf88e4908bf8163aada90d64d85131a6dd1
[INFO] running `Command { std: "docker" "start" "-a" "112a11e350b2d8f21b243eaeae6afaf88e4908bf8163aada90d64d85131a6dd1", kill_on_drop: false }`
[INFO] [stderr]    Compiling lol-core v0.9.2 (/opt/rustwide/workdir)
[INFO] [stderr]     Checking rocksdb v0.19.0
[INFO] [stderr]     Checking serde_bytes v0.11.7
[INFO] [stderr] error: failed to run custom build command for `lol-core v0.9.2 (/opt/rustwide/workdir)`
[INFO] [stderr] 
[INFO] [stderr] Caused by:
[INFO] [stderr]   process didn't exit successfully: `/opt/rustwide/target/debug/build/lol-core-65b0e25c0d7e86b0/build-script-build` (exit status: 1)
[INFO] [stderr]   --- stdout
[INFO] [stderr]   cargo:rerun-if-changed=proto/lol-core.proto
[INFO] [stderr]   cargo:rerun-if-changed=proto
[INFO] [stderr] 
[INFO] [stderr]   --- stderr
[INFO] [stderr]   Error: Custom { kind: Other, error: "protoc failed: Unknown flag: --experimental_allow_proto3_optional\n" }
[INFO] [stderr] warning: build failed, waiting for other jobs to finish...
[INFO] running `Command { std: "docker" "inspect" "112a11e350b2d8f21b243eaeae6afaf88e4908bf8163aada90d64d85131a6dd1", kill_on_drop: false }`
[INFO] running `Command { std: "docker" "rm" "-f" "112a11e350b2d8f21b243eaeae6afaf88e4908bf8163aada90d64d85131a6dd1", kill_on_drop: false }`
[INFO] [stdout] 112a11e350b2d8f21b243eaeae6afaf88e4908bf8163aada90d64d85131a6dd1

[akiradeveloper]

Error: Custom { kind: Other, error: "protoc failed: Unknown flag: --experimental_allow_proto3_optional\n" }

experimental_allow_proto3_optional is outdated as of 2022/5/28

protocolbuffers/protobuf#9684

[akiradeveloper]

I remove the flag in 0.9.3 but still it makes an error

Error: Custom { kind: Other, error: "protoc failed: lol_core.proto:79:12: Explicit 'optional' labels are disallowed in the Proto3 syntax. To define 'optional' fields in Proto3, simply remove the 'optional' label, as fields are 'optional' by default.\nlol_core.proto:88:12: Explicit 'optional' labels are disallowed in the Proto3 syntax. To define 'optional' fields in Proto3, simply remove the 'optional' label, as fields are 'optional' by default.\n" }

I guess this is because protoc used by docrs is too old because optional is valid in the newer protoc (protobuf v3.14 or later).

[akiradeveloper]

rust-lang/docs.rs#1741

I use prost-build to build proto files in build.rs and in its turn it uses system proto compiler. There are some fileds in my proto files that marked as optional. The optional has been added in proto 3.12 and stabilized in 3.15. So it seems that build machines/images contains outdated protoc

[akiradeveloper]

I think this will not resolve any time soon. Losing doc is really damaging for this project.

So we need to work around. The below should work.

1. Do not run build.rs in doc.rs. This should be done by conditional compilation.
2. Generate the auto generated file under src/proto and commit it.

Below is the example of conditional compilation.

if std::env::var("DOCS_RS").is_ok() {
    // ... your code here ...
}

[akiradeveloper]

Resolved in v0.9.5.