linux target does not appear in docs.rs even `targets` in metadata is set

Crate name

xingapi

Build failure link

https://docs.rs/crate/xingapi/0.3.3/builds/465678

Additional details

After I released 0.3.0, I noticed that doc for x86_64-unknown-linux-gnu target is missing in docs.rs. But I was able to build the documentation locally with that target. Anyway, I've released some new versions to fix these issues.

0.3.1

• Use ignore attribute for markdown code blocks to fix doc tests in Linux

0.3.2

• Do not use ignore attribute for markdown code blocks (now doc tests fail)
• Make doc tests disabled in Cargo.toml (All cargo tests except doc tests succeed)
• Make examples compilable in Linux

0.3.3

• Remove Windows-specific markdown code blocks in cross platform module (doc tests succeed)
• Make doc tests enabled in Cargo.toml

None of these attempts to fix the problem have been successful. targets and default-target in Cargo.toml already set. Could someone please tell me what I am doing wrong? I don't even know where and how to view the build failure log.

[Nemo157]

Unfortunately build logs for non-default targets are not currently recorded (#787).

I've checked the logs on the server and it did build the docs for x86_64-unknown-linux-gnu, but then didn't appear to add the files to the database. I wonder if there's a bug in docs.rs about building the host target as a non-default target.

[Nemo157]

Yes, this is wrong:

docs.rs/src/docbuilder/rustwide_builder.rs

Lines 659 to 662 in 78e2992

	if target != HOST_TARGET {
	cargo_args.push("--target".into());
	cargo_args.push(target.into());
	};

We only want to treat the host target as the --target-less target when we're doing a default-platform build. In fact I think we can get rid of this altogether, and always pass --target, since we already handle the default-platform being in a subdirectory fine for the other targets, so we should make the build server agnostic to which target it is running on.

[jyn514]

In fact I think we can get rid of this altogether, and always pass --target,

No, that breaks proc-macros. See #422.

We only want to treat the host target as the --target-less target when we're doing a default-platform build.

Can you explain this? Why would we pass --target for the host? I'm not sure I understand the cause of the bug ...

[Nemo157]

No, that breaks proc-macros. See #422.

Then we can keep that workaround specifically for proc-macros (I assume that all targets except the host fail with proc-macros?).

Can you explain this?

When we are building for the default-platform we want the docs to be in target/docs/, so we either have default-platform == host and don't pass the --target flag to cargo so the docs will naturally end up there; or default-platform != host, so we have to pass --target then move the docs from target/{{default-platform}}/docs into target/docs.

When we are building for a non-default platform we want the docs to be in target/{{platform}}/docs, normally this is platform != host so we pass --targetand the docs end up in the right location; in the case where we have a non-default platform == host we don't pass --target so the docs end up in target/docs, then we check for target/{{platform}}/docs and see it doesn't exist and assume this platform simply has no docs.

Both of these codepaths already handle --target {{host}} correctly always (outside the proc-macro issue). The alternative fix would be to make the non-default platform build more complicated by having it check for platform == host and moving target/docs into target/{{platform}}/docs when the non-default platform is the host.

[jyn514]

Then we can keep that workaround specifically for proc-macros (I assume that all targets except the host fail with proc-macros?).

They would compile fine except cargo neglects to pass them RUSTDOCFLAGS: rust-lang/cargo#7677

Both of these codepaths already handle --target {{host}} correctly always (outside the proc-macro issue). The alternative fix would be to make the non-default platform build more complicated by having it check for platform == host and moving target/docs into target/{{platform}}/docs when the non-default platform is the host.

I see. But we'll have to do that for proc-macros anyway, right? Does it make sense to set a non-host target for proc-macros?

[jyn514]

Err well I guess cross compiling proc-macros is already broken so it doesn't hurt to break them a little more.

@Nemo157 Could you trigger the rebuild from 0.3.0 to 0.3.3 version? I want to check if the problem is solved.

[Nemo157]

Requeued those versions, and 0.3.3 at least appears to have linux docs available.