"rustup target [add, install]" should guide towards successful compilation.

[ralfbiedert]

The README says:

Note that rustup target add only installs the Rust standard library for a given target. There are typically other tools necessary to cross-compile, particularly a linker. For example, to cross compile to Android the Android NDK must be installed. In the future, rustup will provide assistance installing the NDK components as well.

Witnessing myself and my colleagues, most users will:

• not read this part of the README
• just try rustup target [add, install] arm-linux-xxx and see what happens.
• then spend 30 - 60 minutes puzzling together what exactly they need to download and how to configure ~/.cargo/config.

Having everything work out of the box would obviously be the best case.

In lack of that, since the steps for a given host x target combination are similar, there should be clear and simple instructions printed right at the end of an rustup installation, at least for the most common combinations.

What I would have liked (simplified):

> rustup target install aarch64-linux-android

info: component 'rust-std' for target 'aarch64-linux-android' installed.

warning: To successfully compile for `aarch64-linux-android` on `macos` you also 
need the linker from a cross compilation toolchain. In the majority of cases these steps 
are needed:

INSTALL TOOLCHAIN
- Run `brew install [package]`
- (Alternatively) install [URL] 

CONFIGURE TOOLCHAIN
- Locate the file `make-standalone-toolchain.sh`, part of the toolchain.
- Run `make-standalone-toolchain.sh --arch=aarch64-linux-android`

CONFIGURE CARGO
- In your `.cargo/config` set:

[target.aarch64-linux-android]
linker = "[PATH_TO_STANDALONE_TOOLCHAIN]/aarch64-linux-android/bin/aarch64-linux-android-clang"

Other host x target combinations should have these steps modified accordingly.

If the steps for a given host x target are unclear / ambiguous, rustup should print exactly that as part of the INSTALL TOOLCHAIN and CONFIGURE TOOLCHAIN instructions.

[geraldgg]

Finally I found what I was missing! So yes, I agree that this guide should be given somewhere.

[kinnison]

Unfortunately the specific requirements change from platform to platform and over time.

If you were to spearhead a page (e.g. on the rust forge or nursery sites) where you explain how to handle toolchains for various targets, then we could possibly add a "you may want to read " message to some of these targets.

[AndreKR]

Unfortunately the specific requirements change from platform to platform and over time.

Isn't the purpose of rustup to provide a working toolchain?

I'm eager to replace all my Go projects with Rust, but I regularly need to compile on Windows for Linux and Linux ARM and on Linux for Windows. With Go everything works out of the box, but with Rust I haven't managed to get anything to compile that isn't the host platform.

If rustup can't (for licensing reasons or whatever) download a working toolchain itself, it should at least point to the exact project that is needed for the specific case. For example "you need to install GCC" can mean at least 6 different things (4 different mingw-w64 projects, TDM-GCC or Cygwin).

They might all work, but I don't want to try them all and I only need one, so I would really like rustup to tell me exactly what it needs.

By the way (from #1483 (comment)):

• not read this part of the README

I actually did read that part when I first started my experiments with Rust. But that doesn't help me at all, it's near impossible to google reliable information what needs to be done to get Rust to cross-compile.

[kinnison]

Unfortunately the specific requirements change from platform to platform and over time.
Isn't the purpose of rustup to provide a working toolchain?

Not per-se no. The purpose is to allow the installation of Rust toolchains. It's a combinatorial explosion for us to expect to understand how to tell everyone how to deal with cross-compilers.

If rustup can't (for licensing reasons or whatever) download a working toolchain itself, it should at least point to the exact project that is needed for the specific case. For example "you need to install GCC" can mean at least 6 different things (4 different mingw-w64 projects, TDM-GCC or Cygwin).

This is exactly why I requested someone spearhead an effort to document what they can on the forge.

They might all work, but I don't want to try them all and I only need one, so I would really like rustup to tell me exactly what it needs.

My exact goal is that rustup will direct you to the above document where someone who actually knows what the right answer is can document it.

[rahulbansal16]

@kinnison I am trying to figure out how to package toolchain for cross-compilation.
so I started with compiling for windows on ubuntu.

I followed the documentation.
Installed cargo target add x86_64-px-windows-msvc
When I execute the command cargo build --target=x86_64-px-windows-msvc.

I get the below error.

The error is looking for link.exe on the ubuntu platform.
Even if I download the the VS tools How will the ubuntu platform run them?

Do I have to package the tools on the windows machine and ship to the ubuntu?
If Yes, Can you provide some example etc?

[AndreKR]

I don't think the x86_64-pc-windows-msvc toolchain can cross-compile, only x86_64-pc-windows-gnu can.

In addition to switching the toolchain you might have to set [target.x86_64-pc-windows-gnu] linker = "x86_64-w64-mingw32-gcc" in your Cargo config (not Cargo.toml!).

[rahulbansal16]

In the documentation, there is a mention of https://doc.rust-lang.org/nightly/rustc/platform-support.html x86_64-px-windows-msvc . Why do you think it is mentioned in the cross-compilation doc?

How were you able to figure out that x86_64-pc-windows-msvc don't cross-compile? Is it some naming convention, hit, and trial, through the official website, etc that you did? It becomes so confusing to figure out which tool needs which dependency and the google search does not provide much information.

I am trying to setup distributed sccache and was going through the documentation
https://github.com/mozilla/sccache/blob/master/docs/DistributedQuickstart.md#using-custom-toolchains

I am unable to understand How the executable of one platform will help in the compilation on the remote build server with different os? Do let me know if you have any idea about it.

[rbtcollins]

I think we should steer folk to the cross project actually and keep rustup focused on an excellent installation mechanism. if we can ever get to the point of installing all the dependencies to merely compile for the same host automatically, then we can talk about cross-compilations dependencies.

@rahulbansal16 we mention the platform support URL in the cross compilation doc of rustup to help make that documentation visible; not to claim that any particular combination is supported to a particular level - that is up to rustc and cargo's behaviour.

I think making the x86_64-pc-windows-msvc target cross-compile successfully would be a great idea; you may be able to do that using qemu binary emulation; but there may be more requirements than that- possibly even code changes to rustc.

[AndreKR]

I think we should steer folk to the cross project

As far as I know cross needs to be able to run Docker containers and since a lot of build jobs already run inside Docker containers themselves, the cross project is of very limited use.

if we can ever get to the point of installing all the dependencies to merely compile for the same host automatically

I strongly believe that should be a goal, and it seems we're actually getting closer to that? Sure, there are exceptions because of licensing issues (msvc), but the other targets already bring their necessary dependencies. There is even now the bundled LLD, so cross-compiling for Linux on Windows now works fine (as long as all crates use only Rust).

By the way, it might be a bin unorthodox but I recently came across an idea (here for Go, but works the same for Rust). The language Zig includes a self-contained LLVM-based C++ compiler for a variety of targets and apparently can easily be used to cross compile C++ sources on any system.

Personally I value "building just works" much higher than "you can pick and choose your own toolchain", so bundling the Zig executable to make cross-compilation "just work" seems quite attractive. (And you could still pick and choose your toolchain by fiddling with your Cargo config.)

[rbtcollins]

My understanding is that cross supports running within docker as long as you give it the docker socket. So, no problem.

I agree that bringing in all the compile pre-reqs is a goal, but Rustup hasn't moved on that at all since I've been contributing to it: we don't install debs, rpms, etc. Having copies of the platforms preferring components that the Rust-lang project is allowed to distribute is I guess one route forward, but one that redistributors like Redhat and Canonical will not embrace easily.

That said zig is super interesting and teaching rustc to use zig would be very interesting, and Rustup can certainly manage to install zig tarballs, as we install other ones.

We may want to teach rustup how to tell versions of zig separate to versions of rustc to save peoples bandwidth, since I suspect zig is not so small. Thats something that would require some cross-team design and implementation work.

Its a bit sad that zig implements the windows-gnu toolchain not windows-msvc though; we've had performance problems in the past in the compiled binaries on Windows, and for 'just works' avoiding those cases is probably pretty important.

[AndreKR]

My understanding is that cross supports running within docker as long as you give it the docker socket. So, no problem.

Giving a container the Docker socket (or running a privileged container, which is the other common technique to run "Docker in Docker") is basically giving the container full access to the host - not something you would do on a shared CI runner, because then why even bother with a container, just run the build job directly on the host.

That said zig is super interesting and teaching rustc to use zig would be very interesting, and Rustup can certainly manage to install zig tarballs, as we install other ones.

👍

[AndreKR]

Regarding the state of things concerning "successful compilation" I'd like to link to this issue I recently opened. I eventually resolved it myself by finding the one obscure working toolchain, and this isn't even about cross compiling, this is just about building a Rust application with SQLite on Windows.

[rbtcollins]

We should probably split this bug out into some related facets. Cross compilation is a different case to regular builds. That said, I think the diagnostic label on that bug is appropriate - rust itself does get to see the the original error, so is best placed to steer folk towards diagnostic guides, even though this is an error below the layers Rust itself owns.

[nseguias]

This is fixed by doing rustup self uninstall, then curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh and selecting the aarch64-apple-darwin instead of the default one. I chose the stable one but might work with different target versions. I manually deleted the .cargo folder, not sure if the command to uninstall does it for you.

Macbook Pro M2