Note about supported targets

[andrewbaxter]

From #238 (comment)

A note up front about windows builds would be great - I came to the readme and saw “Zero setup” cross compilation and “cross testing” of Rust crates and thought "great!", read the getting started steps, and got a build failure. Adding a warning/note about platforms that aren't zero-config prominently in the readme might reduce the surprise of failures and allow people to avoid searching (closed) issues to find the solution.

I also checked the wiki, but there's nothing there about windows/msvc AFAICT. Would having a section there be a better place for this information?

reply from @Emilgardis

The problem here is that the slightly optimistic claim is only for our supported targets, which we list on the README. Maybe we could add a side-note about unsupported targets but seems unneccessary.

That's fair enough! I agree that the readme is technically correct. I do still think it's still easy for people new to the project to miss that information:

• There's a lot of unqualified suggestions to use cross around the internet and you may arrive at the project assuming the target is supported. The opening really gives the feeling of "if you need to cross compile, this is the tool you want"

• There's no mention of supported targets until more than halfway down the long readme

• It's hard to notice something missing

• The supported targets section has a ton of qualification. What does C++ mean? or QEMU? There's entries there with N/A in multiple columns, maybe those aren't supported and listed in the table to show that? You can read it, not understand the details, and come to the conclusion that that section is for advanced users.

• I think what "supported" means isn't clear:

  "A target is considered as “supported” if cross can cross compile a “non-trivial” (binary) crate, usually Cargo, for that target."

  The qualification here also could lead to other interpretations: This could mean that unlisted targets are still able to compile trivial crates, or maybe compiling Cargo is a perfectionist goal and msvc works pretty well but wasn't able to achieve that specific goal. I can't directly connect this definition to needing to manually build an image, and cross can compile stuff for msvc once you set up the image which seems like it might fit the definition.

I don't have a strong opinion here, but if adding a note gets some misguided people on the right track it might reduce the number of issues/discussions in the long run.