-
-
Notifications
You must be signed in to change notification settings - Fork 12.7k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Revamp cross-compilation docs #127115
base: master
Are you sure you want to change the base?
Revamp cross-compilation docs #127115
Conversation
@domenkozar wow, I didn't know nix.dev covered cross-compilation, thanks! Recently heard the podcast as well :) |
It's quite recent, added yesterday :) Great work with these changes! Looks good to me. |
@ianthehenry I saw you mentioned the cross-compilation section of Nixpkgs in your blog post, I agree the way the section is currently structured is confusing as well and I only managed to make heads or tails of it from various sources online by @matthewbauer, discussions with @Ericson2314 and diving head-first into adding cross-compilation support for a few new targets. Would appreciate any suggestions and/or feedback in this WIP PR. You also may want to check out the nix.dev tutorial on cross-compilation. This section is poignant:
|
@ianthehenry I also highly recommend you join our Matrix channels so you can see what the community is up to and ask questions when they arise. |
@siraben You may have seen this post already, but just in case: the first and most confusing explanation of cross-compilation in the manual is actually in Chapter 6. Trying to read that section was the primary source of my frustration in the summary (ctrl-F "offset"). The actual cross-compilation chapter made better reading, for the most part, although the section on bootstrapping completely lost me. That said, I admire any effort to clarify it, and I think the changes you've made so far certainly do increase the legibility a bit. For me I think that a concrete example would be very helpful -- I tried to cross-compile a trivial package and was unable to. I don't know if I was doing something completely wrong, if I just got unlucky, if Linux is not a reasonable target platform, or what. (I expect that cross-compilation mostly exists for microcontrollers, but that's harder for someone like me (who just wants to see how it works) to experiment with.) |
b99535b
to
5233112
Compare
7767b2d
to
04ba794
Compare
There are tons of use cases for cross-compilation. Here are two that you might not have noticed:
There is a proposal (#21471) to make all compiles be cross-compiles, in order to avoid having two separate codepaths for every package. Even if you don't use cross-compilation, planning for it helps clarify build-time/run-time distinctions quite a bit. |
Still think it's valuable to update cross-compilation updates, but might not have time this summer to get around to the whole thing... |
Maybe we can merge it as-is and incrementally do some of the suggestions at a later PR? |
| Type of compilation | Condition | | ||
|----------------------------|-------------------------| | ||
| native compilation | build == host == target | | ||
| cross-compilation | build /= host == target | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is wrong; "cross compilation" is ambiguous: it can mean either
build /= host == target
or
build == host /= target
Indeed, this is exactly the reason why nixpkgs doesn't have a stdenv.isCross
. It's an ambiguous term.
Nixpkgs follows the [conventions of GNU autoconf](https://gcc.gnu.org/onlinedocs/gccint/Configure-Terms.html). We distinguish between 3 types of platforms when building a derivation: _build_, _host_, and _target_. In summary, _build_ is the platform on which a package is being built, _host_ is the platform on which it will run. The third attribute, _target_, is relevant only for certain specific compilers and build tools. Using this terminology, we can summarize the different types of compilation as follows: | ||
|
||
| Type of compilation | Condition | | ||
|----------------------------|-------------------------| | ||
| native compilation | build == host == target | | ||
| cross-compilation | build /= host == target | | ||
| Canadian cross-compilation | build /= host /= target | | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nixpkgs follows the [conventions of GNU autoconf](https://gcc.gnu.org/onlinedocs/gccint/Configure-Terms.html). We distinguish between 3 types of platforms when building a derivation: _build_, _host_, and _target_. In summary, _build_ is the platform on which a package is being built, _host_ is the platform on which it will run. The third attribute, _target_, is relevant only for certain specific compilers and build tools. Using this terminology, we can summarize the different types of compilation as follows: | |
| Type of compilation | Condition | | |
|----------------------------|-------------------------| | |
| native compilation | build == host == target | | |
| cross-compilation | build /= host == target | | |
| Canadian cross-compilation | build /= host /= target | | |
Nixpkgs follows the [conventions of GNU autoconf](https://gcc.gnu.org/onlinedocs/gccint/Configure-Terms.html). We distinguish between 3 types of platforms when building a derivation: _build_, _host_, and _target_. In summary, _build_ is the platform on which a package is being built, _host_ is the platform on which it will run. The third attribute, _target_, is relevant only for certain specific compilers and build tools. |
@@ -62,15 +69,17 @@ The exact schema these fields follow is a bit ill-defined due to a long and conv | |||
|
|||
: This is, quite frankly, a dumping ground of ad-hoc settings (it's an attribute set). See `lib.systems.platforms` for examples—there's hopefully one in there that will work verbatim for each platform that is working. Please help us triage these flags and give them better homes! | |||
|
|||
Using these attributes, the build process of a package can change depending on the situation, for instance, when cross-compiling, one may want to apply specific patches or disable tests. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Using these attributes, the build process of a package can change depending on the situation, for instance, when cross-compiling, one may want to apply specific patches or disable tests. | |
Using these attributes, the build process of a package can change depending on the situation. |
- Tests are already disabled when
!buildPlatform.canExecute hostPlatform
- We generally try really hard to avoid conditionally applying patches, because conditionally-applied patches tend to get broken by version bumps and never noticed.
@@ -123,6 +132,9 @@ software floating point emulation. `libgcc` would be a "target→ *" dependency | |||
|
|||
Some frequently encountered problems when packaging for cross-compilation should be answered here. Ideally, the information above is exhaustive, so this section cannot provide any new information, but it is ludicrous and cruel to expect everyone to spend effort working through the interaction of many features just to figure out the same answer to the same common problem. Feel free to add to this list! | |||
|
|||
#### How do I test cross-compilation using emulation? {#cross-qa-emulation} | |||
Compile the package and run `nix-shell -p qemu`, then run `qemu-system-<arch>` where `<arch>` is the architecture of interest. Alternatively, Nixpkgs has some logic to dispatch to the right emulator, see [\#106375](https://github.com/NixOS/nixpkgs/issues/106375) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Probably better to actually document lib.systems.emulatorFor
than to point to a github issue...
Motivation for this change
I want this to be an interactive process with the community. Cross-compilation is one of Nixpkgs' greatest strengths, but the docs do not do it justice. In particular:
WIP for now
Things done
sandbox
innix.conf
on non-NixOS linux)nix-shell -p nixpkgs-review --run "nixpkgs-review wip"
./result/bin/
)