cross-compilation.chapter.md: give examples of all depFooBar cases#166991
Conversation
This commit describes the "->" notation for dependency types in greater detail, and uses g++ to provide examples of all six cases (although the host->target and target->target examples are a bit artificial). It also adds three more rows to the table for the "->*" dependency types for non-compiler-like packages; these dependency types were already present in the documentation but the "*" was not really explained. Lastly, this commit adds a hyperlink to the table from the place where it is mentioned in the "specifying dependencies" chapter.
symphorien
left a comment
There was a problem hiding this comment.
thanks for contributing to documentation!
|
@a-m-joseph thanks for the contribution! You might be interested in #127115 as well. |
Co-authored-by: Ben Siraphob <bensiraphob@gmail.com>
| | target → * | target | (none) | | ||
| | target → target | target | target | | ||
|
|
||
| Let's use `g++` as an example to make this table clearer. `g++` is a C++ compiler written in C. Suppose we are building `g++` with a `(build, host, target)` platform triple of `(foo, bar, baz)`. This means we are using a `foo`-machine to build a copy of `g++` which will run on a `bar`-machine and emit binaries for the `baz`-machine. |
There was a problem hiding this comment.
I would say "was", because recent versions do use C++!
There was a problem hiding this comment.
Yikes. Yeah, it's been a long long long time since I worked on GCC. My first draft of this PR used gcj (the java frontend) as an example, and then I found out that it had been removed six years ago.
I'll find another example of a gcc frontend that isn't writing in its own language and submit a follow-up PR. I think the go frontend (gccgo) has this property. The Rust frontend is (AFAICT) out-of-tree. Let me know if you can think of a better frontend, especially if there is one that links a JIT to its output.
|
|
||
| * Since `g++` is written in C, the `gcc` compiler used to compile it is a "build→ host" dependency of `g++` with a triple of `(foo, foo, bar)`. This compiler runs on the build platform and emits code for the host platform. | ||
|
|
||
| * `gcc` links against the build platform's `glibc` C library, which is a "build→ *" dependency with a triple of `(foo, foo, *)`. Since it is a library, not a compiler, it has no "target". |
There was a problem hiding this comment.
We could even go into more detail and say (?, foo, *) because the build platform doesn't matter. Afterwards, then say it is also foo by convention.
If you call https://github.com/NixOS/nixpkgs/blob/master/pkgs/stdenv/booter.nix manually, you can in fact do more complicated bootstraps with more than 3 total platforms.
There was a problem hiding this comment.
We could even go into more detail and say
(?, foo, *)because the build platform doesn't matter. Afterwards, then say it is alsofooby convention.
Thanks, I'll include that in the follow-up PR.
Also, would you be offended if I changed foo, bar, and baz to B, H, and T respectively? The example is already very complicated and I feel like having to remember that "foo is the build, bar is the host, and T is the target" without some kind of mnemonic is an extra burden on the reader.
There was a problem hiding this comment.
If you call https://github.com/NixOS/nixpkgs/blob/master/pkgs/stdenv/booter.nix manually, you can in fact do more complicated bootstraps with more than 3 total platforms.
Cool, I'm still working my way through the fine details of that and the {#ssec-stdenv-dependencies} chapter of the manual. If I come across any documentation quirks there I'll submit a PR, but if so it will certainly be much smaller than this one.
There was a problem hiding this comment.
Also, would you be offended if I changed foo, bar, and baz to B, H, and T respectively? The example is already very complicated and I feel like having to remember that "foo is the build, bar is the host, and T is the target" without some kind of mnemonic is an extra burden on the reader.
Mmm so my idea with foo bar and baz was that they are (stand-ins for) concrete platforms. Whereas "build", "host" and "target" I really want to make sure people understand are just local names from the perspective of a single derivation, relative to it.
A lot of build systems fall in the trap of their being a global "build", "host" and "target", and then mistakes of various sorts happen.
There was a problem hiding this comment.
In the slides linked below, I used some humorous concrete platforms: i386-linux, powerpc-illlumos, sparc-windows, mips-darwin, riscv-sel4.
Perhaps something like that might be better than foo, bar, baz while continuing to not imply there are is "global" build, host, and target?
|
Thank you for doing this! I like this going to detail on the reference. BTW from https://github.com/ClangBuiltLinux/llvm-distributors-conf-2021 @sternenseemann and I have some slides https://github.com/ClangBuiltLinux/llvm-distributors-conf-2021/blob/main/slides/llvm-toolchains-in-nixpkgs.pdf expanded from my nix con 2017 that could be useful if we want to add SVGs. |
This commit describes the "->" notation for dependency types in
greater detail, and uses g++ to provide examples of all six cases
(although the host->target and target->target examples are a bit
artificial).
It also adds three more rows to the table for the "->*" dependency
types for non-compiler-like packages; these dependency types were
already present in the documentation but the "*" was not really
explained.
Lastly, this commit adds a hyperlink to the table from the place where
it is mentioned in the "specifying dependencies" chapter.