From 9d3108c3aee8214d26218e8c2be3b4d497246fbe Mon Sep 17 00:00:00 2001 From: Matthew Bauer Date: Sun, 18 Nov 2018 23:23:22 -0600 Subject: [PATCH] doc/cross-compilation: fixup More cleanups and stuff. May need to be split up. --- doc/cross-compilation.xml | 188 +++++++++++++++++++------------------- doc/stdenv.xml | 8 +- 2 files changed, 98 insertions(+), 98 deletions(-) diff --git a/doc/cross-compilation.xml b/doc/cross-compilation.xml index 77cbf44fb20..ac68e6760bb 100644 --- a/doc/cross-compilation.xml +++ b/doc/cross-compilation.xml @@ -6,17 +6,17 @@ Introduction - "Cross-compilation" means compiling a program on one machine for another - type of machine. For example, a typical use of cross compilation is to - compile programs for embedded devices. These devices often don't have the - computing power and memory to compile their own programs. 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. Nixpkgs is - increasingly adopting the opinion 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. + "Cross-compilation" means compiling a program on one machine for another type + of machine. For example, a typical use of cross-compilation is to compile + programs for embedded devices. These devices often don't have the computing + power and memory to compile their own programs. One might think that + cross-compilation is a fairly niche concern. However, there are significant + advantages to rigorously distinguishing between build-time and run-time + environments! This applies even when one is developing and deploying on the + same machine. Nixpkgs is increasingly adopting the opinion 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. @@ -34,15 +34,15 @@ Platform parameters - Nixpkgs follows the - common - historical convention of GNU autoconf of distinguishing between 3 - types of platform: build, - host, and target. In - summary, build is the platform on which a package - is being built, host is the platform on which it - is to run. The third attribute, target, is - relevant only for certain specific compilers and build tools. + Nixpkgs follows the conventions + of GNU autoconf. We distinguish between 3 types of platforms when + building a derivation: build, + host, and target. In + summary, build is the platform on which a package + is being built, host is the platform on which it + will run. The third attribute, target, is relevant + only for certain specific compilers and build tools. @@ -64,7 +64,7 @@ The "build platform" is the platform on which a package is built. Once someone has a built package, or pre-built binary package, the build - platform should not matter and be safe to ignore. + platform should not matter and can be ignored. @@ -94,11 +94,11 @@ The build process of certain compilers is written in such a way that the compiler resulting from a single build can itself only produce binaries - for a single platform. The task specifying this single "target platform" - is thus pushed to build time of the compiler. The root cause of this - mistake is often that the compiler (which will be run on the host) and - the the standard library/runtime (which will be run on the target) are - built by a single build process. + for a single platform. The task of specifying this single "target + platform" is thus pushed to build time of the compiler. The root cause of + this that the compiler (which will be run on the host) and the standard + library/runtime (which will be run on the target) are built by a single + build process. There is no fundamental need to think about a single target ahead of @@ -135,8 +135,10 @@ 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 + lib.systems.doubles for more. The first component + corresponds to the CPU architecture of the platform and the second to the + operating system of the platform ([cpu]-[os]). This + format has built-in support in Nix, such as the builtins.currentSystem impure string. @@ -147,12 +149,13 @@ - 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 + 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. In the + 4-part form, this corresponds to + [cpu]-[vendor]-[os]-[abi]. 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! @@ -164,12 +167,11 @@ - 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. + 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. See + lib.systems.parse for the exact + representation. @@ -249,17 +251,17 @@ - Some examples will probably make this clearer. If a package is being built - with a (build, host, target) platform triple of - (foo, bar, bar), then its build-time dependencies would - have a triple of (foo, foo, bar), and those - packages' build-time dependencies would have triple of - (foo, foo, foo). 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. + Some examples will make this clearer. If a package is being built with a + (build, host, target) platform triple of (foo, + bar, bar), then its build-time dependencies would have a triple of + (foo, foo, bar), and those packages' + build-time dependencies would have a triple of (foo, foo, + foo). 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. @@ -271,23 +273,23 @@ - How does this work in practice? Nixpkgs is now structured so that - build-time dependencies are taken from buildPackages, - whereas run-time dependencies are taken from the top level attribute set. - For example, buildPackages.gcc should be used at build - time, while gcc should be used at run time. Now, for - most of Nixpkgs's history, there was no buildPackages, - and most packages have not been refactored to use it explicitly. Instead, - one can use the six (gasp) attributes used for - specifying dependencies as documented in - . We "splice" together the - run-time and build-time package sets with callPackage, - and then mkDerivation for each of four attributes pulls - the right derivation out. This splicing can be skipped when not cross - compiling as the package sets are the same, but is a bit slow for cross - compiling. Because of this, a best-of-both-worlds solution is in the works - with no splicing or explicit access of buildPackages - needed. For now, feel free to use either method. + How does this work in practice? Nixpkgs is now structured so that build-time + dependencies are taken from buildPackages, whereas + run-time dependencies are taken from the top level attribute set. For + example, buildPackages.gcc should be used at build-time, + while gcc should be used at run-time. Now, for most of + Nixpkgs's history, there was no buildPackages, and most + packages have not been refactored to use it explicitly. Instead, one can use + the six (gasp) attributes used for specifying + dependencies as documented in . We + "splice" together the run-time and build-time package sets with + callPackage, and then mkDerivation for + each of four attributes pulls the right derivation out. This splicing can be + skipped when not cross-compiling as the package sets are the same, but is a + bit slow for cross-compiling. Because of this, a best-of-both-worlds + solution is in the works with no splicing or explicit access of + buildPackages needed. For now, feel free to use either + method. @@ -305,11 +307,11 @@ Cross packaging cookbook - Some frequently problems when packaging for cross compilation are good to - just spell and answer. Ideally the information above is exhaustive, so this - section cannot provide any new information, but its ludicrous and cruel to - expect everyone to spend effort working through the interaction of many - features just to figure out the same answer to the same common problem. + Some frequently encountered problems when packaging for cross-compilation + should be answered here. Ideally, the information above is exhaustive, so + this section cannot provide any new information, but it is ludicrous and + cruel to expect everyone to spend effort working through the interaction of + many features just to figure out the same answer to the same common problem. Feel free to add to this list! @@ -366,15 +368,14 @@ - More information needs to moved from the old wiki, especially - , for this - section. + More information needs to be moved from the old wiki, especially , for this section. Nixpkgs can be instantiated with localSystem alone, in - which case there is no cross compiling and everything is built by and for + which case there is no cross-compiling and everything is built by and for that system, or also with crossSystem, 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 @@ -440,15 +441,14 @@ nix-build <nixpkgs> --arg crossSystem.config '<arch>-<os>-< 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 buildPackages, the three platforms will - be defined as one of localSystem or - crossSystem, with the former replacing the latter as one - traverses build-time dependencies. A last simple difference then is - crossSystem should be null when one doesn't want to - cross-compile, while the *Platforms are always non-null. - localSystem is always non-null. + 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 + buildPackages, the three platforms will be defined as one + of localSystem or crossSystem, with the + former replacing the latter as one traverses build-time dependencies. A last + simple difference is that crossSystem should be null when + one doesn't want to cross-compile, while the *Platforms + are always non-null. localSystem is always non-null. @@ -461,14 +461,14 @@ nix-build <nixpkgs> --arg crossSystem.config '<arch>-<os>-< - If one explores nixpkgs, they will see derivations with names like - gccCross. Such *Cross derivations is - a holdover from before we properly distinguished between the host and - target platforms —the derivation with "Cross" in the name covered the - build = host != target case, while the other covered the - host = target, with build platform the same or not based - on whether one was using its .nativeDrv or - .crossDrv. This ugliness will disappear soon. + If one explores Nixpkgs, they will see derivations with names like + gccCross. Such *Cross derivations is a + holdover from before we properly distinguished between the host and target + platforms—the derivation with "Cross" in the name covered the build + = host != target case, while the other covered the host = + target, with build platform the same or not based on whether one + was using its .nativeDrv or .crossDrv. + This ugliness will disappear soon. diff --git a/doc/stdenv.xml b/doc/stdenv.xml index 10d58f38399..208b5e9cf30 100644 --- a/doc/stdenv.xml +++ b/doc/stdenv.xml @@ -258,15 +258,15 @@ genericBuild - It is important to note dependencies are not necessarily propagated as the - same sort of dependency that they were before, but rather as the + It is important to note that dependencies are not necessarily propagated as + the same sort of dependency that they were before, but rather as the corresponding sort so that the platform rules still line up. The exact rules for dependency propagation can be given by assigning to each dependency two integers based one how its host and target platforms are offset from the depending derivation's platforms. Those offsets are given below in the descriptions of each dependency list attribute. Algorithmically, we traverse propagated inputs, accumulating every propagated dependency's propagated - dependenciess and adjusting them to account for the "shift in perspective" + dependencies and adjusting them to account for the "shift in perspective" described by the current dependency's platform offsets. This results in sort a transitive closure of the dependency relation, with the offsets being approximately summed when two dependency links are combined. We also prune @@ -424,7 +424,7 @@ let f(h, h + 1, i) = i + h target offset from the new derivation's platforms. These are programs used at build time that produce code to run with code produced by the depending package. Most commonly, these are tools used to build the runtime or - standard library taht the currently-being-built compiler will inject into + standard library that the currently-being-built compiler will inject into any code it compiles. In many cases, the currently-being-built-compiler is itself employed for that task, but when that compiler won't run (i.e. its build and host platform differ) this is not possible. Other times, the