Home • Explore • Blog • Models • CI
☰



nixpkgs
8th chunk of `doc/stdenv/cross-compilation.chapter.md`
d6145f5594a2e7c93874d110cdd61500d3f2bc96481ee8f00000000100000b07
To make this work, we "splice" together the six `pkgsFooBar` package sets and have `callPackage` actually take its arguments from that. This is currently implemented in `pkgs/top-level/splice.nix`. `mkDerivation` then, for each dependency attribute, pulls the right derivation out from the splice. This splicing can be skipped when not cross-compiling as the package sets are the same, but still is a bit slow for cross-compiling. We'd like to do something better, but haven't come up with anything yet.

### Bootstrapping {#ssec-bootstrapping}

Each of the package sets described above come from a single bootstrapping stage. While `pkgs/top-level/default.nix`, coordinates the composition of stages at a high level, `pkgs/top-level/stage.nix` "ties the knot" (creates the fixed point) of each stage. The package sets are defined per-stage however, so they can be thought of as edges between stages (the nodes) in a graph. Compositions like `pkgsBuildTarget.targetPackages` can be thought of as paths to this graph.

While there are many package sets, and thus many edges, the stages can also be arranged in a linear chain. In other words, many of the edges are redundant as far as connectivity is concerned. This hinges on the type of bootstrapping we do. Currently for cross it is:

1.  `(native, native, native)`

2.  `(native, native, foreign)`

3.  `(native, foreign, foreign)`

In each stage, `pkgsBuildHost` refers to the previous stage, `pkgsBuildBuild` refers to the one before that, and `pkgsHostTarget` refers to the current one, and `pkgsTargetTarget` refers to the next one. When there is no previous or next stage, they instead refer to the current stage. Note how all the invariants regarding the mapping between dependency and depending packages' build host and target platforms are preserved. `pkgsBuildTarget` and `pkgsHostHost` are more complex in that the stage fitting the requirements isn't always a fixed chain of "prevs" and "nexts" away (modulo the "saturating" self-references at the ends). We just special case each instead. All the primary edges are implemented is in `pkgs/stdenv/booter.nix`, and secondarily aliases in `pkgs/top-level/stage.nix`.

::: {.note}
The native stages are bootstrapped in legacy ways that predate the current cross implementation. This is why the bootstrapping stages leading up to the final stages are ignored in the previous paragraph.
:::

If one looks at the 3 platform triples, one can see that they overlap such that one could put them together into a chain like:
```
(native, native, native, foreign, foreign)
```

If one imagines the saturating self references at the end being replaced with infinite stages, and then overlays those platform triples, one ends up with the infinite tuple:
```
(native..., native, native, native, foreign, foreign, foreign...)
Title: Bootstrapping Stages and Package Set Splicing for Cross-Compilation
Summary
This chunk details how `pkgsFooBar` package sets are 'spliced' together using `pkgs/top-level/splice.nix` to allow `callPackage` to retrieve appropriate dependencies. While efficient for native builds, this splicing can be slow for cross-compilation. It then explains that these package sets are derived from a series of bootstrapping stages, coordinated by `pkgs/top-level/default.nix` and fixed by `pkgs/top-level/stage.nix`. For cross-compilation, these stages form a linear chain (e.g., `(native, native, native)` progressing to `(native, foreign, foreign)`). Within this chain, attributes like `pkgsBuildHost` refer to previous stages, `pkgsHostTarget` to the current, and `pkgsTargetTarget` to the next, with special handling for `pkgsBuildTarget` and `pkgsHostHost`. The primary implementation resides in `pkgs/stdenv/booter.nix`, with a note that native stages use legacy bootstrapping methods. The text concludes by visualizing the platform triples as a continuous, overlapping chain.