diff options
author | Vladimír Čunát <vcunat@gmail.com> | 2017-02-09 08:42:04 +0100 |
---|---|---|
committer | Vladimír Čunát <vcunat@gmail.com> | 2017-02-09 08:42:04 +0100 |
commit | 6bea415b5e3f4ab70afcea4c646ad76d9c073c89 (patch) | |
tree | 8f5e976cd8aecc6029b4019e16f0177e0a66a093 /doc | |
parent | b846a53d2a3cba3002a4d6fb064f579677eac52c (diff) | |
parent | 4bf9f8afc39e9d0c0629635652804b81fe3e3332 (diff) |
Merge branch 'master' into staging
Diffstat (limited to 'doc')
-rw-r--r-- | doc/cross-compilation.xml | 31 |
1 files changed, 23 insertions, 8 deletions
diff --git a/doc/cross-compilation.xml b/doc/cross-compilation.xml index e93d1a98f7fde..8e981a4318e18 100644 --- a/doc/cross-compilation.xml +++ b/doc/cross-compilation.xml @@ -25,7 +25,7 @@ <!--============================================================--> <section xml:id="sec-cross-packaging"> - <title>Packing in a cross-friendly manner</title> + <title>Packaging in a cross-friendly manner</title> <section> <title>Platform parameters</title> @@ -105,14 +105,15 @@ This is the most important guiding principle behind cross-compilation with Nixpkgs, and will be called the <wordasword>sliding window principle</wordasword>. In this manner, given the 3 platforms for one package, we can determine the three platforms for all its transitive dependencies. </para> + <para> + Some examples will probably make this clearer. + 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>. + 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. + Indeed, this happens with cross compilation, where only rounds of native dependencies starting with the second necessarily coincide with native packages. + </para> <note><para> 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. </para></note> - <warning><para> - From the above, one would surmise that 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>. - 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. - Unfortunately, at the moment, we do <emphasis>not</emphasis> implement this correctly, and after only one round of following build-time dependencies is the fixed point reached, with target incorrectly kept different than the others. - </para></warning> <para> How does this work in practice? Nixpkgs is now structured so that build-time dependencies are taken from from <varname>buildPackages</varname>, whereas run-time dependencies are taken from the top level attribute set. For example, <varname>buildPackages.gcc</varname> should be used at build time, while <varname>gcc</varname> should be used at run time. @@ -131,9 +132,23 @@ <section xml:id="sec-cross-usage"> <title>Cross-building packages</title> + <note><para> + More information needs to moved from the old wiki, especially <link xlink:href="https://nixos.org/wiki/CrossCompiling" />, for this section. + </para></note> + <para> + Many sources (manual, wiki, etc) probably mention passing <varname>system</varname>, <varname>platform</varname>, and, optionally, <varname>crossSystem</varname> to nixpkgs: + <literal>import <nixpkgs> { system = ..; platform = ..; crossSystem = ..; }</literal>. + <varname>system</varname> and <varname>platform</varname> together determine the system on which packages are built, and <varname>crossSystem</varname> specifies the platform on which packages are ultimately intended to run, if it is different. + This still works, but with more recent changes, one can alternatively pass <varname>localSystem</varname>, containing <varname>system</varname> and <varname>platform</varname>, for symmetry. + </para> <para> - To be written. - This is basically unchanged so see the old wiki for now. + 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). + Actually, those identifiers are purposefully not used here to draw a subtle but important distinction: + 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. + 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. + 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. + 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. + <varname>localSystem</varname> is always non-null. </para> </section> |