rust-lang / rust-lang/docs.rs

crates using unstable cargo feature `bindeps` are not buildable in docs.rs

Open
#2,710 6 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

A-builds E-easy
Dominant language
Rust
Stars
1.2k
Forks
233
Avg merge
11h 35m
Merged PRs (30d)
60

Description

Crate name

protoc-plugin-by-closure

Build failure link

https://docs.rs/crate/protoc-plugin-by-closure/0.1.6/builds/1612629

Additional details

Hello! First of all, thanks for fixing #2542 ! Thanks to this fix, I could go deeper why my crate does not build in docs.rs.
I think I found the reason, but this might be not trivial...

Background

My relatively simple crate fails to build in docs.rs.
My crate has one special thing: Using cargo's unstable feature "Artifact dependencies" in my Cargo.toml.
You don't need to know the detail about this feature. Just please remember that by enabling this feature, Cargo.toml accepts a new attribute artifact = ... in the dependencies:

[dependencies]
bar = { version = "1.0", artifact = "staticlib" }

Of course, without explicitly enabling the feature by cargo command flag (-Z bindeps), this Cargo.toml fails to compile.

docs.rs document says we can add the cargo command line flags using [package.metadata.docs.rs] table's cargo-args = ... field in my Cargo.toml, but it turned out this is not enough.

My investigation

(In my understanding) When docs.rs builds a crate, it invokes many cargo command internally, and there are 2 ways to do this:

  1. Explicitly invoking the cargo command using a ::rustwide::cmd::Command struct constructed by RustwideBuilder::prepare_command() function.
  2. Implicit cargo invocations done in Rustwide library code. For example, when Rustwide is preparing for the build command, it is running cargo fetch command internally.

The problem is the second case. In this case, our custom cargo command line param -Z bindeps is not passed, and it seems to be no way to do so.
This is resulting in my crate's build error even though I'm setting the cargo-args flag in my Cargo.toml.

Unresolved questions

There are another way to specify the unstable cargo flag: Using the .cargo/config.toml file. My crate contains this file too, but it seems to be ignored when Rustwide is running cargo commands. Why?

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading src/docbuilder/rustwide_builder.rs around the build preparation code and rustwide's prepare.rs around the cargo fetch invocation. Trace whether cargo-args from [package.metadata.docs.rs] or .cargo/config.toml reaches implicit cargo commands. Done means establishing how unstable flags should apply consistently and documenting or reproducing the behavior with the protoc-plugin-by-closure build failure.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
build-system
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.