From c13457fe58c354ac2437b4380f27fca4b771c034 Mon Sep 17 00:00:00 2001 From: John Ericson Date: Mon, 17 Apr 2017 20:30:36 -0400 Subject: [PATCH] doc: Document the structure of `{build,host,target}Platforms` Worthwhile to do now that #24610 makes it less abysmal. --- doc/cross-compilation.xml | 59 +++++++++++++++++++++++++++++++++------ 1 file changed, 51 insertions(+), 8 deletions(-) diff --git a/doc/cross-compilation.xml b/doc/cross-compilation.xml index 8e981a4318e1..06a8919c2a19 100644 --- a/doc/cross-compilation.xml +++ b/doc/cross-compilation.xml @@ -37,16 +37,9 @@ In Nixpkgs, these three platforms are defined as attribute sets under the names buildPlatform, hostPlatform, and targetPlatform. - All are guaranteed to contain at least a platform field, which contains detailed information on the platform. All three are always defined at the top level, so one can get at them just like a dependency in a function that is imported with callPackage: { stdenv, buildPlatform, hostPlatform, fooDep, barDep, .. }: ... - - These platforms should all have the same structure in all scenarios, but that is currently not the case. - When not cross-compiling, they will each contain a system field with a short 2-part, hyphen-separated summering string name for the platform. - But, when when cross compiling, hostPlatform and targetPlatform may instead contain config with a fuller 3- or 4-part string in the manner of LLVM. - We should have all 3 platforms always contain both, and maybe give config a better name while we are at it. - buildPlatform @@ -83,7 +76,7 @@ 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. Tools like LLVM that don't need up-front target platforms can safely ignore it like normal packages, and it will do no harm. - + @@ -91,6 +84,56 @@ This field defined as hostPlatform when the host and build platforms differ, but otherwise not defined at all. This field is obsolete and will soon disappear—please do not use it. + + The exact scheme these fields is a bit ill-defined due to a long and convoluted evolution, but this is slowly being cleaned up. + For now, here are few fields can count on them containing: + + + + system + + + This is a two-component shorthand for the platform. + Examples of this would be "x86_64-darwin" and "i686-linux"; see lib.systems.doubles for more. + This format isn't very standard, but has built-in support in Nix, such as the builtins.currentSystem impure string. + + + + + config + + + This is a 3- or 4- component shorthand for the platform. + Examples of this would be "x86_64-unknown-linux-gnu" and "aarch64-apple-darwin14". + This is a standard format called the "LLVM target triple", as they are pioneered by LLVM and traditionally just used for the targetPlatform. + This format is strictly more informative than the "Nix host double", as the previous format could analogously be termed. + This needs a better name than config! + + + + + parsed + + + 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 config. + [Technically, only one need be specified and the others can be inferred, though the precision of inference may not be very good.] + See lib.systems.parse for the exact representation, along with some is*predicates. + These predicates are superior to the ones in stdenv as they aren't tied to the build platform (host, as previously discussed, would be a saner default). + + + + + platform + + + 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 one is working. + Please help us triage these flags and give them better homes! + + + +