pyrox.dev
1<chapter xmlns="http://docbook.org/ns/docbook"
2 xmlns:xlink="http://www.w3.org/1999/xlink"
3 xml:id="chap-cross">
4
5<title>Cross-compilation</title>
6
7<section xml:id="sec-cross-intro">
8 <title>Introduction</title>
9 <para>
10 "Cross-compilation" means compiling a program on one machine for another type of machine.
11 For example, a typical use of cross compilation is to compile programs for embedded devices.
12 These devices often don't have the computing power and memory to compile their own programs.
13 One might think that cross-compilation is a fairly niche concern, but there are advantages to being rigorous about distinguishing build-time vs run-time environments even when one is developing and deploying on the same machine.
14 Nixpkgs is increasingly adopting this opinion in that packages should be written with cross-compilation in mind, and nixpkgs should evaluate in a similar way (by minimizing cross-compilation-specific special cases) whether or not one is cross-compiling.
15 </para>
16
17 <para>
18 This chapter will be organized in three parts.
19 First, it will describe the basics of how to package software in a way that supports cross-compilation.
20 Second, it will describe how to use Nixpkgs when cross-compiling.
21 Third, it will describe the internal infrastructure supporting cross-compilation.
22 </para>
23</section>
24
25<!--============================================================-->
26
27<section xml:id="sec-cross-packaging">
28 <title>Packaging in a cross-friendly manner</title>
29
30 <section>
31 <title>Platform parameters</title>
32 <para>
33 The three GNU Autoconf platforms, <wordasword>build</wordasword>, <wordasword>host</wordasword>, and <wordasword>target</wordasword>, are historically the result of much confusion.
34 <link xlink:href="https://gcc.gnu.org/onlinedocs/gccint/Configure-Terms.html" /> clears this up somewhat but there is more to be said.
35 An important advice to get out the way is, unless you are packaging a compiler or other build tool, just worry about the build and host platforms.
36 Dealing with just two platforms usually better matches people's preconceptions, and in this case is completely correct.
37 </para>
38 <para>
39 In Nixpkgs, these three platforms are defined as attribute sets under the names <literal>buildPlatform</literal>, <literal>hostPlatform</literal>, and <literal>targetPlatform</literal>.
40 All three are always defined as attributes in the standard environment, and at the top level. That means one can get at them just like a dependency in a function that is imported with <literal>callPackage</literal>:
41 <programlisting>{ stdenv, buildPlatform, hostPlatform, fooDep, barDep, .. }: ...buildPlatform...</programlisting>, or just off <varname>stdenv</varname>:
42 <programlisting>{ stdenv, fooDep, barDep, .. }: ...stdenv.buildPlatform...</programlisting>.
43 </para>
44 <variablelist>
45 <varlistentry>
46 <term><varname>buildPlatform</varname></term>
47 <listitem><para>
48 The "build platform" is the platform on which a package is built.
49 Once someone has a built package, or pre-built binary package, the build platform should not matter and be safe to ignore.
50 </para></listitem>
51 </varlistentry>
52 <varlistentry>
53 <term><varname>hostPlatform</varname></term>
54 <listitem><para>
55 The "host platform" is the platform on which a package is run.
56 This is the simplest platform to understand, but also the one with the worst name.
57 </para></listitem>
58 </varlistentry>
59 <varlistentry>
60 <term><varname>targetPlatform</varname></term>
61 <listitem>
62 <para>
63 The "target platform" is black sheep.
64 The other two intrinsically apply to all compiled software—or any build process with a notion of "build-time" followed by "run-time".
65 The target platform only applies to programming tools, and even then only is a good for for some of them.
66 Briefly, GCC, Binutils, GHC, and certain other tools are written in such a way such that a single build can only compile code for a single platform.
67 Thus, when building them, one must think ahead about which platforms they wish to use the tool to produce machine code for, and build binaries for each.
68 </para>
69 <para>
70 There is no fundamental need to think about the target ahead of time like this.
71 LLVM, for example, was designed from the beginning with cross-compilation in mind, and so a normal LLVM binary will support every architecture that LLVM supports.
72 If the tool supports modular or pluggable backends, one might imagine specifying a <emphasis>set</emphasis> of target platforms / backends one wishes to support, rather than a single one.
73 </para>
74 <para>
75 The biggest reason for mess, if there is one, is that many compilers have the bad habit a build process that builds the compiler and standard library/runtime together.
76 Then the specifying target platform is essential, because it determines the host platform of the standard library/runtime.
77 Nixpkgs tries to avoid this where possible too, but still, because the concept of a target platform is so ingrained now in Autoconf and other tools, it is best to support it as is.
78 Tools like LLVM that don't need up-front target platforms can safely ignore it like normal packages, and it will do no harm.
79 </para>
80 </listitem>
81 </varlistentry>
82 </variablelist>
83 <para>
84 The exact schema these fields follow is a bit ill-defined due to a long and convoluted evolution, but this is slowly being cleaned up.
85 You can see examples of ones used in practice in <literal>lib.systems.examples</literal>; note how they are not all very consistent.
86 For now, here are few fields can count on them containing:
87 </para>
88 <variablelist>
89 <varlistentry>
90 <term><varname>system</varname></term>
91 <listitem>
92 <para>
93 This is a two-component shorthand for the platform.
94 Examples of this would be "x86_64-darwin" and "i686-linux"; see <literal>lib.systems.doubles</literal> for more.
95 This format isn't very standard, but has built-in support in Nix, such as the <varname>builtins.currentSystem</varname> impure string.
96 </para>
97 </listitem>
98 </varlistentry>
99 <varlistentry>
100 <term><varname>config</varname></term>
101 <listitem>
102 <para>
103 This is a 3- or 4- component shorthand for the platform.
104 Examples of this would be "x86_64-unknown-linux-gnu" and "aarch64-apple-darwin14".
105 This is a standard format called the "LLVM target triple", as they are pioneered by LLVM and traditionally just used for the <varname>targetPlatform</varname>.
106 This format is strictly more informative than the "Nix host double", as the previous format could analogously be termed.
107 This needs a better name than <varname>config</varname>!
108 </para>
109 </listitem>
110 </varlistentry>
111 <varlistentry>
112 <term><varname>parsed</varname></term>
113 <listitem>
114 <para>
115 This is a nix representation of a parsed LLVM target triple with white-listed components.
116 This can be specified directly, or actually parsed from the <varname>config</varname>.
117 [Technically, only one need be specified and the others can be inferred, though the precision of inference may not be very good.]
118 See <literal>lib.systems.parse</literal> for the exact representation.
119 </para>
120 </listitem>
121 </varlistentry>
122 <varlistentry>
123 <term><varname>libc</varname></term>
124 <listitem>
125 <para>
126 This is a string identifying the standard C library used.
127 Valid identifiers include "glibc" for GNU libc, "libSystem" for Darwin's Libsystem, and "uclibc" for µClibc.
128 It should probably be refactored to use the module system, like <varname>parse</varname>.
129 </para>
130 </listitem>
131 </varlistentry>
132 <varlistentry>
133 <term><varname>is*</varname></term>
134 <listitem>
135 <para>
136 These predicates are defined in <literal>lib.systems.inspect</literal>, and slapped on every platform.
137 They are superior to the ones in <varname>stdenv</varname> as they force the user to be explicit about which platform they are inspecting.
138 Please use these instead of those.
139 </para>
140 </listitem>
141 </varlistentry>
142 <varlistentry>
143 <term><varname>platform</varname></term>
144 <listitem>
145 <para>
146 This is, quite frankly, a dumping ground of ad-hoc settings (it's an attribute set).
147 See <literal>lib.systems.platforms</literal> for examples—there's hopefully one in there that will work verbatim for each platform that is working.
148 Please help us triage these flags and give them better homes!
149 </para>
150 </listitem>
151 </varlistentry>
152 </variablelist>
153 </section>
154
155 <section>
156 <title>Specifying Dependencies</title>
157 <para>
158 As mentioned in the introduction to this chapter, one can think about a build time vs run time distinction whether cross-compiling or not.
159 In the case of cross-compilation, this corresponds with whether a derivation running on the native or foreign platform is produced.
160 An interesting thing to think about is how this corresponds with the three Autoconf platforms.
161 In the run-time case, the depending and depended-on package simply have matching build, host, and target platforms.
162 But in the build-time case, one can imagine "sliding" the platforms one over.
163 The depended-on package's host and target platforms (respectively) become the depending package's build and host platforms.
164 This is the most important guiding principle behind cross-compilation with Nixpkgs, and will be called the <wordasword>sliding window principle</wordasword>.
165 In this manner, given the 3 platforms for one package, we can determine the three platforms for all its transitive dependencies.
166 </para>
167 <para>
168 Some examples will probably make this clearer.
169 If a package is being built with a <literal>(build, host, target)</literal> platform triple of <literal>(foo, bar, bar)</literal>, then its build-time dependencies would have a triple of <literal>(foo, foo, bar)</literal>, and <emphasis>those packages'</emphasis> build-time dependencies would have triple of <literal>(foo, foo, foo)</literal>.
170 In other words, it should take two "rounds" of following build-time dependency edges before one reaches a fixed point where, by the sliding window principle, the platform triple no longer changes.
171 Indeed, this happens with cross compilation, where only rounds of native dependencies starting with the second necessarily coincide with native packages.
172 </para>
173 <note><para>
174 The depending package's target platform is unconstrained by the sliding window principle, which makes sense in that one can in principle build cross compilers targeting arbitrary platforms.
175 </para></note>
176 <para>
177 How does this work in practice? Nixpkgs is now structured so that build-time dependencies are taken from <varname>buildPackages</varname>, whereas run-time dependencies are taken from the top level attribute set.
178 For example, <varname>buildPackages.gcc</varname> should be used at build time, while <varname>gcc</varname> should be used at run time.
179 Now, for most of Nixpkgs's history, there was no <varname>buildPackages</varname>, and most packages have not been refactored to use it explicitly.
180 Instead, one can use the four attributes used for specifying dependencies as documented in <xref linkend="ssec-stdenv-attributes"/>.
181 We "splice" together the run-time and build-time package sets with <varname>callPackage</varname>, and then <varname>mkDerivation</varname> for each of four attributes pulls the right derivation out.
182 This splicing can be skipped when not cross compiling as the package sets are the same, but is a bit slow for cross compiling.
183 Because of this, a best-of-both-worlds solution is in the works with no splicing or explicit access of <varname>buildPackages</varname> needed.
184 For now, feel free to use either method.
185 </para>
186 <note><para>
187 There is also a "backlink" <varname>__targetPackages</varname>, yielding a package set whose <varname>buildPackages</varname> is the current package set.
188 This is a hack, though, to accommodate compilers with lousy build systems.
189 Please do not use this unless you are absolutely sure you are packaging such a compiler and there is no other way.
190 </para></note>
191 </section>
192
193</section>
194
195<!--============================================================-->
196
197<section xml:id="sec-cross-usage">
198 <title>Cross-building packages</title>
199 <note><para>
200 More information needs to moved from the old wiki, especially <link xlink:href="https://nixos.org/wiki/CrossCompiling" />, for this section.
201 </para></note>
202 <para>
203 Nixpkgs can be instantiated with <varname>localSystem</varname> alone, in which case there is no cross compiling and everything is built by and for that system,
204 or also with <varname>crossSystem</varname>, in which case packages run on the latter, but all building happens on the former.
205 Both parameters take the same schema as the 3 (build, host, and target) platforms defined in the previous section.
206 As mentioned above, <literal>lib.systems.examples</literal> has some platforms which are used as arguments for these parameters in practice.
207 You can use them programmatically, or on the command line like <command>nix-build <nixpkgs> --arg crossSystem '(import <nixpkgs/lib>).systems.examples.fooBarBaz'</command>.
208 </para>
209 <para>
210 While one is free to pass both parameters in full, there's a lot of logic to fill in missing fields.
211 As discussed in the previous section, only one of <varname>system</varname>, <varname>config</varname>, and <varname>parsed</varname> is needed to infer the other two.
212 Additionally, <varname>libc</varname> will be inferred from <varname>parse</varname>.
213 Finally, <literal>localSystem.system</literal> is also <emphasis>impurely</emphasis> inferred based on the platform evaluation occurs.
214 This means it is often not necessary to pass <varname>localSystem</varname> at all, as in the command-line example in the previous paragraph.
215 </para>
216 <note>
217 <para>
218 Many sources (manual, wiki, etc) probably mention passing <varname>system</varname>, <varname>platform</varname>, along with the optional <varname>crossSystem</varname> to nixpkgs:
219 <literal>import <nixpkgs> { system = ..; platform = ..; crossSystem = ..; }</literal>.
220 Passing those two instead of <varname>localSystem</varname> is still supported for compatibility, but is discouraged.
221 Indeed, much of the inference we do for these parameters is motivated by compatibility as much as convenience.
222 </para>
223 </note>
224 <para>
225 One would think that <varname>localSystem</varname> and <varname>crossSystem</varname> overlap horribly with the three <varname>*Platforms</varname> (<varname>buildPlatform</varname>, <varname>hostPlatform,</varname> and <varname>targetPlatform</varname>; see <varname>stage.nix</varname> or the manual).
226 Actually, those identifiers are purposefully not used here to draw a subtle but important distinction:
227 While the granularity of having 3 platforms is necessary to properly *build* packages, it is overkill for specifying the user's *intent* when making a build plan or package set.
228 A simple "build vs deploy" dichotomy is adequate: the sliding window principle described in the previous section shows how to interpolate between the these two "end points" to get the 3 platform triple for each bootstrapping stage.
229 That means for any package a given package set, even those not bound on the top level but only reachable via dependencies or <varname>buildPackages</varname>, the three platforms will be defined as one of <varname>localSystem</varname> or <varname>crossSystem</varname>, with the former replacing the latter as one traverses build-time dependencies.
230 A last simple difference then is <varname>crossSystem</varname> should be null when one doesn't want to cross-compile, while the <varname>*Platform</varname>s are always non-null.
231 <varname>localSystem</varname> is always non-null.
232 </para>
233</section>
234
235<!--============================================================-->
236
237<section xml:id="sec-cross-infra">
238 <title>Cross-compilation infrastructure</title>
239 <para>To be written.</para>
240 <note><para>
241 If one explores nixpkgs, they will see derivations with names like <literal>gccCross</literal>.
242 Such <literal>*Cross</literal> derivations is a holdover from before we properly distinguished between the host and target platforms
243 —the derivation with "Cross" in the name covered the <literal>build = host != target</literal> case, while the other covered the <literal>host = target</literal>, with build platform the same or not based on whether one was using its <literal>.nativeDrv</literal> or <literal>.crossDrv</literal>.
244 This ugliness will disappear soon.
245 </para></note>
246</section>
247
248</chapter>