Docs.rs: Add support for more targets

[rubberduck203]

Crate name: stm32f3-discovery
Build failure link: https://docs.rs/crate/stm32f3-discovery/0.1.2/builds/212158

Additional details:

Crates targeting ARM Cortex-M processors fail to build because docs.rs currently doesn't support the thumbv* targets.

This can be worked around by setting the default target to x86_64-unknown-linux-gnu per https://github.com/stm32-rs/stm32f3xx-hal/issues/46.

[package.metadata.docs.rs]
default-target = "x86_64-unknown-linux-gnu"

Possibly related to https://github.com/rust-lang/docs.rs/issues/343#issuecomment-525888748

[Disasm]

Earlier docs were built with the explicit --target x86_64-unknown-linux-gnu parameter and now this parameter is not passed. For some projects like embedded ones, cargo takes target from .cargo/config and it happens to be different from x86_64-unknown-linux-gnu and not installed.

[jyn514]

@Disasm We stopped passing --target because it broke proc-macros, it's unrelated to #343.

Thanks for pointing out .cargo/config, I wouldn't have noticed that. Would ignoring configuration in .cargo/config solve your issue? Or does your crate sometimes depend on that config to build?

[jyn514]

Also I suppose this is as good a place as any to talk about additional targets. I would like to support more targets, but it requires some significant refactors on our ends. Adapted from a chat I had on Discord:

Targets are currently a little complicated. We have 5 targets that we build which are documented only here on the site. These are mostly kept in sync with Tier 1 platforms.

Additionally, we unconditionally build each crate for each target. This is about to change in #532. Until we stop building each crate for each target, storage and build costs don't make it practical to add more targets. Resolved by #632.

Once #532 is merged, I think adding more targets might be interesting under the following conditions:

1. They would only be built if explicitly requested (part of #632 )
2. They would have to be supported by rustup without any special effort on our part

Note that build-scripts and proc-macros will still be broken when passed --target, although I don't expect that to be a big deal once cross-compiling is opt-in instead of opt-out.

[rubberduck203]

They would have to be supported by rustup without any special effort on our part

Just to clarify, you mean anything that could be rustup target add-ed? I think that’s very reasonable. Once I’ve added the thumbv7em-none-eabihf target, I can run cargo doc locally without issue.

[jyn514]

Just to clarify, you mean anything that could be rustup target add-ed?

Yes, that's right. Ok great, in that case this is definitely doable, it's just going to be a while (at least a month, probably closer to 3). Watch #550 and #532 if you're interested :)

[jyn514]

I have a possible solution that might help by making new targets opt-in instead of opt-out. No promises, but I hope to have it implemented in the next 2 to 3 weeks. After that is merged I just need to add code that allows non-tier 1 targets to be added at runtime, which will be a fair amount of work but unlikely to break anything.

[rubberduck203]

That’s promising news. Thanks for the effort you’ve put into this!

[jyn514]

@rubberduck203 I'm running into some trouble trying to build thumbv7em-none-eabihf targets locally.

# grab a random crate (https://crates.io/crates/hexponent) (this takes less than a second to build)
$ git clone https://gitlab.com/pythondude325/hexponent && cd hexponent
$ rustup "target" "add" "--toolchain" "nightly" "thumbv7em-none-eabihf"
info: downloading component 'rust-std' for 'thumbv7em-none-eabihf'
info: installing component 'rust-std' for 'thumbv7em-none-eabihf'
$ cargo +nightly build
   Compiling hexponent v0.5.0 (/home/joshua/src/hexponent)
    Finished dev [unoptimized + debuginfo] target(s) in 1.27s
$ cargo +nightly doc --target thumbv7em-none-eabihf
 Documenting hexponent v0.5.0 (/home/joshua/src/hexponent)
error[E0463]: can't find crate for `std`
  |
  = note: the `thumbv7em-none-eabihf` target may not be installed

I run into the same trouble building with stable instead of nightly.

[rubberduck203]

That crate requires features from std.
The none part of the target triple indicates it's a bare metal target, without an OS.
Currently, the Rust std lib relies on an OS being available.

Try this crate, which doesn't rely on the std lib..

$ git clone https://github.com/rubberduck203/switch-hal.git && cd switch-hal
$ cargo +nightly doc --target thumbv7em-none-eabihf
    Updating crates.io index
    Checking nb v0.1.2
    Checking void v1.0.2
 Documenting nb v0.1.2
 Documenting void v1.0.2
    Checking embedded-hal v0.2.3
 Documenting embedded-hal v0.2.3
 Documenting switch-hal v0.3.2 (/Users/rubberduck/src/temp/switch-hal)
    Finished dev [unoptimized + debuginfo] target(s) in 3.83s