Problem

Either this is just my misunderstanding and/or different terminology in Nix, or the docs on crosscompilation here are wrong/misleading.

Proposal

I'm coming from the Bazel world where we also have have host, target and build (well, there it's called execution but whatever) platforms. The docs state that the host is the platform the target is run on. I believe this is incorrect. At least it misaligns with the terminology used in Bazel.

I believe it would be more appropriate to document crosscompilation something like this:

• The host platform is the machine that invokes the build. For instance the developers laptop.
• The build platform is the machine that executes the build. For instance a remote compile server.
• The target platform is the machine that runs the final executable. For instance a mobile device.

For most users, host, build and executable will always be the same: We are building software for ourselves by ourselves, always on the same machine.

If host and target are the same, but build is different, we might be in a situation where for instance a developer requests a remote execution server to create an executable for them. For instance because they are on a low-end device and the remote build server is a high-end device.

If host and build are the same, but target is different, we might be in a situation where a developer builds a mobile app locally.

If build and target are the same, but host is different, we are likely building a tool that is part of a toolchain that runs on the build platform. For instance a compiler that is built using other, lower level compilers for later (or immediate) use by the build platform.

(IMO it is incorrect to state that the target platform is the most irrelevant platform. It is in fact the host platform that is least relevant to the build, since it is just the platform that says "hello build platform please give me executable X for target platform Y".)

I've encountered this because I think the cross compilation support in nixpkgs is a bit unintuitive. I feel like nixpkgs is mixing up platforms and configurations a bit and this might be a reason why e.g. the LLVM stdenvs are so hard to get working everywhere.

Maybe it would be worth considering a differentiation between platforms and toolchain configurations, similar to how Bazel does it. Every time I try to cross-compile something I have to build like half the world, which shouldn't be necessary because e.g. a Clang on x86-unknown-linux-gnu should be able to build libc++ for x64-unknown-linux-musl without first requiring a Clang built for musl. I might be doing something wrong, but my experiments with this would always first build a specific clang for musl, which should be unnecessary.

To me, attributes like platform.isDarwin make sense, but platform.useLLVM seems rather unintuitive to me: Whether we use LLVM as C++ toolchain for stdenv is part of a toolchain configuration and not really related to any platform. We can switch back and forth rather easily between Clang and GCC, i.e. we can choose whether we want to use LLVM or not, but we can't choose our operating system in the same way. We also can't choose our hardware with the same flexibility.

I hope this was not too verbose to read 😅 I kinda feel like the LLVM stdenv is running into the same issues that caused Bazel to deprecate crosstool and instead use Platforms/ToolchainTransitions/Configurations.

Checklist

• checked latest Nixpkgs manual (source) and latest NixOS manual (source)
• checked open documentation issues for possible duplicates (potentially related Rename dependency attributes #28327 Add documentation for emulators feature in cross infra #106375)
• checked open documentation pull requests for possible solutions

cc @rrbutani