diff options
author | John Ericson <Ericson2314@Yahoo.com> | 2017-05-23 18:04:15 -0400 |
---|---|---|
committer | John Ericson <Ericson2314@Yahoo.com> | 2017-05-29 18:56:03 -0400 |
commit | 20e756a0936fb75ce8f9d9ef0b7a511198bf7eea (patch) | |
tree | efe83f0252c5097c00fff2d67afc90c9d6dd7b42 /doc/cross-compilation.xml | |
parent | b20f20d3eb80de83abe5047c2ada9abad54ae0b6 (diff) |
lib: Consolidate platform configurations (used for crossSystem)
This is good for maintenance and education.
Diffstat (limited to 'doc/cross-compilation.xml')
-rw-r--r-- | doc/cross-compilation.xml | 52 |
1 files changed, 44 insertions, 8 deletions
diff --git a/doc/cross-compilation.xml b/doc/cross-compilation.xml index de1b9b80d300e..e99e90bac9c5a 100644 --- a/doc/cross-compilation.xml +++ b/doc/cross-compilation.xml @@ -85,7 +85,8 @@ This field is obsolete and will soon disappear—please do not use it. </para></note> <para> - The exact scheme these fields is a bit ill-defined due to a long and convoluted evolution, but this is slowly being cleaned up. + 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. + You can see examples of ones used in practice in <literal>lib.systems.examples</literal>; note how they are not all very consistent. For now, here are few fields can count on them containing: </para> <variablelist> @@ -118,8 +119,27 @@ This is a nix representation of a parsed LLVM target triple with white-listed components. This can be specified directly, or actually parsed from the <varname>config</varname>. [Technically, only one need be specified and the others can be inferred, though the precision of inference may not be very good.] - See <literal>lib.systems.parse</literal> for the exact representation, along with some <literal>is*</literal>predicates. - These predicates are superior to the ones in <varname>stdenv</varname> as they aren't tied to the build platform (host, as previously discussed, would be a saner default). + See <literal>lib.systems.parse</literal> for the exact representation. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>libc</varname></term> + <listitem> + <para> + This is a string identifying the standard C library used. + Valid identifiers include "glibc" for GNU libc, "libsystem" for Darwin's Libsystem, and "uclibc" for µClibc. + It should probably be refactored to use the module system, like <varname>parse</varname>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>is*</varname></term> + <listitem> + <para> + These predicates are defined in <literal>lib.systems.inspect</literal>, and slapped on every platform. + They are superior to the ones in <varname>stdenv</varname> as they force the user to be explicit about which platform they are inspecting. + Please use these instead of those. </para> </listitem> </varlistentry> @@ -128,7 +148,7 @@ <listitem> <para> This is, quite frankly, a dumping ground of ad-hoc settings (it's an attribute set). - See <literal>lib.systems.platforms</literal> for examples—there's hopefully one in there that will work verbatim for each platform one is working. + See <literal>lib.systems.platforms</literal> 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! </para> </listitem> @@ -184,12 +204,28 @@ 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. + 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, + or also with <varname>crossSystem</varname>, in which case packages run on the latter, but all building happens on the former. + Both parameters take the same schema as the 3 (build, host, and target) platforms defined in the previous section. + As mentioned above, <literal>lib.systems.examples</literal> has some platforms which are used as arguments for these parameters in practice. + You can use them programmatically, or on the command line like <command>nix-build <nixpkgs> --arg crossSystem '(import <nixpkgs/lib>).systems.examples.fooBarBaz'</command>. </para> <para> + While one is free to pass both parameters in full, there's a lot of logic to fill in missing fields. + 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. + Additionally, <varname>libc</varname> will be inferred from <varname>parse</varname>. + Finally, <literal>localSystem.system</literal> is also <emphasis>impurely</emphasis> inferred based on the platform evaluation occurs. + This means it is often not necessary to pass <varname>localSystem</varname> at all, as in the command-line example in the previous paragraph. + </para> + <note> + <para> + Many sources (manual, wiki, etc) probably mention passing <varname>system</varname>, <varname>platform</varname>, along with the optional <varname>crossSystem</varname> to nixpkgs: + <literal>import <nixpkgs> { system = ..; platform = ..; crossSystem = ..; }</literal>. + Passing those two instead of <varname>localSystem</varname> is still supported for compatibility, but is discouraged. + Indeed, much of the inference we do for these parameters is motivated by compatibility as much as convenience. + </para> + </note> + <para> 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. |